[Python-checkins] distutils2: started setupcfg-spec

[Ezio Melotti]

Hi,

On 15/03/2011 21.18, tarek.ziade wrote:
> http://hg.python.org/distutils2/rev/6fca65ff60ad
> changeset:   1119:6fca65ff60ad
> user:        Tarek Ziade<tarek at ziade.org>
> date:        Tue Mar 15 15:18:39 2011 -0400
> summary:
>    started setupcfg-spec
>
> files:
>    docs/source/index.rst
>    docs/source/setupcfg-spec.rst
>
> diff --git a/docs/source/index.rst b/docs/source/index.rst
> --- a/docs/source/index.rst
> +++ b/docs/source/index.rst
> @@ -48,8 +48,11 @@
>     A guide for for end-users wanting to install a Python application or
>     library.
>
> +:doc:`setupcfg-spec`
> +  Specifications of setup.cfg, the most important file for developers.
> +
>   :doc:`setupcfg`
> -  Specifications of setup.cfg, the most important file for developers.
> +  Documenation about using setup.cfg

s/Documenation/Documentation/


>
>   :doc:`tutorial`
>     A tutorial for Python developers to discover Distutils2 main features.
> @@ -71,6 +74,7 @@
>
>      devresources
>      install/index
> +   setupcfg-spec
>      setupcfg
>      tutorial
>      distutils/index
> diff --git a/docs/source/setupcfg-spec.rst b/docs/source/setupcfg-spec.rst
> new file mode 100644
> --- /dev/null
> +++ b/docs/source/setupcfg-spec.rst
> [...]
> +
> +Description of sections and fields
> +==================================
> +
> +Each section contains a description of its options.
> +
> +- Options that are marked *\*multi* can have multiple values, one value per
> +  line.
> +- Options that are marked *\*optional* can be omited.

s/omited/omitted/

> +
> +
> +The sections are:
> +
> +global
> +    Global options for Distutils2.
> +
> +metadata
> +    The metadata section contains the metadata for the project as described in
> +    :PEP:`345`.
> +
> +files
> +    Declaration of package files included in the project.
> +
> +`command` sections
> +    Redefinition of user options for Distutils2 commands.
> +
> +[...]
> +
> +Changes in the specification
> +============================
> +
> +The version scheme for this specification is **MAJOR.MINOR**.
> +Changes in the specification will increment the version.
> +
> +- minor version changes (1.x): backwards compatible
> + - new fields and sections (both optional and mandatory) can be added
> + - optional fields can be removed
> +- major channges (2.X): backwards-incompatible

s/channges/changes/

> + - mandatory fields/sections are removed
> + - fields change their meaning
> +
> +As a consequence, a tool written to consume 1.X (say, X=5) has these
> +properties:
> +
> +- reading 1.Y, Y<X (e.g. 1.1) is possible, since the tool knows what
> +  optional fields weren't there
> +- reading 1.Y, Y>X is also possible. The tool will just ignore the new
> +  fields (even if they are mandatory in that version)
> +  If optional fields were removed, the tool will just consider them absent.
> +- reading 2.X is not possible; the tool should refuse to interpret
> +  the file.
> +
> +A tool written to produce 1.X should have these properties:
> +- it will write all mandatory fields
> +- it may write optional fields
> +
> +Acks
> +====
> +
> +XXX

Best Regards,
Ezio Melotti