technofab/bumpver
1
0
Fork 0
mirror of https://github.com/TECHNOFAB11/bumpver.git synced 2025-12-12 14:30:09 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc updates for new release

Browse source
This commit is contained in:
Manuel Barkhau 2019-01-06 21:48:30 +01:00
parent 630b5cd750
commit d9f98b172b
2 changed files with 105 additions and 65 deletions
Download patch file Download diff file Expand all files Collapse all files

5
CHANGELOG.md
View file

@ -1,6 +1,11 @@
# Changelog for https://gitlab.com/mbarkhau/pycalver # Changelog for https://gitlab.com/mbarkhau/pycalver
## v201901.0019-beta
- Added: Experimental support for many more custom version patterns
## v201812.0018 ## v201812.0018
- Fixed: Better handling of pattern replacements with "-final" releases. - Fixed: Better handling of pattern replacements with "-final" releases.

165
README.md
View file

@ -3,8 +3,8 @@
PyCalVer is for projects that only have one semantic: newer == PyCalVer is for projects that only have one semantic: newer ==
better. PyCalVer version strings are compatible with python better. PyCalVer version strings are compatible with python
packaging software [setuptools][setuptools_ref] and packaging software [setuptools][setuptools_ref] and
[PEP440][pep_440_ref], but can in principle be used with any [PEP440][pep_440_ref], but can in principle be used for projects
project. of any language.
Project/Repo: Project/Repo:
@ -60,7 +60,7 @@ version strings. The version strings have three parts:
``` ```
o Year and Month of Build o Year and Month of Release
| o Sequential Build Number | o Sequential Build Number
| | o Release Tag (optional) | | o Release Tag (optional)
| | | | | |
@ -100,20 +100,20 @@ If you are familiar with these, feel free to skip ahead to
## Semantics of PyCalVer ## Semantics of PyCalVer
> Disclaimer: This section is aspirational and of course there > Disclaimer: This section is aspirational. There is nothing to
> is nothing to prevent package maintainers from publishing > prevent package maintainers from publishing packages with
> packages with different semantics than what is laid out here. > different semantics than what is laid out here.
PyCalVer places a greater burden on package maintainers than PyCalVer places a greater burden on package maintainers than
SemVer. Backward incompatibility is not encoded, because SemVer. Backward incompatibility is not encoded in the version
maintainers should not make any breaking changes. This is great string, because maintainers should not make any breaking changes.
for users of a package, who can worry a bit less about an update This is great for users of a package, who can worry a bit less
breaking their project. If they're paranoid, they can of course about an update breaking their project. If users are paranoid,
still pin to known good versions, but ideally they don't need they can of course still pin to known good versions, but ideally
version specifier in their requirements.txt so they always get they don't need version specifier in their requirements.txt so
the latest bug fixes and features. Ideally users can trust the they always get the latest bug fixes and features. Ideally users
promise of a maintainer that the following semantics will always can trust the promise of a maintainer that the following
be true: semantics will always be true:
- Newer is compatible. - Newer is compatible.
- Newer has fewer bugs. - Newer has fewer bugs.
@ -121,7 +121,7 @@ be true:
- Newer has similar or better performance. - Newer has similar or better performance.
The world is not ideal of course, so how do users and The world is not ideal of course, so how do users and
maintainers deal with changes that might violate these promises? maintainers deal with changes that violate these promises?
### Breaking Changes ### Breaking Changes
@ -129,9 +129,9 @@ maintainers deal with changes that might violate these promises?
> Namespaces are one honking great idea > Namespaces are one honking great idea
> -- let's do more of those! > -- let's do more of those!
If you must make a breaking change to a package, *instead of If you must make a breaking change to a package, **instead of
incrementing a number*, the recommended approach with PyCalVer incrementing a number**, the recommended approach with PyCalVer
is to *create a whole new package*. Put differently, the major is to **create a whole new package**. Put differently, the major
version becomes part of the package/module namespace. Typically version becomes part of the package/module namespace. Typically
you might add a numerical suffix, eg. `mypkg -> mypkg2`. you might add a numerical suffix, eg. `mypkg -> mypkg2`.
@ -191,20 +191,21 @@ v201901.0670 # final release after testing
``` ```
In the absolute worst case, a change is discovered to break In the absolute worst case, a change is discovered to break
backward compatibility, but the change is still considered to be backward compatibility, but the change is nonetheless considered
desirable. At that point, a new release should be made to revert to be desirable. At that point, a new release should be made to
the change. This way: revert the change. This allows users:
- users who were not exposed to the breaking change will - who were exposed to the breaking change to update to the
download the the newest release with the reverted changes. latest release and get the old working code again.
- users who were exposed to the breaking change can update to - who were not exposed to the breaking change to download the
the latest release and get the old working code again. the newest release with the reverted changes and never even
know anything was wrong.
Remember that the goal is to always make things easy for users Remember that the goal is to always make things easy for users
who depend on a package. If there is any issue whatsoever, all who have your package as a dependency. If there is any issue
they should have to do is `pip install --update`. If this whatsoever, all they should have to do is `pip install --update`.
doesn't work, they may have to temporarily pin to a known good If this doesn't work, they may have to *temporarily* pin to a known
version of a dependency, at least until a fixed release is good version of a dependency, at least until a fixed release is
uploaded. uploaded.
After this immediate fire has been put out, if the maintainer After this immediate fire has been put out, if the maintainer
@ -284,8 +285,8 @@ import re
# https://regex101.com/r/fnj60p/10 # https://regex101.com/r/fnj60p/10
PYCALVER_PATTERN = r""" PYCALVER_PATTERN = r"""
\b \b
(?P<version> (?P<pycalver>
(?P<calver> (?P<vYYYYMM>
v # "v" version prefix v # "v" version prefix
(?P<year>\d{4}) (?P<year>\d{4})
(?P<month>\d{2}) (?P<month>\d{2})
@ -306,8 +307,8 @@ version_str = "v201712.0001-alpha"
version_info = PYCALVER_RE.match(version_str).groupdict() version_info = PYCALVER_RE.match(version_str).groupdict()
assert version_info == { assert version_info == {
"version" : "v201712.0001-alpha", "pycalver": "v201712.0001-alpha",
"calver" : "v201712", "vYYYYMM" : "v201712",
"year" : "2017", "year" : "2017",
"month" : "12", "month" : "12",
"build" : ".0001", "build" : ".0001",
@ -318,8 +319,8 @@ version_str = "v201712.0033"
version_info = PYCALVER_RE.match(version_str).groupdict() version_info = PYCALVER_RE.match(version_str).groupdict()
assert version_info == { assert version_info == {
"version" : "v201712.0033", "pycalver": "v201712.0033",
"calver" : "v201712", "vYYYYMM" : "v201712",
"year" : "2017", "year" : "2017",
"month" : "12", "month" : "12",
"build" : ".0033", "build" : ".0033",
@ -336,7 +337,7 @@ To see how version strings are incremented, we can use
$ pip install pycalver $ pip install pycalver
... ...
Successfully installed pycalver-201812.18 Successfully installed pycalver-201812.18
$ pycavler --version $ pycalver --version
pycalver, version v201812.0018 pycalver, version v201812.0018
$ pycalver test v201801.0033-beta $ pycalver test v201801.0033-beta
PyCalVer Version: v201809.0034-beta PyCalVer Version: v201809.0034-beta
@ -385,19 +386,21 @@ This will add the something like the following to your
```ini ```ini
[pycalver] [pycalver]
current_version = v201809.0001-beta
version_pattern = {pycalver}
commit = True commit = True
tag = True tag = True
push = True push = True
[pycalver:file_patterns] [pycalver:file_patterns]
setup.cfg = setup.cfg =
current_version = {version} current_version = {pycalver}
setup.py = setup.py =
"{version}", "{pycalver}",
"{pep440_version}", "{pep440_pycalver}",
README.md = README.md =
{version} {pycalver}
{pep440_version} {pep440_pycalver}
``` ```
This probably won't cover all instances of version numbers across This probably won't cover all instances of version numbers across
@ -407,17 +410,18 @@ additional changes you might need to make.
```ini ```ini
[pycalver] [pycalver]
current_version = v201809.0001-beta current_version = v201809.0001-beta
version_pattern = {pycalver}
commit = True commit = True
tag = True tag = True
push = True push = True
[pycalver:file_patterns] [pycalver:file_patterns]
setup.cfg = setup.cfg =
current_version = {version} current_version = {pycalver}
setup.py = setup.py =
version="{pep440_version}" version="{pep440_pycalver}"
myproject/__init__.py = myproject/__init__.py =
__version__ = "{version}" __version__ = "{pycalver}"
README.md = README.md =
[PyCalVer {calver}{build}{release}] [PyCalVer {calver}{build}{release}]
img.shields.io/badge/PyCalVer-{calver}{build}-{release}-blue img.shields.io/badge/PyCalVer-{calver}{build}-{release}-blue
@ -465,47 +469,50 @@ projects files. The following placeholders are available for
use, everything else in a pattern is treated as literal text. use, everything else in a pattern is treated as literal text.
| placeholder | example | | placeholder | range / example(s) |
|--------------------|--------------------| |---------------------|--------------------|
| `{pep440_version}` | 201809.1b0 | | `{pycalver}` | v201809.0001-beta |
| `{version}` | v201809.0001-alpha | | `{semver}` | 1.2.3 |
| `{calver}` | v201809 | | `{pep440_pycalver}` | 201809.1b0 |
| `{year}` | 2018 | | `{year}` | 2018... |
| `{month}` | 09 | | `{month}` | 09, 10, 11, 12 |
| `{build}` | .0001 | | `{build}` | .0123 |
| `{build_no}` | 0001 | | `{build_no}` | 0123, 12345 |
| `{release}` | -alpha | | `{release}` | -alpha |
| `{release_tag}` | alpha | | `{release_tag}` | alpha |
There are two limitations to keep in mind: There are some limitations to keep in mind:
1. A version string cannot span multiple lines. 1. A version string cannot span multiple lines.
2. There is no way to escape "-", "." characters (yet). 2. There is no way to escape "-", "." characters (yet).
3. The timezone is always UTC.
The lack of escaping may for example be an issue with badge URLs. The lack of escaping may for example be an issue with badge URLs.
You may want to put the following text in your README.md (note the You may want to put the following text in your README.md (note
two dashes before `beta` are parsed as a literal dash by shields.io): that shields.io parses the two "-" dashes before `beta` as one
literal "-"):
``` ```
https://img.shields.io/badge/myproject-v201812.0116--beta-blue.svg https://img.shields.io/badge/myproject-v201812.0116--beta-blue.svg
``` ```
While could use the following pattern, which will work for a while: While could use the following pattern, which will work fine for a
while:
```ini ```ini
README.md = README.md =
/badge/myproject-v{year}{month}.{build_no}--{release_tag}-blue.svg /badge/myproject-v{year}{month}.{build_no}--{release_tag}-blue.svg
``` ```
This will eventually break though, when you do a `final` release, at Eventually thie will break, when you do a `final` release, at
which point the following will be put in your README.md: which point the following will be put in your README.md:
``` ```
https://img.shields.io/badge/myproject-v201812.0117--final-blue.svg https://img.shields.io/badge/myproject-v201812.0117--final-blue.svg
``` ```
Whereas what you probably wanted was this: What you probably wanted was this:
``` ```
https://img.shields.io/badge/myproject-v201812.0117-blue.svg https://img.shields.io/badge/myproject-v201812.0117-blue.svg
@ -516,6 +523,34 @@ should be ashamed for releasing PyCalVer with such a monumental
deficiency. deficiency.
### Support for Other Versioning Schemes
Besides the default version string pattern, pycalver also supports.
| placeholder | comment | range / example(s) | padding | lexical id |
|--------------|-------------------------|-----------------------|----------|------------|
| `{year}` | `strftime %Y` | 2018... | | |
| `{yy}` | `strftime %y` | 18, 19..99, 01, 02 | | |
| `{quarter}` | | 1, 2, 3, 4 | | |
| `{month}` | `strftime %m` | 09, 10, 11, 12 | yes (2) | |
| `{iso_week}` | `strftime %W` | 00..53 | yes (2) | |
| `{us_week}` | `strftime %U` | 00..53 | yes (2) | |
| `{dom}` | `strftime %d` | 01..31 | yes (2) | |
| `{doy}` | `strftime %j` | 001..366 | yes (3) | |
| `{MAJOR}` | `bump --major` | 1..9, 10..99, 100.. | no | |
| `{MINOR}` | `bump --minor` | 1..9, 10..99, 100.. | no | no |
| `{MM}` | `bump --minor` | 01..08, 09, 10... | yes (2+) | no |
| `{MMM}` | `bump --minor` | 001..098, 099, 1100.. | yes (3+) | no |
| ... | | | | |
| `{PATCH}` | | 1, 10, 101 | no | no |
| `{bid}` | | 0123, 12345 | yes (4+) | yes |
| `{BID}` | | 1, 1234 | no | no |
| `{tag}` | | alpha | | |
### Bump It Up ### Bump It Up
The current version that will be bumped is defined either as The current version that will be bumped is defined either as
@ -531,15 +566,15 @@ As part of doing `pycalver bump`, your local VCS index is updated
using `git fetch --tags`/`hg pull`. This ensures that all tags using `git fetch --tags`/`hg pull`. This ensures that all tags
are known locally and the same version is not generated for are known locally and the same version is not generated for
different commits, and mitigates the risk of a rare corner case, different commits, and mitigates the risk of a rare corner case,
where `p`pycalver bump` is invoked on different machines. If you're where `pycalver bump` is invoked on different machines. If you
the only maintainer, you can always use `-n/--no-fetch`. are the sole maintainer, you can always use `-n/--no-fetch`.
```shell ```shell
$ pycalver show --verbose $ pycalver show --verbose
INFO - fetching tags from remote (to turn off use: -n / --no-fetch) INFO - fetching tags from remote (to turn off use: -n / --no-fetch)
Current Version: v201812.0005-beta Current Version: v201812.0005-beta
PEP440 Version : 201812.5b0 PEP440 : 201812.5b0
``` ```