Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/toumorokoshi/vcver-python

Reference Implementation of vcver (WIP)
https://github.com/toumorokoshi/vcver-python

Last synced: about 2 months ago
JSON representation

Reference Implementation of vcver (WIP)

Awesome Lists containing this project

README 

        
============

vcver Python

============



--------------

What is vcver?

--------------



vcver is an approach for versioning that heavily relies on the version control

system of choice for determining version strings.



There are two categories of version strings:



develop versions, of the form:



.. code-block::



    {main_version}.dev{commit_count}+{branch}.{scm_change_id}



With development branches, it is desired to not override versions published from

a blessed subset of "released" branches. As such, if the current branch is not a release

branch, a version of 0 is used instead of the main_version:



.. code-block::



    0.dev{commit_count}+{branch}.{scm_change_id}



and a release version, of the form:



.. code-block::



    {main_version}



Each part is described as follows:



* main_version is retrieved from the last tagged commit with a leading v (e.g. v1.0),

  but is converted to a 0 if the branch is not a release branch.

* commit_count is the number of commits from main_version

* branch is the branch that the repository was built against, removing

  characters that are incompatible with PEP440 (anything that is not alphanumeric or a dot)

* scm_change_id is a unique id in the form of version control, used to identify

  the change that was used to build this version.



For example, in a git repository, on a master branch with the most recent tag of

v1.1, the dev version would look something like:



.. code-block::



   1.1.dev10+master.abc123



On a develop branch:



.. code-block::



   0.dev13+develop.def456



And a release version:



.. code-block::



   1.1



These are compatible with

`PEP440 `_.



-------

Example

-------



Add a MANIFEST.in to your package, if you do not already have one. Then add the following:



.. code-block::



   include VERSION



It's also recommended to ignore this file in your version control.



Then, follow this pattern in your setup.py:



.. code-block:: python



    # OPTIONAL, but recommended:

    # this block is useful for specifying when a build should

    # use the 'release' version. it allows specifying a release version

    # with an additional argument in the setup.py:

    # $ python setup.py upload --release

    import sys

    is_release = False

    if "--release" in sys.argv:

        sys.argv.remove("--release")

        is_release = True



    # OPTIONAL, but recommended:

    # vcver writes a version file relative to the

    # current working directory by default.

    # It's recommended to provide it with your

    # setup.py directory instead (in case someone

    # runs your setup.py from a different directory)

    base = os.path.dirname(os.path.abspath(__file__))



    setup(name='aiohttp-transmute',

        # add the following two lines,

        # and do not specify a version.

        setup_requires=["vcver"],

        # vcver will only produce a release

        # version if "is_release" is True.

        vcver={

            "is_release": is_release,

            "path": base,

            # OPTIONAL ARGS



            # version_format overrides the standard version format

            version_format="{main_version}.{commit_count}",



            # release_version_format overrides the release version format

            release_version_format="{commit_count}",



            # scm_type: if you do not want autodetection of the SCM, you can

            # specify it.

            scm_type="git",



            # release_branch_regex: override the default release branch

            # (default release branch depends on the SCM used.)

            release_branch_regex="(master|hotfix|release)",



            # version_file: override the name of the version file.

            version_file="GENERATED_VERSION"

        },

        ...

    )



Now your package will publish with a VC-based version!



If you followed the full example, you can specify the release version by adding --release:



.. code-block::



    python setup.py upload --release



-------------------

FAQ / Other Details

-------------------



Why a dev and release version?

==============================



The dev and release versions have different goals:



* dev: to provide as much information as possible to quickly identify

  where the current version originated from in regard to version control.

* release: to provide a clear version that helps the consumer understand what changed.



For most consumers, the number of commits since the last release, the

branch it was released against, or the build commit itself are

irrelevant.  The consumer wants to know about the size of the change or type of changes,

and that can be done by the major / minor / patch versions specified

in the git tag, or the changelog. Adding version control information proves to be confusing with

that regard, providing multiple numbers that are not relevant to figuring out

the amount of change.



Why zero out versions from non-release branches?

================================================



Sometimes, a non-release version can be published accidentally, or it may be desired to publish

development versions side by side by versions published by release branches. In this situations,

ensuring that the release versions always take precedence over non-release version is valuable, to ensure

that development versions are not accidentally picked up by those expecting stable releases.



If this behavior is not desired, custom version strings can be specified with "main_version" instead of "main_version". "main_version" is preserved regardless of the branch used.



How to make sure others can consume your package

================================================



If you followed the example, you already have this.



Once vcver is called, a VERSION file is created in the current working

directory, which is typically the same directory as where the setup.py lives

(you can make it more accurate, see the example)



vcver will attempt to find a VERSION file if the working directory is

not a version control repository. Make sure your package includes a

VERSION file by creating/modifying the

`MANIFEST.in `_:



.. code-block::



   include VERSION



Customizable Version Strings

============================



Both the version format and release format is configurable, with the

arguments version_format and release_version_format, respectively.



In addition to the values above, the following values are provided:



* tag_version: the raw version of main_version, which does not zero

  out for non-release branches.



Pre-PEP440 Version

==================



Some (much older) versions of setuptools are unable to consume the dev version string,

due to the plus in the version string.



If you need backwards compatibility and you would still like vc versioning, the

following format is recommended:



.. code-block::



      {main_version}.dev{commit_count}.{branch}.{scm_change_id}



 This can be changed by an argument into vcver:



.. code-block:: python



    # in the setup call of setup.py

    vcver={"version_format": "{main_version}.dev{commit_count}.{branch}.{scm_change_id}"}



Compatibility with Semantic Versioning

======================================



`Semantic versioning `_ is a standard to provided a

meaning to the major, minor, and patch versions of a version

string. Compatibility with semver is possible if new major / minor

versions are tagged according the semver spec.



--------------

Special Thanks

--------------



- `Zillow `_, where this particular approach of SCM-based versioning was developed

- `Taylor McKay `_,  who implemented the original Python version at Zillow

- `Mohammad Sarhan `_, who designed and implemented the original Java version at Zillow, and has a public `gradle variant `_