From adf997c08202a2a23bdd65c7b7b18ce722f5da75 Mon Sep 17 00:00:00 2001 From: Martynov Maxim Date: Fri, 12 Mar 2021 03:02:18 +0300 Subject: [PATCH] #10 Fix examples in README.md --- README.md | 320 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 306 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index c94bd71..a2eb0dd 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/setuptools-git-versioning)](https://badge.fury.io/py/setuptools-git-versioning) [![Build Status](https://github.com/dolfinus/setuptools-git-versioning/workflows/Tests/badge.svg)](https://github.com/dolfinus/setuptools-git-versioning/actions) -Automatically set package version using git tag/hash +Use git repo data (latest tag, current commit hash, etc) for building a version number according [PEP-440(https://www.python.org/dev/peps/pep-0440/). ## Compairing with other packages @@ -25,27 +25,324 @@ Adding `setup_requires=['setuptools-git-versioning']` somewhere in `setup.py` wi ## Usage -To just use the default templates for versioning: +Just add these lines into your `setup.py`: + ```python + setuptools.setup( + ... + version_config=True, + setup_requires=['setuptools-git-versioning'], + ... + ) + ``` +### Release version = git tag +You want to use git tag as a release number instead of duplicating it setup.py or other file. + +For example, current repo state is: +``` +commit 86269212 Release commit (HEAD, master) +| +commit e7bdbe51 Another commit +| +... +| +commit 273c47eb Long long ago +| +... +``` + +Then you decided to release new version: +- Tag commit with a proper release version (e.g. `v1.0.0` or `1.0.0`): + ``` + commit 86269212 Release commit (v1.0.0, HEAD, master) + | + commit e7bdbe51 Another commit + | + ... + | + commit 273c47eb Long long ago + | + ... + ``` +- Check current version with command `python setup.py --version`. +- You'll get `1.0.0` as a version number. If tag number had `v` prefix, like `v1.0.0`, it will be trimmed. + +#### Version number template +By default, when you try to get current version, you'll receive version number like `1.0.0`. + +You can change this template just in the same `setup.py` file: +```python +setuptools.setup( + ... + version_config={ + "template": "2021.{tag}", + }, + setup_requires=['setuptools-git-versioning'], + ... +) +``` +In this case, for tag `3.4` version number will be `2021.3.4` + +#### Dev template +For example, current repo state is: +``` +commit 86269212 Current commit (HEAD, master) +| +commit 86269212 Release commit (v1.0.0) +| +commit e7bdbe51 Another commit +| +... +| +commit 273c47eb Long long ago +| +... +``` + +By default, when you try to get current version, you'll receive version number like `1.0.0.post1+git.64e68cd`. + +This is a PEP-440 compilant value, but sometimes you want see just `1.0.0.post1` value or even `1.0.0`. + +You can change this template just in the same `setup.py` file: +- For values like `1.0.0.post1`. `N` in `.postN` suffix is a number of commits since previous release (tag): + ```python + setuptools.setup( + ... + version_config={ + "dev_template": "{tag}.dev{ccount}", + }, + setup_requires=['setuptools-git-versioning'], + ... + ) + ``` +- To return just the latest tag value, like `1.0.0`,use these options: + ```python + version_config={ + "dev_template": "{tag}", + } + ``` + +#### Dirty template +For example, current repo state is: +``` +Unstashed changes (HEAD) +| +commit 86269212 Current commit (master) +| +commit 86269212 Release commit (v1.0.0) +| +commit e7bdbe51 Another commit +| +... +| +commit 273c47eb Long long ago +| +... +``` + +By default, when you try to get current version, you'll receive version number like `1.0.0.post1+git.64e68cd.dirty`. +This is a PEP-440 compilant value, but sometimes you want see just `1.0.0.post1` value or even `1.0.0`. + +You can change this template just in the same `setup.py` file: +- For values like `1.0.0.post1`. `N` in `.postN` suffix is a number of commits since previous release (tag): + ```python + setuptools.setup( + ... + version_config={ + "dirty_template": "{tag}.dev{ccount}", + }, + setup_requires=['setuptools-git-versioning'], + ... + ) + ``` +- To return just the latest tag value, like `1.0.0`,use these options: + ```python + version_config={ + "dirty_template": "{tag}", + } + ``` + +#### Set initial version +For example, current repo state is: +``` +commit 86269212 Current commit (HEAD, master) +| +commit e7bdbe51 Another commit +| +... +| +commit 273c47eb Long long ago +| +... +``` +And there are just no tags in the current branch. + +By default, when you try to get current version, you'll receive some initial value, like `0.0.1` + +You can change this template just in the same `setup.py` file: +```python +setuptools.setup( + ... + version_config={ + "starting_version": "1.0.0", + }, + setup_requires=['setuptools-git-versioning'], + ... +) +``` + +### Use callback as current version +For example, current repo state is: +``` +commit 233f6d72 Dev branch commit (HEAD, dev) +| +| commit 86269212 Current commit (v1.0.0, master) +| | +| commit e7bdbe51 Another commit +| / +... +| +commit 273c47eb Long long ago +| +... +``` +And there are just no tags in the current branch (`dev`) because all of them are placed in the `master` branch only. + +By default, when you try to get current version, you'll receive some initial value. But if you want to get syncronized version numbers in both on the branches? + +You can create a function in some file (for example, in the `__init__.py` file of your module): ```python +def get_version(): + return '1.0.0' +``` +Then place it in both the branches and update your `setup.py` file: +```python +from mymodule import get_version + setuptools.setup( ... - version_config=True, + version_config={ + "version_callback": get_version, + }, + setup_requires=['setuptools-git-versioning'], ... +) +``` + +When you'll try to get current version in non-master branch, the result of executing this function will be returned instead of latest tag number. + +If a value of this option is not a function but just str, it also could be used: +- `__init__.py` file: + ```python + __version__ = '1.0.0' + ``` +- `setup.py` file: + ```python + from mymodule import __version__ + + setuptools.setup( + ... + version_config={ + "version_callback": __version__, + }, + setup_requires=['setuptools-git-versioning'], + ... + ) + ``` + +**Please take into account that no tag means `dev_template` or `dirty_template` values are not user because current repo state is ignored in such the case** + + +### Read current version from a file +Just like the previous example, but instead you can save current version in a simple test file instead of `.py` script. + +Just create a file (for example, `VERSION` or `VERSION.txt`) and place here a version number: +``` +1.0.0 +``` +Then place it in both the branches and update your `setup.py` file: +```python +import os + +HERE = os.path.dirname(__file__) +VERSION_FILE = os.path.join(HERE, 'VERSION') + +setuptools.setup( + ... + version_config={ + "version_file": VERSION_FILE, + }, setup_requires=['setuptools-git-versioning'], ... ) ``` -Changing templates (also shows the defaults): +When you'll try to get current version in non-master branch, the content of this file will be returned instead. + +### Development releases (prereleases) from `dev`/`develop` branch + +For example, current repo state is: +``` +commit 233f6d72 Dev branch commit (HEAD, dev) +| +| commit 86269212 Current commit (v1.0.0, master) +| | +| commit e7bdbe51 Another commit +| / +... +| +commit 273c47eb Long long ago +| +... +``` +You want to make development releases (prereleases) from this branch. +But there are just no tags in the current branch (`dev`) because all of them are placed in the `master` branch only. + +Just like the examples above, create a file with a next release number (e.g. `1.1.0`) in the `dev` branch, e.g. `VERSION.txt`: +``` +1.1.0 +``` +But place here **next** release number instead of current one. + +Then update your `setup.py` file: +```python +import os + +HERE = os.path.dirname(__file__) +VERSION_FILE = os.path.join(HERE, 'VERSION.txt') + +setuptools.setup( + ... + version_config={ + "count_commits_from_version_file": True, + "dev_template": "{tag}.dev{ccount}", # suffix now is not .post, but .dev + "dirty_template": "{tag}.dev{ccount}", # same thing here + "version_file": VERSION_FILE + }, + setup_requires=['setuptools-git-versioning'], + ... +) +``` + +Then you decided to release new version: +- Merge `dev` branch into `master` branch. +- Tag commit in the `master` branch with a proper release version (e.g. `v1.1.0`). Tag will be used as a version number for the release. +- Save next release version (e.g. `1.2.0`) in `VERSION` or `version.py` file in the `dev` branch. **Do not place any tags in the `dev` branch!** +- Next commits to a `dev` branch will lead to returning this next release version plus dev suffix, like `1.1.0.dev1` or so. +- `N` in `.devN` suffix is a number of commits since the last change of a certain file. +- **Note: every change of this file in the `dev` branch will lead to this `N` suffix to be reset. Update this file only in the case when you've setting up the next release version!** + +## Options + +Default options are: ```python setuptools.setup( ... version_config={ "template": "{tag}", - "dev_template": "{tag}.dev{ccount}+git.{sha}", - "dirty_template": "{tag}.dev{ccount}+git.{sha}.dirty", + "dev_template": "{tag}.post{ccount}+git.{sha}", + "dirty_template": "{tag}.post{ccount}+git.{sha}.dirty", "starting_version": "0.0.1", "version_callback": None, "version_file": None, @@ -57,8 +354,6 @@ setuptools.setup( ) ``` -### Templates - - `template`: used if no untracked files and latest commit is tagged - `dev_template`: used if no untracked files and latest commit isn't tagged @@ -71,14 +366,11 @@ setuptools.setup( - `version_file`: path to VERSION file, to read version from it instead of using `static_version` -- `count_commits_from_version_file`: `True` to fetch `version_file` last commit instead of tag commit, `False` overwise. Example: +- `count_commits_from_version_file`: `True` to fetch `version_file` last commit instead of tag commit, `False` otherwise - You have a project there tags are added to `master` branch only (e.g. '1.0.0'). - But you also wish to build development version (e.g. '1.0.0.dev0') from each commit to `dev` branch. - But you don't want neither setup tag with CI/CD for every commit to `dev` branch, nor set such tags manually. - So just fill up `version_file`, set `count_commits_from_version_file` to `True` and that's all. +### Substitions -### Format Options +You can use these substitutions in `template`, `dev_template` or `dirty_template` options: - `{tag}`: Latest tag in the repository