diff --git a/CHANGELOG.md b/CHANGELOG.md index 847e2b7..d5097a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ v2.3.0 (in development) ----------------------- - Always read `.hg_archival.txt` files using UTF-8 encoding +- Added support for using versioningit with [Hatch](https://hatch.pypa.io) v2.2.1 (2023-09-22) ------------------- diff --git a/README.rst b/README.rst index 2472dff..cd09224 100644 --- a/README.rst +++ b/README.rst @@ -41,6 +41,10 @@ calculation. - Supports Git, modern Git archives, and Mercurial +- *(New in version 2.3.0)* `Works with Hatch`__ + + __ https://versioningit.readthedocs.io/en/stable/hatch.html + - Formatting of the final version uses format template strings, with fields for basic VCS information and separate template strings for distanced vs. dirty vs. distanced-and-dirty repository states diff --git a/docs/api.rst b/docs/api.rst index 981e960..84524df 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -3,8 +3,8 @@ Library API =========== -High-Level Functions --------------------- +High-Level Functions and Classes +-------------------------------- .. autofunction:: get_version .. autofunction:: get_next_version diff --git a/docs/changelog.rst b/docs/changelog.rst index 264556e..42e433c 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -6,6 +6,7 @@ Changelog v2.3.0 (in development) ----------------------- - Always read :file:`.hg_archival.txt` files using UTF-8 encoding +- Added support for using versioningit with `Hatch `_ v2.2.1 (2023-09-22) diff --git a/docs/configuration.rst b/docs/configuration.rst index 10b526f..9e5c2d6 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -498,6 +498,18 @@ which takes the following parameters: This file should not be committed to version control, but it should be included in your project's built sdists and wheels. + .. note:: + + If you're using Hatch and you followed the advice above by adding the + file to your :file:`.gitignore` or :file:`.hgignore`, then you will + need to tell Hatch to include the file in sdists & wheels like so: + + .. code:: toml + + [tool.hatch.build] + # Replace the path below with the value you gave to the "file" key: + artifacts = ["src/mypackage/_version.py"] + ``encoding`` : string *(optional)* The encoding with which to write the file. Defaults to UTF-8. @@ -675,10 +687,10 @@ time by running the ``versioningit`` command (See ":ref:`command`"). Log Level Environment Variable ------------------------------ -When ``versioningit`` is invoked via the setuptools plugin interface, it logs -various information to stderr. By default, only messages at ``WARNING`` level -or higher are displayed, but this can be changed by setting the -:envvar:`VERSIONINGIT_LOG_LEVEL` environment variable to the name of a Python -`logging level`_ (case insensitive) or the equivalent integer value. +When ``versioningit`` is invoked via the setuptools or Hatch plugin interface, +it logs various information to stderr. By default, only messages at +``WARNING`` level or higher are displayed, but this can be changed by setting +the :envvar:`VERSIONINGIT_LOG_LEVEL` environment variable to the name of a +Python `logging level`_ (case insensitive) or the equivalent integer value. .. _logging level: https://docs.python.org/3/library/logging.html#logging-levels diff --git a/docs/hatch.rst b/docs/hatch.rst new file mode 100644 index 0000000..f6386cd --- /dev/null +++ b/docs/hatch.rst @@ -0,0 +1,98 @@ +Hatch Integration +================= + +.. versionadded:: 2.3.0 + +If you're not a setuptools user, ``versioningit`` can also be used as a version +source plugin for the Hatch_ build backend. You use it in pretty much the same +way as for setuptools: + +.. _Hatch: https://hatch.pypa.io + +- Include ``versioningit`` in your build requirements like so: + + .. code:: toml + + [build-system] + requires = ["hatchling", "versioningit"] + build-backend = "hatchling.build" + +- Tell Hatch that you're using a dynamic version source by including + ``"version"`` in the ``project.dynamic`` key: + + .. code:: toml + + [project] + name = "your-project-name" + dynamic = ["version"] + # The rest of your project metadata follows after. + + # Do not set the `version` key in [project]. If it's currently set, + # remove it. + +- Tell Hatch to use ``versioningit`` as the version source: + + .. code:: toml + + [tool.hatch.version] + source = "versioningit" + +- Configure ``versioningit`` as normal. However, with Hatch, you have two + possible locations to put ``versioningit``'s configuration in: either a + ``[tool.versioningit]`` table as used with setuptools or under the + ``[tool.hatch.version]`` table. Moreover, unlike when using setuptools, you + don't even need the ``[tool.versioningit]`` table if it's just going to be + empty. + + For example, the following configurations are equivalent: + + - Using ``[tool.versioningit]``: + + .. code:: toml + + [tool.hatch.version] + source = "versioningit" + + [tool.versioningit] + default-version = "0.0.0+unknown" + + [tool.versioningit.format] + distance = "{next_version}.dev{distance}+{vcs}{rev}" + dirty = "{version}+dirty" + distance-dirty = "{next_version}.dev{distance}+{vcs}{rev}.dirty" + + - Using ``[tool.hatch.version]``: + + .. code:: toml + + [tool.hatch.version] + source = "versioningit" + default-version = "0.0.0+unknown" + + [tool.hatch.version.format] + distance = "{next_version}.dev{distance}+{vcs}{rev}" + dirty = "{version}+dirty" + distance-dirty = "{next_version}.dev{distance}+{vcs}{rev}.dirty" + + If you configure ``versioningit`` via ``[tool.hatch.version]`` and also + define a ``[tool.versioningit]`` table (even if it's empty), a warning will + be emitted, and only the ``[tool.hatch.version]`` configuration will be + used. + +- If you use the ``write`` step to create a file containing your project + version, and this file is listed in your :file:`.gitignore` or + :file:`.hgignore`, you will need to tell Hatch to include the file in sdists + & wheels like so: + + .. code:: toml + + [tool.hatch.build] + # Replace the path below with the path to the file created by the + # `write` step: + artifacts = ["src/mypackage/_version.py"] + +.. note:: + + If you use ``versioningit`` with Hatch, you will not be able to set your + project's version by running ``hatch version x.y.z``. Just create a tag + instead! diff --git a/docs/how.rst b/docs/how.rst index fa4c149..7fc7eea 100644 --- a/docs/how.rst +++ b/docs/how.rst @@ -4,7 +4,7 @@ How it Works ``versioningit`` divides its operation into seven :dfn:`steps`: ``vcs``, ``tag2version``, ``next-version``, ``format``, ``template-fields``, ``write``, and ``onbuild``. The first four steps make up the actual version calculation, -while the rest normally only happen while building with setuptools. +while the rest normally only happen while building with setuptools or Hatch. Version Calculation ------------------- @@ -34,25 +34,25 @@ The version for a given project is determined as follows: ``onbuild`` steps -Setuptools Integration ----------------------- +Build Integration +----------------- Setting the Version ^^^^^^^^^^^^^^^^^^^ -``versioningit`` registers a ``setuptools.finalize_distribution_options`` entry -point that causes it to be run whenever setuptools computes the metadata for a -project in an environment in which ``versioningit`` is installed. If the -project in question has a :file:`pyproject.toml` file with a -``[tool.versioningit]`` table, then ``versioningit`` performs the version -calculations described above and sets the project's version to the final value. -(If a version cannot be determined because the project is not in a repository -or repository archive, then ``versioningit`` will assume the project is an +``versioningit`` registers plugins with both setuptools and Hatch that cause it +to be run whenever one of those backends computes the metadata for a project in +an environment in which ``versioningit`` is installed. If the project in +question has a :file:`pyproject.toml` file with a ``[tool.versioningit]`` table +(or, for Hatch only, a ``[tool.hatch.version]`` table containing more than just +a ``source`` key), then ``versioningit`` performs the version calculations +described above and sets the project's version to the final value. (If a +version cannot be determined because the project is not in a repository or +repository archive, then ``versioningit`` will assume the project is an unpacked sdist and will look for a :file:`PKG-INFO` file to fetch the version -from instead.) If the :file:`pyproject.toml` contains a -``[tool.versioningit.write]`` table, then the ``write`` step will also be run -at this time; the default ``write`` method creates a file at a specified path -containing the project's version. +from instead.) If the configuration table contains a ``write`` subtable, then +the ``write`` step will also be run at this time; the default ``write`` method +creates a file at a specified path containing the project's version. ``onbuild`` Step ^^^^^^^^^^^^^^^^ diff --git a/docs/index.rst b/docs/index.rst index 6b08b5a..78a610c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,6 +16,7 @@ versioningit — Versioning It with your Version In Git how configuration runtime-version + hatch command api writing-methods @@ -34,6 +35,8 @@ calculation. - Supports Git, modern Git archives, and Mercurial +- *(New in version 2.3.0)* :doc:`Works with Hatch ` + - Formatting of the final version uses format template strings, with fields for basic VCS information and separate template strings for distanced vs. dirty vs. distanced-and-dirty repository states diff --git a/src/versioningit/__init__.py b/src/versioningit/__init__.py index 238ff22..289d438 100644 --- a/src/versioningit/__init__.py +++ b/src/versioningit/__init__.py @@ -12,6 +12,8 @@ - Supports Git, modern Git archives, and Mercurial +- *(New in version 2.3.0)* Works with Hatch + - Formatting of the final version uses format template strings, with fields for basic VCS information and separate template strings for distanced vs. dirty vs. distanced-and-dirty repository states