Version bump your Python project
Project description
Bump My Version
NOTE
This is a maintained refactor of the bump2version fork of the excellent bumpversion project. The main goals of this refactor were:
Overview
Bump My Version's purpose is to:
- Work as a part of an automated build system
- Manage project versioning through the project's development life cycle
- Incrementing version numbers
- serializing version numbers
- parsing version numbers
- supporting SemVer, CalVer, and other versioning schemes
- Modify project files as part of the project's development life cycle
- Work with the project's source control system
- Committing changes
- Tagging releases
- Reading version numbers from tags
Installation
You can download and install the latest version of this software from the Python package index (PyPI) as follows:
pip install --upgrade bump-my-version
Changelog
Please find the changelog here: CHANGELOG.md
Semantic versioning example
Create a default configuration
The default configuration uses a simplified version of semantic versioning.
$ bump-my-version sample-config --no-prompt --destination .bumpversion.toml
$ cat .bumpversion.toml
[tool.bumpversion]
current_version = "0.1.0"
parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
serialize = ["{major}.{minor}.{patch}"]
search = "{current_version}"
replace = "{new_version}"
regex = false
ignore_missing_version = false
tag = false
sign_tags = false
tag_name = "v{new_version}"
tag_message = "Bump version: {current_version} → {new_version}"
allow_dirty = false
commit = false
message = "Bump version: {current_version} → {new_version}"
commit_args = ""
Visualize the versioning path
You can see the potential versioning paths with the show-bump
subcommand.
$ bump-my-version show-bump
0.1.0 ── bump ─┬─ major ─ 1.0.0
├─ minor ─ 0.2.0
╰─ patch ─ 0.1.1
$ bump-my-version show-bump 1.2.3
1.2.3 ── bump ─┬─ major ─ 2.0.0
├─ minor ─ 1.3.0
╰─ patch ─ 1.2.4
The default configuration only allows bumping the major, minor, or patch version. What if you wanted to support pre-release versions?
Add support for pre-release versions
Alter the parse
configuration to support pre-release versions. This parse
option uses an extended (or verbose) regular expression to extract the version components from the current version.
parse = """(?x)
(?P<major>0|[1-9]\\d*)\\.
(?P<minor>0|[1-9]\\d*)\\.
(?P<patch>0|[1-9]\\d*)
(?:
- # dash separator for pre-release section
(?P<pre_l>[a-zA-Z-]+) # pre-release label
(?P<pre_n>0|[1-9]\\d*) # pre-release version number
)? # pre-release section is optional
"""
Alter the serialize
configuration to support pre-release versions.
serialize = [
"{major}.{minor}.{patch}-{pre_l}{pre_n}",
"{major}.{minor}.{patch}",
]
Add a new configuration section for the pre_l
part.
[tool.bumpversion.parts.pre_l]
values = ["dev", "rc", "final"]
optional_value = "final"
Visualize the new versioning path
Now when you run bump-my-version show-bump
, you can see the new pre-release versioning path.
$ bump-my-version show-bump
0.1.0 ── bump ─┬─ major ─ 1.0.0-dev0
├─ minor ─ 0.2.0-dev0
├─ patch ─ 0.1.1-dev0
├─ pre_l ─ invalid: The part has already the maximum value among ['dev', 'rc', 'final'] and cannot be bumped.
╰─ pre_n ─ 0.1.0-final1
The pre_l
is not bump-able because it is already at the maximum value. The pre_n
is bump-able because it is not at the maximum value.
If we run bump-my-version show-bump 1.0.0-dev0
, we can see the new versioning path for a dev
starting version.
$ bump-my-version show-bump 1.0.0-dev0
1.0.0-dev0 ── bump ─┬─ major ─ 2.0.0-dev0
├─ minor ─ 1.1.0-dev0
├─ patch ─ 1.0.1-dev0
├─ pre_l ─ 1.0.0-rc0
╰─ pre_n ─ 1.0.0-dev1
Finally, we can see the new versioning path for a rc
starting version.
$ bump-my-version show-bump 1.0.0-rc0
1.0.0-rc0 ── bump ─┬─ major ─ 2.0.0-dev0
├─ minor ─ 1.1.0-dev0
├─ patch ─ 1.0.1-dev0
├─ pre_l ─ 1.0.0
╰─ pre_n ─ 1.0.0-rc1
The full development and release path is:
1.0.0
bump patch
→1.0.1-dev0
bump pre_n
→1.0.1-dev1
bump pre_l
→1.0.1-rc0
bump pre_n
→1.0.1-rc1
bump pre_l
→1.0.1
- You must decide on the next version before you start developing.
- Development versions increase using
bump-my-version bump pre_n
. - Switch from development to release candidate using
bump-my-version bump pre_l
. - Release candidates increase using
bump-my-version bump pre_n
. - Switch from the release candidate to the final release using
bump-my-version bump pre_l
.
Automate the pre-release numbering
The pre_n
or pre-release number is a number that increases with each pre-release. You can automate this my changing the serialization configuration.
serialize = [
"{major}.{minor}.{patch}-{pre_l}{distance_to_latest_tag}",
"{major}.{minor}.{patch}",
]
The distance_to_latest_tag
is a special value that is replaced with the number of commits since the last tag. This is a good value to use for the pre_n
because it will always increase with each commit.
Visualize the pre_n versioning path
Now when you run bump-my-version show-bump
, you can see the new pre-release versioning path.
$ bump-my-version show-bump
0.1.0 ── bump ─┬─ major ─ 1.0.0-dev0
├─ minor ─ 0.2.0-dev0
├─ patch ─ 0.1.1-dev0
╰─ pre_l ─ invalid: The part has already the maximum value among ['dev', 'rc', 'final'] and cannot be bumped.
$ bump-my-version show-bump 1.0.0-dev0
1.0.0-dev0 ── bump ─┬─ major ─ 2.0.0-dev0
├─ minor ─ 1.1.0-dev0
├─ patch ─ 1.0.1-dev0
╰─ pre_l ─ 1.0.0-rc0
$ bump-my-version show-bump 1.0.0-rc0
1.0.0-rc0 ── bump ─┬─ major ─ 2.0.0-dev0
├─ minor ─ 1.1.0-dev0
├─ patch ─ 1.0.1-dev0
╰─ pre_l ─ 1.0.0
The pre_n
path is now missing because it is automated.
The full development and release path now is:
1.0.0
bump patch
→1.0.1-dev0
- each commit will increase →
1.0.1-dev1
- each commit will increase →
bump pre_l
→1.0.1-rc0
- each commit will increase →
1.0.1-rc1
- each commit will increase →
bump pre_l
→1.0.1
- You must decide on the next version before you start developing.
- Development versions increase automatically with each commit.
- Switch from development to release candidate using
bump-my-version bump pre_l
. - Release candidate versions increase automatically with each commit.
- Switch from the release candidate to the final release using
bump-my-version bump pre_l
.
Development & Contributing
Thank you, contributors! You can find a full list here: https://github.com/callowayproject/bump-my-version/graphs/contributors
See also our CONTRIBUTING.md
Development of this happens on GitHub, patches including tests, and documentation are very welcome, as well as bug reports! Please open an issue if this tool does not support every aspect of bumping versions in your development workflow, as it is intended to be very versatile.
License
Bump My Version is licensed under the MIT License - see the LICENSE file for details
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for bump_my_version-0.26.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fe35ebae91e92deebe809ce06bfa37303e45e4f087ad4a371f605702e767623f |
|
MD5 | 19190357678f2a0461778a4c3a122196 |
|
BLAKE2b-256 | b21a95fbe16cc0b9f4043b69612685b8848aaf5a89a2fa8ac645ba9333b5625d |