traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Rephrase the section about spec versioning

This commit is contained in:
Éric Araujo 2011-06-06 02:02:34 +02:00
parent 60533e03e9
commit a69ade81be
1 changed files with 19 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
Doc/packaging/setupcfg.rst
View File

@ -777,37 +777,36 @@ An extension field starts with ``X-``. Example::
Changes in the specification Changes in the specification
============================ ============================
The version scheme for this specification is **MAJOR.MINOR**. The versioning scheme for this specification is **MAJOR.MINOR**. Changes in the
Changes in the specification will increment the version. specification will cause the version number to be updated.
- minor version changes (1.x): backwards compatible Changes to the minor number reflect backwards-compatible changes:
- new fields and sections (both optional and mandatory) can be added - New fields and sections (optional or mandatory) can be added.
- optional fields can be removed - Optional fields can be removed.
- major channges (2.X): backwards-incompatible The major number will be incremented for backwards-incompatible changes:
- mandatory fields/sections are removed - Mandatory fields or sections are removed.
- fields change their meaning - Fields change their meaning.
As a consequence, a tool written to consume 1.X (say, X=5) has these As a consequence, a tool written to consume 1.5 has these properties:
properties:
- reading 1.Y, Y<X (e.g. 1.1) is possible, since the tool knows what - Can read 1.1, 1.2 and all versions < 1.5, since the tool knows what
optional fields weren't there 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: .. XXX clarify
- it will write all mandatory fields - Can also read 1.6 and other 1.x versions: The tool will just ignore fields it
- it may write optional fields doesn't know about, even if they are mandatory in the new version. If
optional fields were removed, the tool will just consider them absent.
- Cannot read 2.x and should refuse to interpret such files.
A tool written to produce 1.x should have these properties:
- Writes all mandatory fields.
- May write optional fields.
Acknowledgments Acknowledgments