diff --git a/source/discussions/index.rst b/source/discussions/index.rst index d262bcff2..1f5ff1f2b 100644 --- a/source/discussions/index.rst +++ b/source/discussions/index.rst @@ -16,3 +16,4 @@ specific topic. If you're just trying to get stuff done, see package-formats src-layout-vs-flat-layout setup-py-deprecated + single-source-version diff --git a/source/discussions/single-source-version.rst b/source/discussions/single-source-version.rst new file mode 100644 index 000000000..9bcab6291 --- /dev/null +++ b/source/discussions/single-source-version.rst @@ -0,0 +1,47 @@ +.. _`Single sourcing the version discussion`: + +=================================== +Single-sourcing the Project Version +=================================== + +:Page Status: Complete +:Last Reviewed: 2024-08-24 + +One of the challenges in building packages is that the version string can be required in multiple places. + +* It needs to be specified when building the package (e.g. in :file:`pyproject.toml`) + This will make it available in the installed package’s metadata, from where it will be accessible at runtime using ``importlib.metadata.version("distribution_name")``. + +* A package may set a module attribute (e.g., ``__version__``) to provide an alternative means of runtime access to the version of the imported package. If this is done, the value of the attribute and that used by the build system to set the distribution's version should be kept in sync in :ref:`the build systems's recommended way `. + +* If the code is in in a version control system (VCS), e.g. Git, the version may appear in a *tag* such as ``v1.2.3``. + +To ensure that version numbers do not get out of sync, it is recommended that there is a single source of truth for the version number. + +In general, the options are: + +1) If the code is in a version control system (VCS), e.g. Git, then the version can be extracted from the VCS. + +2) The version can be hard-coded into the :file:`pyproject.toml` file -- and the build system can copy it into other locations it may be required. + +3) The version string can be hard-coded into the source code -- either in a special purpose file, such as :file:`_version.txt`, or as a attribute in a module, such as :file:`__init__.py`, and the build system can extract it at build time. + + +Consult your build system's documentation for their recommended method. + +.. _Build system version handling: + +Build System Version Handling +----------------------------- + +The following are links to some build system's documentation for handling version strings. + +* `Flit `_ + +* `Hatchling `_ + +* `PDM `_ + +* `Setuptools `_ + + - `setuptools_scm `_