Skip to content

dev_release_file.rst

Latest commit

 

History

History
214 lines (157 loc) · 6.98 KB

dev_release_file.rst

File metadata and controls

214 lines (157 loc) · 6.98 KB

Development releases (prereleases) from dev branch

For example, current repo state is:

commit 233f6d72 Dev branch commit (HEAD, dev)
|
|    commit 86269212 Release commit (v1.0.0, master)
|    |
|   commit e7bdbe51 Another commit
|    /
...
|
commit 273c47eb Long long ago
|
...

If you want to create development releases (prereleases) for the next planned version 1.1.0, so every commit to dev branch should produce version number like 1.1.0.dev123 (just plain increment) or even 1.1.0.dev123+git.sha (to describe which commit was used for this exact version).

In such a case you need to create a text file (for example, VERSION or VERSION.txt) with your next release number (e.g. 1.1.0):

1.1.0

Then update your config file:

.. tabs::

    .. code-tab:: python ``setup.py``

        import setuptools
        from pathlib import Path

        root_path = Path(__file__).parent
        version_file = root_path / "VERSION.txt"

        setuptools.setup(
            ...,
            setup_requires=["setuptools-git-versioning>=2.0,<3"],
            setuptools_git_versioning={
                "enabled": True,
                "version_file": version_file,
                "count_commits_from_version_file": True,  # <--- enable commits tracking
                "dev_template": "{tag}.dev{ccount}",  # suffix for versions will be .dev
                "dirty_template": "{tag}.dev{ccount}",  # same thing here
            },
        )

    .. code-tab:: toml ``pyproject.toml``

        [build-system]
        requires = [ "setuptools>=41", "wheel", "setuptools-git-versioning>=2.0,<3", ]
        build-backend = "setuptools.build_meta"

        [project]
        dynamic = ["version"]

        [tool.setuptools-git-versioning]
        enabled = true
        version_file = "VERSION"
        count_commits_from_version_file = true  # <--- enable commits tracking
        dev_template = "{tag}.dev{ccount}"  # suffix for versions will be .dev
        dirty_template = "{tag}.dev{ccount}"  # same thing here

In case of next release version 1.1.0, the third commit to dev branch will produce version number 1.1.0.dev3, and so on.

Release process

  • Merge dev branch into master branch.
  • Tag commit in the master branch, and publish a release from code on this branch.
  • Checkout back to dev branch
  • Save next release version (e.g. 1.2.0) in VERSION or VERSION.txt file in the dev branch.
  • Next commits to a dev branch will lead to returning this next release version plus dev suffix, like 1.2.0.dev1 or so.
  • N in .devN suffix is a number of commits since the last change of a certain file.

Warning

Every change of this file in the dev branch will lead to this N suffix to be reset to 0. Update this file only in the case when you're setting up the next release version!

Development releases from any branch

Just like example above, but you want to make development releases (prereleases) with a branch name (feature / bugfix / preview / beta / etc) present in the version number.

For example, if the branch name is something like alpha, beta, preview or rc, you can add {branch} substitution to template in your config file:

.. tabs::

    .. code-tab:: python ``setup.py``

        import setuptools
        from pathlib import Path  # same thing here

        root_path = Path(__file__).parent
        version_file = root_path / "VERSION.txt"

        setuptools.setup(
            ...,
            setup_requires=["setuptools-git-versioning>=2.0,<3"],
            setuptools_git_versioning={
                "enabled": True,
                "version_file": version_file,
                "count_commits_from_version_file": True,
                "dev_template": "{tag}.{branch}{ccount}",  # <--- note {branch} here
                "dirty_template": "{tag}.{branch}{ccount}",
            },
        )

    .. code-tab:: toml ``pyproject.toml``

        [build-system]
        requires = [ "setuptools>=41", "wheel", "setuptools-git-versioning>=2.0,<3", ]
        build-backend = "setuptools.build_meta"

        [project]
        dynamic = ["version"]

        [tool.setuptools-git-versioning]
        enabled = true
        version_file = "VERSION"
        count_commits_from_version_file = true
        dev_template = "{tag}.{branch}{ccount}"  # <--- note {branch} here
        dirty_template = "{tag}.{branch}{ccount}"

Fourth commit to alpha branch with next release number 1.2.3 will generate a version number like 1.2.3a4.

Fifth commit to beta branch with next release number 1.2.3 will generate a version number like 1.2.3b5.

Development releases using only branch name

It is also possible to use branch names like 1.0-alpha or 1.1.beta:

.. tabs::

    .. code-tab:: python ``setup.py``

        import setuptools
        from pathlib import Path

        root_path = Path(__file__).parent
        version_file = root_path / "VERSION.txt"

        setuptools.setup(
            ...,
            setup_requires=["setuptools-git-versioning>=2.0,<3"],
            setuptools_git_versioning={
                "enabled": True,
                "count_commits_from_version_file": True,
                "dev_template": "{branch}{ccount}",  # <--- without {tag}
                "dirty_template": "{branch}{ccount}",
                "version_file": version_file,
            },
        )

    .. code-tab:: toml ``pyproject.toml``

        [build-system]
        requires = [ "setuptools>=41", "wheel", "setuptools-git-versioning>=2.0,<3", ]
        build-backend = "setuptools.build_meta"

        [project]
        dynamic = ["version"]

        [tool.setuptools-git-versioning]
        enabled = true
        version_file = "VERSION"
        count_commits_from_version_file = true
        dev_template = "{branch}{ccount}"  # <--- without {tag}
        dirty_template = "{branch}{ccount}"

Second commit to 1.0-alpha branch will generate a version number like 1.0a2.

Third commit to 1.2.beta branch will generate a version number like 1.2b3.

If branch name is not PEP 440 compliant, use :ref:`branch-formatter-option` option

Note

Although VERSION file content is not used in this particular example, you still need to update it while changing your next release version.

Otherwise this tool will not be able to properly calculate version number. The commits history is used for this calcucation, so no file changes means that ccount will not be reset to 0.

See also