Description

Incremental =========== |pypi| |calver| |gha| |coverage| Incremental is a `CalVer <https://calver.org/>`_ version manager supports the future. API documentation can be found `here <https://twisted.org/incremental/docs/>`_. Narrative documentation follows. .. contents:: Theory of Operation ------------------- - A version number has the form YY.MM.PATCH. - If your project is named "Shrubbery", its code is found in ``shrubbery/`` or ``src/shrubbery/``. - Incremental stores your project's version number in ``{src/}shrubbery/_version.py``. - To update the version, run ``incremental update Shrubbery``, passing ``--rc`` and/or ``--patch`` as appropriate (see `Updating`_, below). - Changing the version also updates any `indeterminate versions`_ in your codebase, like "Shrubbery NEXT", so you can reference the upcoming release in documentation. That's how Incremental supports the future. Quick Start ----------- Using setuptools ~~~~~~~~~~~~~~~~ Add Incremental to your ``pyproject.toml``: .. code-block:: toml [build-system] requires = [ "setuptools", "incremental>=24.7.2", # ← Add incremental as a build dependency ] build-backend = "setuptools.build_meta" [project] name = "<projectname>" dynamic = ["version"] # ← Mark the version dynamic dependencies = [ "incremental>=24.7.2", # ← Depend on incremental at runtime ] # ... [tool.incremental] # ← Activate Incremental's setuptools plugin It's fine if the ``[tool.incremental]`` table is empty, but it must be present. Remove any ``[project] version =`` entry and any ``[tool.setuptools.dynamic] version =`` entry. Next, `initialize the project`_. Using Hatchling ~~~~~~~~~~~~~~~ If you're using `Hatchling <https://hatch.pypa.io/>`_ to package your project, activate Incremental's Hatchling plugin by altering your ``pyproject.toml``: .. code:: toml [build-system] requires = [ "hatchling", "incremental>=24.7.2", # ← Add incremental as a build dependency ] build-backend = "hatchling.build" [project] name = "<projectname>" dynamic = ["version"] # ← Mark the version dynamic dependencies = [ "incremental>=24.7.2", # ← Depend on incremental at runtime ] # ... [tool.hatch.version] source = "incremental" # ← Activate Incremental's Hatchling plugin Incremental can be configured as usual in an optional ``[tool.incremental]`` table. The ``hatch version`` command will report the Incremental-managed version. Use the ``incremental update`` command to change the version (setting it with ``hatch version`` is not supported). Next, `initialize the project`_. Using ``setup.py`` ~~~~~~~~~~~~~~~~~~ Incremental may be used from ``setup.py`` instead of ``pyproject.toml``. Add this to your ``setup()`` call, removing any other versioning arguments: .. code:: python setup( use_incremental=True, setup_requires=['incremental'], install_requires=['incremental'], # along with any other install dependencies ... } Then `initialize the project`_. Initialize the project ~~~~~~~~~~~~~~~~~~~~~~ Install Incremental to your local environment with ``pipx install incremental``. Then run ``incremental update <projectname> --create``. It will create a file in your package named ``_version.py`` like this: .. code:: python from incremental import Version __version__ = Version("<projectname>", 24, 1, 0) __all__ = ["__version__"] Subsequent installations of your project will then use Incremental for versioning. Runtime integration ~~~~~~~~~~~~~~~~~~~ You may expose the ``incremental.Version`` from ``_version.py`` in your package's API. To do so, add to your root package's ``__init__.py``: .. code:: python from ._version import __version__ .. note:: Providing a ``__version__`` attribute is falling out of fashion following the introduction of `importlib.metadata.version() <https://docs.python.org/3/library/importlib.metadata.html#distribution-versions>`_ in Python 3.6, which can retrieve an installed package's version. If you don't expose this object publicly, nor make use of it within your package, then there is no need to depend on Incremental at runtime. You can remove it from your project's ``dependencies`` array (or, in ``setup.py``, from ``install_requires``). Incremental Versions -------------------- ``incremental.Version`` is a class that represents a version of a given project. It is made up of the following elements (which are given during instantiation): - ``package`` (required), the name of the package this ``Version`` represents. - ``major``, ``minor``, ``micro`` (all required), the X.Y.Z of your project's ``Version``. - ``release_candidate`` (optional), set to 0 or higher to mark this ``Version`` being of a release candidate (also sometimes called a "prerelease"). - ``post`` (optional), set to 0 or higher to mark this ``Version`` as a postrel