{"id":17316066,"url":"https://github.com/ankostis/polyvers","last_synced_at":"2025-04-14T14:53:33.130Z","repository":{"id":57454123,"uuid":"119414669","full_name":"ankostis/polyvers","owner":"ankostis","description":"Manage sub-project versions in Git monorepos independently","archived":false,"fork":false,"pushed_at":"2019-05-20T13:07:05.000Z","size":1524,"stargazers_count":8,"open_issues_count":10,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-09T12:38:53.913Z","etag":null,"topics":["configuration-management","git","library","monorepo","pep440","tool","version-manager","versioning"],"latest_commit_sha":null,"homepage":"http://polyvers.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"eupl-1.2","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ankostis.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-29T17:14:56.000Z","updated_at":"2023-11-05T10:55:03.000Z","dependencies_parsed_at":"2022-09-04T23:22:20.772Z","dependency_job_id":null,"html_url":"https://github.com/ankostis/polyvers","commit_stats":null,"previous_names":["jrcstu/polyvers"],"tags_count":121,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankostis%2Fpolyvers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankostis%2Fpolyvers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankostis%2Fpolyvers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ankostis%2Fpolyvers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ankostis","download_url":"https://codeload.github.com/ankostis/polyvers/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248901247,"owners_count":21180370,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["configuration-management","git","library","monorepo","pep440","tool","version-manager","versioning"],"created_at":"2024-10-15T13:11:31.745Z","updated_at":"2025-04-14T14:53:33.097Z","avatar_url":"https://github.com/ankostis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"==================================================================\nPolyvers: Bump sub-project versions in Git monorepos independently\n==================================================================\n\n.. _opening-start:\n.. image:: https://img.shields.io/pypi/v/polyvers.svg\n    :alt: Deployed in PyPi?\n    :target: https://pypi.org/pypi/polyvers\n\n.. image:: https://img.shields.io/travis/ankostis/polyvers.svg\n    :alt: TravisCI (linux) build ok?\n    :target: https://travis-ci.org/ankostis/polyvers\n\n.. image:: https://ci.appveyor.com/api/projects/status/lyyjtmit5ti7tg1n?svg=true\n    :alt: Apveyor (Windows) build?\n    :scale: 100%\n    :target: https://ci.appveyor.com/project/ankostis/polyvers\n\n.. image:: https://img.shields.io/coveralls/github/ankostis/polyvers.svg\n    :alt: Test-case coverage report\n    :scale: 100%\n    :target: https://coveralls.io/github/ankostis/polyvers?branch=master\u0026service=github\n\n.. image:: https://readthedocs.org/projects/polyvers/badge/?version=latest\n    :target: https://polyvers.readthedocs.io/en/latest/?badge=latest\n    :alt: Auto-generated documentation status\n\n.. image:: https://pyup.io/repos/github/ankostis/polyvers/shield.svg\n    :target: https://pyup.io/repos/github/ankostis/polyvers/\n    :alt: Dependencies needing updates?\n\n.. image:: https://api.codacy.com/project/badge/Grade/11b2545fd0264f1cab4c862998833503\n    :target: https://www.codacy.com/app/ankostis/polyvers_jrc\n    :alt: Code quality metric\n\n:version:       |version|\n:updated:       |today|\n:Documentation: https://polyvers.readthedocs.io\n:repository:    https://github.com/ankostis/polyvers\n:pypi-repo:     https://pypi.org/project/polyvers/, https://pypi.org/project/polyversion/\n:keywords:      version-management, configuration-management, versioning, git, monorepos,\n                tool, library\n:copyright:     2018 JRC.C4(STU), European Commission (`JRC \u003chttps://ec.europa.eu/jrc/\u003e`_)\n:license:       `EUPL 1.2 \u003chttps://joinup.ec.europa.eu/software/page/eupl\u003e`_\n\nA Python 3.6+ command-line tool to manage `PEP-440 version-ids\n\u003chttps://www.python.org/dev/peps/pep-0440/\u003e`_ of dependent sub-projects\nhosted in a *Git* :term:`monorepo`\\s, independently.\n\nThe key features are:\n\n- :term:`setuptools integration`,\n- x2 :term:`repo scheme`\\s (:term:`monorepo`, :term:`mono-project`),\n- configurable :term:`version scheme`,\n- *leaf* :term:`release scheme`,\n- intuitive :term:`version-bump algebra` (TODO),\n- configurable :term:`engravings`.\n\nThe *leaf version scheme* feature departs from the logic of :ref:`similar-tools`.\nSpecifically, when bumping the version of sub-project(s), this tool\nadds **+2 tags and +1 commits**:\n\n  - one :term:`Version tag` in-trunk like ``foo-proj-v0.1.0``,\n  - and another :term:`Release tag` on a new :term:`out-of-trunk commit` (leaf)\n    like ``foo-proj-r0.1.0`` (the new version-ids are :term:`engrave`\\d only\n    in this release-commit):\n\n    .. figure:: _static/leaf_commits.png\n        :align: center\n        :alt: Leaf-commits \u0026 version/release tags for the two repo's sub-projects\n\n        Leaf-commits \u0026 version/release-tags for the two sub-project's,\n        as shown in this repo's git history.\n\n.. Note::\n  The reason for this feature is to allow exchange code across branches (for the\n  different sub-projects) without :term:`engravings` getting in your way as\n  merge-conflicts.\n\nAdditional capabilities and utilities:\n\n- It is still possible to use plain **version tags (vtags)** like ``v0.1.0``,\n  assuming you have a single project (called hereinafter a :term:`mono-project`)\n\n- A separate Python 2.7+ **polyversion** project, which contains API to extract\n  sub-project's version from past tags (provided as a separate subproject\n  so client programs do not get ``polyvers`` commands transitive dependencies).\n  The library functions as a :term:`setuptools  plugin`.\n\n.. _opening-end:\n\n.. contents:: Table of Contents\n   :backlinks: top\n   :depth: 4\n\n\n.. _usage:\n\nTutorial\n========\nInstall the tool\n----------------\nAnd you get the ``polyvers`` command:\n\n.. code-block:: console\n\n    $ pip install polyvers\n    ...\n    $ polyvers --version\n    0.0.0\n    $ polyvers --help\n    ...\n\n    $ polyvers status\n    polyvers: Neither `setup.py` nor `.polyvers(.json|.py|.salt)` config-files found!\n\n.. Note::\n    Actually two projects are installed:\n\n    - **polyvers** cmd-line tool, for developing python :term:`monorepo`\\s,\n    - **polyversion**: the base python library used by projects developed\n      with *polyvers* tool, so that their sources can discover their subproject-version\n      on runtime from Git.\n\n\nPrepare project\n---------------\nAssuming our :term:`monorepo` project ``/monorepo.git/`` contains two sub-projects,\nthen you need enter the following configurations into your build files::\n\n    /monorepo.git/\n        +--setup.py               # see below for contents\n        +--mainprog/__init__.py\n        |                         from polyversion import polyversion, polytime\n        |                         __version__ = polyversion()\n        |                         __updated__ = polytime()\n        |                         ...\n        |\n        +--core-lib/\n            +--setup.py:          # like above\n            +--core/__init__.py   # like above\n            +--...\n\n.. Tip::\n    You may see different sample approaches for your setup-files by looking\n    into both `polyvers` \u0026 `polyversion` subprojects of this repo (because\n    they eat their own dog food).\n\nThe `polyversion` library function as a *setuptools* \"plugin\", and\nadds a new ``setup()`` keyword ``polyversion = (bool | dict)``\n(see :func:`polyversion.init_plugin_kw` for its content), which you can use it\nlike this:\n\n.. code-block:: python\n\n    from setuptools import setup\n\n    setup(\n        project='myname',\n        version=''              # omit (or None) to abort if cannot auto-version\n        polyversion={           # dict or bool\n            'version_scheme: 'mono-project',\n            ...  # See `polyversion.init_plugin_kw()` for more keys.\n        },\n        setup_requires=[..., 'polyversion'],\n        ...\n    )\n\n.. Hint::\n    The ``setup_requires=['polyvers']`` keyword  (only available with *setuptools*,\n    and not *distutils*), enables the new ``polyversion=`` setup-keyword.\n\nAlternatively, a subproject may use :pep:`0518` to pre-install `polyversion`\nlibrary *before* pip-installing or launching ``setup.py`` script.\nTo do that, add the ``pyproject.toml`` file below next to your `setup` script::\n\n    [build-system]\n    requires = [\"setuptools\", \"wheel\", \"polyversion\"]\n\nand then you can simply import ``polyversion`` from your ``setup.py``:\n\n.. code-block:: python\n\n    from setuptools import setup\n    from polyversion import polyversion\n\n    setup(\n        project='myname',\n        version=polyversion(mono_project=True)  # version implied empty string.\n\n.. Attention::\n    To properly install a :pep:`0518` project you need ``pip-v10+`` version.\n\n\nInitialize `polyvers`\n---------------------\n...we let the tool auto-discover the mapping of *project folders ↔ project-names*\nand create a `traitlets configuration YAML-file \u003chttps://traitlets.readthedocs.io\u003e`_\nnamed as  ``/monorepo.git/.polyvers.py``:\n\n.. code-block:: console\n\n    $ cd monorepo.git\n\n    $ polyvers init --monorepo\n    Created new config-file '.polyvers.yaml'.\n\n    $ cat .polyvers.yaml\n    ...\n    PolyversCmd:\n      projects:\n      - pname: mainprog     # name extracted from `setup.py`.\n        basepath: .         # path discovered by the location of `setup.py`\n      - pname: core\n        basepath: core-lib\n    ...\n\n    $ git add .polyvers.yaml\n    $ git commit -m 'add polyvers config-gile'\n\nAnd now we can use the ``polyvers`` command to inspect the versions of all\nsub-projects:\n\n.. code-block:: console\n\n    $ polyvers status\n    - mainprog\n    - core\n\nIndeed there are no tags in in git-history for the tool to derive and display\nproject-versions, so only project-names are shown.  With ``--all`` option\nmore gets displayed:\n\n.. code-block:: console\n\n    $ polyvers status -a\n    - pname: mainprog\n      basepath: .\n      gitver:\n      history: []\n    - pname: core\n      basepath: core-lib\n      gitver:\n      history: []\n\n..where ``gitver`` would be the result of ``git-describe``.\n\n\nBump versions\n-------------\nWe can now use tool to set the same version to all sub-projects:\n\n.. code-block:: console\n\n    $ polyvers bump 0.0.0 -f noengraves   # all projects implied, if no project-name given\n    00:52:06       |WARNI|polyvers.bumpcmd.BumpCmd|Ignored 1 errors while checking if at least one version-engraving happened:\n      ignored (--force=noengraves): CmdException: No version-engravings happened, bump aborted.\n    00:52:07       |NOTIC|polyvers.bumpcmd.BumpCmd|Bumped projects: mainprog-0.0.0 --\u003e 0.0.0, core-0.0.0 --\u003e 0.0.0\n\nThe ``--force=noengraves`` disables a safety check that requires at least one\nfile modification for :term:`engrave`\\ing the current version in the leaf \"Release\" commit\n(see next step).\n\n.. code-block:: console\n\n    $ polyvers status\n    - mainprog-v0.0.0\n    - core-v0.0.0\n\n    $ git lg    # Ok, augmented `lg` output a bit here...HEAD --\u003e UPPER branch.\n    COMMITS BRANCH TAGS                 REMARKS\n    ======= ====== ==================== ========================================\n         O  latest mainprog-r0.0.0      - x2 tags on \"Release\" leaf-commit\n        /          core-r0.0.0            outside-of-trunk (not in HEAD).\n       O    MASTER mainprog-v0.0.0      - x2 tags on \"Version\" commit\n       |           core-v0.0.0            for bumping both projects to v0.0.0\n       O                                - Previous commit, before version bump.\n\n   .. Hint::\n      Note the difference between ``ABC-v0.0.0`` vs ``ABC-r0.0.0`` tags.\n\n   In the source code, it's only the \"release\" commit that has :term:`engrave`\\d* version-ids:\n\n   .. code-block:: console\n\n    $ cat mainprog/mainprog/__init__.py    # Untouched!\n    import polyvers\n\n    __title__     = \"mainprog\"\n    __version__ = polyvers.version('mainprog')\n    ...\n\n    $ git checkout  latest\n    $ cat mainprog/mainprog/__init__.py\n    import polyvers\n\n    __title__     = \"mainprog\"\n    __version__ = '0.0.0'\n    ...\n\n    $ git checkout  -  # to return to master.\n\n\nEngrave version in the sources\n------------------------------\nUsually programs report their version somehow when run, e.g. with ```cmd --version``.\nWith *polyvers* we can derive the latest from the tags created in the previous step,\nusing a code like this, usually in the file ``/mainprog/mainprog/__init__.py:``:\n\n.. code-block:: python\n\n    import polyvers\n\n    __title__ = \"mainprog\"\n    __version__ = polyvers.version('mainprog')\n    ...\n\n...and respectively ``/core-lib/core/__init__.py:``:\n\n.. code-block:: python\n\n    __version__ = polyvers.version('core')\n\n\n\nBump sub-projects selectively\n-----------------------------\nNow let's add another dummy commit and then bump ONLY ONE sub-project:\n\n.. code-block:: console\n\n    $ git commit  --allow-empty  -m \"some head work\"\n    $ polyvers bump ^1 mainprog\n    00:53:07       |NOTIC|polyvers.bumpcmd.BumpCmd|Bumped projects: mainprog-0.0.0 --\u003e 0.0.1\n\n    $ git lg\n    COMMITS BRANCH TAGS                 REMARKS\n    ======= ====== ==================== ========================================\n         O  latest mainprog-r0.0.1.dev0 - The latest \"Release\" leaf-commit.\n        /                                 branch `latest` was reset non-ff.\n       O    MASTER mainprog-v0.0.1.dev0 - The latest \"Version\" commit.\n       O                                - some head work\n       | O         mainprog-r0.0.0      - Now it's obvious why \"Release\" commits\n       |/          core-r0.0.0            are called \"leafs\".\n       O           mainprog-v0.0.0\n       |           core-v0.0.0\n       O\n\n    $ git checkout latest\n    $ cat mainprog/mainprog/__init__.py\n    import polyvers\n\n    __title__     = \"mainprog\"\n    __version__ = '0.0.1.dev0'\n    ...\n\n    $ cat core/core/__init__.py\n    import polyvers\n\n    __title__ = \"core\"\n    __version__ = '0.0.0+mainprog.0.0.1.dev0'\n    ...\n    $ git checkout -\n\nNotice how the the `\"local\" part of PEP-440\n\u003chttps://www.python.org/dev/peps/pep-0440/#local-version-identifiers\u003e`_ (statring with ``+...``)\nis used by the engraved version of the **un-bumped** ``core`` project to signify\nthe correlated version of the **bumped** ``mainprog``.  This trick is not necessary\nfor tags because they apply repo-wide, to all sub-projects.\n\n\n.. _features:\n\nFeatures\n========\n.. include:: \u003cxhtml1-lat1.txt\u003e\n.. glossary::\n\n    PEP 440 version ids\n        While most versioning tools use `Semantic versioning\n        \u003chttp://semver.org/\u003e`_, python's ``distutils`` native library\n        supports the quasi-superset, but more versatile, `PEP-440 version ids\n        \u003chttps://www.python.org/dev/peps/pep-0440/\u003e`_, like that:\n\n        - Pre-releases: when working on new features::\n\n            X.YbN               # Beta release\n            X.YrcN  or  X.YcN   # Release Candidate\n            X.Y                 # Final release\n\n        - Post-release::\n\n            X.YaN.postM         # Post-release of an alpha release\n            X.YrcN.postM        # Post-release of a release candidate\n\n        - Dev-release::\n\n            X.YaN.devM          # Developmental release of an alpha release\n            X.Y.postN.devM      # Developmental release of a post-release\n\n    version-bump algebra\n        When bumping, the increment over the base-version can be specified with a\n        \"relative version\", which is a combination of :pep:`0440` segments and\n        one of these modifiers: ``+^~=``\n        See :mod:`polyvers.vermath` for more.\n\n    repo scheme\n    monorepo\n    mono-project\n        whether a git repo hosts a single or multiple subprojects\n\n        **Rational:**\n\n        When your single project succeeds, problems like these are known only too well:\n\n          Changes in **web-server** part depend on **core** features that cannot\n          go public because the \"official\" **wire-protocol** is freezed.\n\n          While downstream projects using **core** as a library complain about\n          its bloated transitive dependencies (asking why *flask* library is needed??).\n\n        So the time to \"split the project\" has come.  But from :term:`Lerna`:\n\n          |laquo|\\ Splitting up large codebases into separate independently versioned packages\n          is extremely useful for code sharing. However, making changes across\n          many repositories is messy and difficult to track, and testing across repositories\n          gets complicated really fast.\\ |Raquo|\n\n        So a *monorepo* [#]_ [#]_ is the solution.\n        But as `Yarn \u003chttps://yarnpkg.com/blog/2017/08/02/introducing-workspaces/\u003e`_ put it:\n\n          |laquo|\\ OTOH, splitting projects into their own folders is sometimes not enough.\n          Testing, managing dependencies, and publishing multiple packages quickly\n          gets complicated and many such projects adopt tools such as ...\\ |Raquo|\n\n        *Polyvers* is such a tool.\n\n        .. [#] \u003chttps://medium.com/@maoberlehner/monorepos-in-the-wild-33c6eb246cb9\n        .. [#] http://www.drmaciver.com/2016/10/why-you-should-use-a-single-repository-for-all-your-companys-projects/\n\n    version scheme\n        the pattern for version-tags.\n        2x2 *versioning schemes* are pre-configured, for :term:`mono-project` and\n        :term:`monorepo` repositories, respectively:\n\n        - `v1.2.3` (and `r1.2.3` applied on :term:`leaf commit`\\s)\n        - `project-v1.2.3` (and `project-r1.2.3` for :term:`leaf commit`\\s)\n\n    release scheme\n    out-of-trunk commit\n    leaf commit\n    release tag\n    r-tag\n    version tag\n    v-tag\n        Even in single-project repos, sharing code across branches may cause\n        merge-conflicts due to the version-ids :term:`engrave`\\d\" in the sources.\n        In :term:`monorepo`\\s, the versions proliferate, and so does the conflicts.\n\n        Contrary to :ref:`similar-tools`, static version-ids are engraved only in out-of-trunk\n        (leaf) commits, and only when the sub-projects are released.\n        In-trunk code is never touched, and version-ids are reported, on runtime, based\n        on Git tags (like ``git-describe``), so they are always up-to-date.\n\n    engrave\n    engravings\n        the search-n-replace in files, to substitute the new version.\n        Default grep-like substitutions are included, which can be re-configured\n        in the ``.polyvers.yaml`` config file.\n\n    setuptools\n    setuptools plugin\n    setuptools integration\n        The `polyversion` library function as a *setuptools* \"plugin\", and\n        adds a new ``setup()`` keyword ``polyversion = (bool | dict)``\n        (see :func:`polyversion.init_plugin_kw` for its content).\n\n    bdist-check\n        When the ``setuptools:setup()`` keyword ``polyversion_check_bdist_enabled = True``\n        the :term:`setuptools plugin` aborts any `bdist...` commands if they\n        are not run from :term:`engrave`\\d sources, (ie from an :term:`r-tag`).\n\n        To enable this check without editing the sources, add the following into\n        your ``$CWD/setup.cfg`` file::\n\n            [global]\n            polyversion_check_bdist_enabled = true\n            ...\n\n    Marking dependent versions across sub-projects\n        [TODO] When bumping the version of a sub-project the `\"local\" part of PEP-440\n        \u003chttps://www.python.org/dev/peps/pep-0440/#local-version-identifiers\u003e`_\n        on all other the *dependent* sub-projects in the monorepo  signify their relationship\n        at the time of the bump.\n\n    Lock release trains as \"developmental\"\n        [TODO] Specific branches can be selected always to be published into *PyPi* only as\n        `PEP-440's \"Developmental\" releases\n        \u003chttps://www.python.org/dev/peps/pep-0440/#developmental-releases\u003e`_, meanining that\n        users need ``pip install --pre`` to install from such release-trains.\n        This is a safeguard to avoid accidentally landing half-baked code to users.\n\n    default version env-var\n        From which env-var to read a project's *version* if git cmd fail.\n        It does not override any value given as ``default_version`` keyword\n        for :func:`polyversion.polyversion()`.\n        Also :func:`polyversion.polytime()` assumes keyword ``no_raise=True``\n        if such env-var is found.\n        [Default var-name: ``\u003cpname\u003e_VERSION``]\n\n    Other Features\n        - Highly configurable using `traitlets \u003chttps://traitlets.readthedocs.io\u003e`_,\n          with sensible defaults; it should be possible to start using the tool\n          without any config file (see `init` cmd), or by adding one of the flags\n          ``--monorepo``/``--mono-project`` in all commands, in the face of\n          conflicting tags.\n        - Always accurate version reported on runtime when run from git repos\n          (never again wonder with which version your experimental-data were produced).\n\n\nKnown Limitations, Drawbacks \u0026 Workarounds\n------------------------------------------\n.. TODO: epoch vermath, and update README\n\n- PEP440 `Epoch` handling is not yet working.\n- Version-bump's grammar is not yet as described in \"GRAMMAR\" section\n  of command's doc::\n\n    $ polyvers config desc --class BumpCmd\n    BumpCmd(_SubCmd)\n    ----------------\n    Increase or set the version of project(s) to the (relative/absolute) version.\n    SYNTAX:\n        polyvers config desc [OPTIONS] \u003cversion\u003e [\u003cproject\u003e]...\n    - If no project(s) specified, increase the versions on all projects.\n    - Denied if version for some projects is backward-in-time (or has jumped parts?);\n      use --force if you might.\n    VERSION: - A version specifier, either ABSOLUTE, or RELATIVE to the current\n    version og each project:\n      - *ABSOLUTE* PEP-440 version samples:\n        - Pre-releases: when working on new features:\n            X.YbN               # Beta release\n            X.YrcN  or  X.YcN   # Release Candidate\n            X.Y                 # Final release\n    ...\n\n- (not related to this tool) In ``setup.py`` script, the kw-argument\n  ``package_dir={'': \u003csub-dir\u003e}`` arg is needed for `py_modules` to work\n  when packaging sub-projects (also useful with ``find_packages()``,\n  check this project's sources).\n  But ``\u003csub-dir\u003e`` must be relative to launch cwd, or else,\n  ``pip install -e \u003csubdir\u003e`` and/or ``python setup.py develop``\n  break.\n\n- (not related to this tool) When building projects with ``python setup.py bdist_XXX``,\n  you have to clean up your build directory (e.g. ``python setup.py clean --all``)\n  or else, the distribution package will contain the sources from all previous\n  subprojects built.  That applies also when rebuilding a project between versions.\n\n- Installing directly from git-repos needs an engraved branch (e.g. ``latest``)::\n\n      pip install git+https://github.com/ankostis/polyvers@latest\n\n  If you still want to install non-engraved branhces (e.g. ``master``),\n  set the :term:`default version env-var`; for example, since *polyvers* subproject\n  has not customized the name of its env-var, you may install the very latest\n  like this::\n\n      polyvers_VERSION=1.2.3 pip install git+https://github.com/ankostis/polyvers\n\n  .. Attention::\n    The version given in the env-var is irrelevant.\n    The installed version will still derive from git tags, and the local-part\n    from the actual git-commit.\n\n- (not related to this tool) If you don't place a ``setup.py`` file at the root\n  of your git-repo (using ``package_dir`` argument to ``setup()``  function or\n  in ``find_packages()``,  according to `setuptools-docs\n  \u003chttp://setuptools.readthedocs.io/en/latest/setuptools.html#id10\u003e`_), then\n  in order to ``pip install git+https://...`` directly from remote URLs\n  you have to use `this official trick\n  \u003chttps://pip.pypa.io/en/stable/reference/pip_install/#vcs-support\u003e`_.\n  For example, to install *polyversion* subproject::\n\n      pip install \"git+https://github.com/ankostis/polyvers@latest#egg=polyversion\u0026subdirectory=pvlib\"\n\n  Notice that the quotes are needed to escape the ``\u0026`` char from bash.\n  Respectively, use this to install from the very latest::\n\n      polyversion_VERSION=1.2.3 pip install git+https://github.com/ankostis/polyvers#egg=polyversion\u0026subdirectory=pvlib\"\n\n\n- Set branch ``latest`` as default in GitHub to show :term:`engrave`\\d sub-project version-ids.\n\n- See :ref:`to-dos`.\n\nRecipes\n=======\nAutomatically sign tags:\n------------------------\nAdd this to your ``~/.polyvers.yaml``:\n\n.. code-block:: yaml\n\n    BumpCmd:\n      sign_tags: true\n      sign_user: \u003cusername-or-keyid\u003e\n\n\n.. _contribute-section:\n.. _similar-tools:\n\nSimilar Tools\n=============\nBumped across these projects while building it...\n\n.. glossary::\n\n    bumpversion\n        The original **bumpversion** project; development stopped after 2015:\n        (recomended also by :term:`python guide`)\n        https://github.com/peritus/bumpversion\n\n    bump2version\n        active clone of the original:\n        https://github.com/c4urself/bump2version\n\n    releash\n        another :term:`monorepo`\\s managing tool, that publishes also to PyPi:\n        https://github.com/maartenbreddels/releash\n\n    Git Bump\n        bump version using git-hooks:\n        https://github.com/arrdem/git-bump\n\n    Lerna\n        A tool for managing JavaScript projects with multiple packages.\n        https://lernajs.io/\n\n    Pants\n        a build system designed for codebases that:\n        - Are large and/or growing rapidly.\n        - Consist of many subprojects that share a significant amount of code.\n        - Have complex dependencies on third-party libraries.\n        - Use a variety of languages, code generators and frameworks.\n        - https://www.pantsbuild.org/\n\n    pbr\n        a ``setup_requires`` library that\n        injects sensible default and behaviors into your *setuptools*.\n        Crafted for *Semantic Versioning*, maintained for OpenStack projects.\n        https://docs.openstack.org/pbr/\n\n    Zest.releaser\n        easy releasing and tagging for Python packages; make easy, quick and\n        neat releases of your Python packages.  You need to change the version number,\n        add a new heading in your changelog, record the release date, svn/git/bzr/hg tag\n        your project, perhaps upload it to pypi... *zest.releaser* takes care\n        of the boring bits for you.\n        (recomended also by :term:`python guide`)\n        http://zestreleaser.readthedocs.io/\n\n    incremental\n        a small *setuptools* plugin library that versions Python projects.\n        https://github.com/twisted/incremental\n\n    changes\n        Manages the release of a Python Library (intuitive logo,\n        recomended also by :term:`python guide`):\n\n        - Auto generates changelog entries from commit messages\n        - CLI that follows Semantic Versioning principles to auto-increment the library version\n        - Runs the library tests\n        - Checks the package installation from a tarball and PyPi\n        - Uploads the distribution to PyPi\n        - Tags the GitHub repository\n\n        https://github.com/michaeljoseph/changes\n\n    setuptools_scm\n        managing versions in scm metadata instead of declaring them as\n        the version argument or in a scm managed file, apart from  handling\n        file finders for the supported scm’s.\n        (recomended also by :term:`python guide`)\n        https://pypi.org/project/setuptools_scm/\n\n        .. Note:\n            Interesting how this project parses ``git describe`` tags:\n            https://pypi.org/project/setuptools_scm/#default-versioning-scheme\n\n    Dunamai\n        Library and command line tool for producing dynamic, standards-compliant version strings, \n        derived from tags in your version control system. Suitable for projects written in \n        any programming language (i.e. no need for  `setup.py`), \n        many VCSs(Git; Mercurial, Darcs, Subversion, Bazaar), and \n        many Version styles (PEP 440, Semantic Versioning, Haskell Package Versioning Policy, Custom)\n         https://github.com/mtkennerly/dunamai\n\n    setupmeta\n        Helper for simple `setup.py` files with *setuptools_scm* like tag-based versioning\n        plus commands for bumping version, explain meta infos, cleanall, twine, etc\n        https://github.com/zsimic/setupmeta\n\n    python guide\n        There is a dedicated guide for this problem in pythons docs:\n        https://packaging.python.org/guides/single-sourcing-package-version/\n\nFind more than `34 similar projects in GitHub:\n\u003chttps://github.com/search?l=Python\u0026o=desc\u0026q=bump+version\u0026s=updated\u0026type=Repositories\u003e`_\nand in awesome: https://github.com/korfuri/awesome-monorepo.\n\n\n\n\nCredits\n=======\n- Contains a function from the BSD-tool :term`pbr` to fetch version from *pkg-metadata*\n  when invoked as a :term:`setuptools plugin` from inside an egg.\n\n- This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.\n\n- Using `towncrier \u003chttps://pypi.org/project/towncrier/\u003e`_ for generating CHANGES.\n\n.. _Cookiecutter: https://github.com/audreyr/cookiecutter\n.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fankostis%2Fpolyvers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fankostis%2Fpolyvers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fankostis%2Fpolyvers/lists"}