Commits

Éric Araujo committed 566a417

Use an annex for rejected ideas

Comments (0)

Files changed (1)

new-config-file.rst

 Files listed in that field are automatically added to distributions.
 
 
-Get values from hooks
----------------------
-
-Some users would like to specify callback functions instead of writing some
-values, to avoid repetition. Let’s take ``version`` as example. It is very
-common to have it stored as a tag in version control, and there are a number of
-helper functions to get this information. We could have this kind of field::
-
-  [metadata]
-  get-version = _buildhelper.get_hg_version
-
-Tarek strongly disagrees with this proposal, since it conflicts with the point
-of having static metadata. If the metadata is fully defined by a file format,
-then any tool in any language can follow the specification [#]_ to implement a
-parser and do useful things with the values, without depending on Distutils2,
-setup scripts or Python at all. People who really cannot write the version
-number in :file:`setup.cfg` for some reason can still use a :file:`setup.py`
-and benefit from fixes and features in Distutils2, but they won’t be static
-metadata-compliant.
-
-.. [#] Not this work-in-progress document, but a better one evolved from it.
-
-Furthermore, the version example is not a strong argument. When doing a
-release, updating the version number in :file:`setup.cfg` is but a minor and
-quick step. Documentation needs to be checked, translations built, the version
-number has to be updated in :file:`README`, :file:`NEWS` or :file:`CHANGES`,
-source code, so using a hook to set version in :file:`setup.cfg` would remove
-only one tidbit of work.
-
-Other fields may be duplicated in documentation files and :file:`setup.cfg`,
-i.e. author, summary and project URIs, but this duplication has a very small
-cost. Dependencies, classifiers and keywords are only in :file:`setup.cfg`, so
-wouldn’t benefit from hooks at all.
-
-In conclusion, I suggest to explore other solutions: Use a version control
-hook to edit :file:`setup.cfg` when a special tag is created, or use a shell
-function to create the tag from the value in :file:`setup.cfg`. People who
-love automation typically write a small script or makefile to do all
-operations related to a release (adjust version numbers in relevant files, run
-lint tools, run i18n tools, etc.), then check if the result look good (not
-always trusting automated tools is sane), commit, tag, push, send
-announcements, register the release in catalogs and so on.
-
-
 Fix misnamed fields
 -------------------
 
 ============================ ==============================
 
 
+Annex: Rejected ideas
+"""""""""""""""""""""
+
+Get metadata from hooks
+-----------------------
+
+Some users would like to specify callback functions instead of writing some
+values, to avoid repetition. Let’s take ``version`` as example. It is very
+common to have it stored as a tag in version control, and there are a number of
+helper functions to get this information. We could have this kind of field::
+
+  [metadata]
+  get-version = _buildhelper.get_hg_version
+
+This proposal has to be rejected, since it strongly conflicts with the point
+of having static metadata. If the metadata is fully defined by a file format,
+then any tool in any language can follow the specification to implement a
+parser and do useful things with the values, without depending on Distutils2,
+setup scripts or Python at all. People who really cannot write the version
+number in :file:`setup.cfg` for some reason can still use a :file:`setup.py`
+and benefit from fixes and features in Distutils2, but they won’t be static
+metadata-compliant.
+
+Furthermore, the version example is not a strong argument. When doing a
+release, updating the version number in :file:`setup.cfg` is but a minor and
+quick step. Documentation needs to be checked, translations built, the version
+number has to be updated in :file:`README`, :file:`NEWS` or :file:`CHANGES`,
+source code, so using a hook to set version in :file:`setup.cfg` would remove
+only one tidbit of work.
+
+Other fields may be duplicated in documentation files and :file:`setup.cfg`,
+i.e. author, summary and project URIs, but this duplication has a very small
+cost. Dependencies, classifiers and keywords are only in :file:`setup.cfg`, so
+wouldn’t benefit from hooks at all.
+
+In conclusion, other solutions can be explored. Since the version number is
+easily retrieved from :file:`setup.cfg`, a trivial shell function can be
+written to create the VCS tag from the static metadata. People who love
+automation typically write a small script or makefile to do all operations
+related to a release (adjust version numbers in relevant files, run lint
+tools, run i18n tools, etc.), then check if the result look good (not always
+trusting automated tools is sane), commit, tag, push, send announcements,
+register the release in catalogs and so on.
+
+
 .. Footnotes and References
    """"""""""""""""""""""""
 .. _source directory: `replacing package_dir`_
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.