From e0cebb3ecaac58a8b7a8773847079fe1a7cd3035 Mon Sep 17 00:00:00 2001 From: Corey Oordt Date: Wed, 12 Apr 2023 09:14:37 -0500 Subject: [PATCH] Updated README and other documentation --- README.md | 154 ++++++++-- docsrc/_static/css/custom.css | 26 ++ docsrc/cli.rst | 4 +- docsrc/conf.py | 5 +- docsrc/configuration.md | 511 ++++++++++++++++++++++++++++++++++ docsrc/index.md | 2 + docsrc/search-and-replace.md | 90 ++++++ docsrc/usage.md | 49 +++- docsrc/version-parts.md | 112 ++++++++ 9 files changed, 921 insertions(+), 32 deletions(-) create mode 100644 docsrc/configuration.md create mode 100644 docsrc/search-and-replace.md create mode 100644 docsrc/version-parts.md diff --git a/README.md b/README.md index c46af258..6258727b 100644 --- a/README.md +++ b/README.md @@ -1,53 +1,157 @@ # Bump My Version -Version bump your Python project +[![image](https://img.shields.io/pypi/v/bump-my-version.svg)](https://pypi.org/project/bump-my-version/) +[![image](https://img.shields.io/pypi/l/bump-my-version.svg)](https://pypi.org/project/bump-my-version/) +[![image](https://img.shields.io/pypi/pyversions/bump-my-version.svg)](https://pypi.org/project/bump-my-version/) +[![GitHub Actions](https://github.com/callowayproject/bump-my-version/workflows/CI/badge.svg)](https://github.com/callowayproject/bump-my-version/actions) -*Put a meaningful, short, plain-language description of:* +> **NOTE** +> +> This is a maintained refactor of the [bump2version fork of](https://github.com/c4urself/bump2version) the excellent [bumpversion project](https://github.com/peritus/bumpversion). The main goals of this refactor were: +> +> - Add support for `pyproject.toml` configuration files. +> - Convert to [click](https://click.palletsprojects.com/en/8.1.x/) for and [rich](https://rich.readthedocs.io/en/stable/index.html) for the CLI interface +> - Add better configuration validation using [Pydantic](https://docs.pydantic.dev) +> - Make the code and tests easier to read and maintain -- *what this project is trying to accomplish.* -- *why it matters.* -- *the problem(s) this project solves.* -- *how this software can improve the lives of its audience.* -- *what sets this apart from related-projects. Linking to another doc or page is OK if this can't be expressed in a sentence or two.* -**Technology stack:** *Indicate the technological nature of the software, including primary programming language(s) and whether the software is intended as standalone or as a module in a framework or other ecosystem.* +## Overview -**Status:** *Alpha, Beta, 1.1, etc. It's OK to write a sentence, too. The goal is to let interested people know where this project is at. This is also a good place to link to the CHANGELOG.md.* +Version-bump your software with a single command! -**Links:** to production or demo instances +A small command line tool to simplify releasing software by updating all +version strings in your source code by the correct increment. Also creates +commits and tags: +* version formats are highly configurable +* works without any source code manager, but happily reads tag information from and writes + commits and tags to Git and Mercurial if available +* just handles text files, so it's not specific to any programming language +* supports Python 3 and PyPy3 -## Dependencies -*Describe any dependencies that must be installed for this software to work. This includes programming languages, databases or other storage mechanisms, build tools, frameworks, and so forth. If specific versions of other software are required, or known not to work, call that out.* +## Alternatives + +If bump-my-version does not fully suit your needs, you could take a look +at other tools doing similar or related tasks: +[ALTERNATIVES.md](https://github.com/c4urself/bump-my-version/blob/master/RELATED.md). ## Installation -_Detailed instructions on how to install, configure, and get the project running. This should be frequently tested to ensure reliability. Alternatively, link to a separate INSTALL document._ +You can download and install the latest version of this software from the Python package index (PyPI) as follows: + +```console +pip install --upgrade bump-my-version +``` -## Configuration +## Changelog -_If the software is configurable, describe it in detail, either here or in other documentation to which you link._ +Please find the changelog here: [CHANGELOG.md](CHANGELOG.md) ## Usage -_Show users how to use the software. Be specific. Use appropriate formatting when showing code snippets._ +> **NOTE:** +> +> Throughout this document, you can use `bumpversion` or `bump-my-version` interchangeably. + +There are two modes of operation: On the command line for single-file operation and using a configuration file for more complex multi-file operations. + + bump-my-version [options] part [file] + +### `part` + +_**required**_ + +The part of the version to increase, e.g. `minor`. + +Valid values include the named groups defined in the `parse` configuration. + +Example bumping 0.5.1 to 0.6.0: + + bump-my-version --current-version 0.5.1 minor + +### `file` + +_**[optional]**_
+**default**: none + +Additional files to modify. + +These files are added to the list of files specified in your configuration file. If you want to rewrite only files specified on the command line, also use `--no-configured-files`. + +Example bumping 1.1.9 to 2.0.0: + + bump-my-version --current-version 1.1.9 major setup.py + +## Configuration file + +`bump-my-version` looks in four places for the configuration file to parse (in order of precedence): + +1. `--config-file ` _(command line argument)_ +2. `BUMPVERSION_CONFIG_FILE=file` _(environment variable)_ +3. `.bumpversion.cfg` _(legacy)_ +4. `.bumpversion.toml` +5. `setup.cfg` _(legacy)_ +6. `pyproject.toml` + +`.toml` files are recommended due to their type handling. We will likely drop support for `ini`-style formats in the future due to issues with formatting and parsing. You should add your configuration file to your source code management system. + +By using a configuration file, you no longer need to specify those options on the command line. The configuration file also allows greater flexibility in specifying how files are modified. + +## Command-line Options + +Most of the configuration values above can also be given as an option on the command line. +Additionally, the following options are available: + +`--dry-run, -n` +Don't touch any files, just pretend. Best used with `--verbose`. + +`--no-configured-files` +Will not update/check files specified in the configuration file. + +Similar to dry-run, but will also avoid checking the files. Also useful when you want to update just one file with e.g., `bump-my-version --no-configured-files major my-file.txt` + +`--verbose, -v` +Print useful information to stderr. If specified more than once, it will output more information. + +`--list` +List machine-readable information to stdout for consumption by other programs. + +Example output: + + current_version=0.0.18 + new_version=0.0.19 + +`-h, --help` +Print help and exit + +## Using bumpversion in a script + +If you need to use the version generated by bumpversion in a script you can make use of the `--list` option, combined with `grep` and `sed`. + +Say for example that you are using git-flow to manage your project and want to automatically create a release. When you issue `git flow release start` you already need to know the new version, before applying the change. + +The standard way to get it in a bash script is -## How to test the software + bump-my-version --dry-run --list | grep | sed -r s,"^.*=",, -_If the software includes automated tests, detail how to run those tests._ +where `part` is as usual the part of the version number you are updating. You need to specify `--dry-run` to avoid bumpversion acting. -## Known issues +For example, if you are updating the minor number and looking for the new version number this becomes -_Document any known significant shortcomings with the software._ + bump-my-version --dry-run --list minor | grep new_version | sed -r s,"^.*=",, -## Getting help +## Development & Contributing -_Instruct users how to get help with this software; this might include links to an issue tracker, wiki, mailing list, etc._ +Thank you, contributors! You can find a full list here: https://github.com/callowayproject/bump-my-version/graphs/contributors +See also our [CONTRIBUTING.md](CONTRIBUTING.md) -## Getting involved +Development of this happens on GitHub, patches including tests, and documentation +are very welcome, as well as bug reports! Also 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. -_This section should detail why people should get involved and describe key areas you are currently focusing on; e.g., trying to get feedback on features, fixing certain bugs, building important pieces, etc._ +## License -_General instructions on how to contribute should be stated with a link to CONTRIBUTING.md._ +bump-my-version is licensed under the MIT License - see the [LICENSE](LICENSE) file for details diff --git a/docsrc/_static/css/custom.css b/docsrc/_static/css/custom.css index 74868684..cb3ea675 100644 --- a/docsrc/_static/css/custom.css +++ b/docsrc/_static/css/custom.css @@ -1,11 +1,37 @@ .class .sig-prename.descclassname { display: none; } + .subheading { line-height: 1.25; margin-bottom: 0; color: #646776; } + .subheading + section > h1 { margin-top: 0; } + +.field-list p { + margin: 0; +} + +dl.field-list { + display: grid; + grid-template-columns: fit-content(30%) auto; + margin-bottom: 1rem; +} + +dl.field-list > dt { + font-weight: bold; + word-break: break-word; + padding-left: 0.5em; + padding-right: 5px; +} + +dl.field-list > dd { + padding-left: 0.5em; + margin-top: 0; + margin-left: 0; + margin-bottom: 0; +} diff --git a/docsrc/cli.rst b/docsrc/cli.rst index 517d7187..cc17c60b 100644 --- a/docsrc/cli.rst +++ b/docsrc/cli.rst @@ -1,6 +1,6 @@ Command-line Interface ====================== -.. click:: bump_version.cli:cli - :prog: bump_version +.. click:: bumpversion.cli:cli + :prog: bumpversion :nested: full diff --git a/docsrc/conf.py b/docsrc/conf.py index f5f3e103..2d7e3c02 100644 --- a/docsrc/conf.py +++ b/docsrc/conf.py @@ -11,8 +11,8 @@ import bumpversion project = "bump-my-version" -copyright = f"{date.today():%Y}, C H Robinson" -author = "Data Science Team" +copyright = f"{date.today():%Y} Calloway Project" +author = "Contributors" version = bumpversion.__version__ release = bumpversion.__version__ @@ -64,6 +64,7 @@ "smartquotes", "substitution", "tasklist", + "fieldlist", ] intersphinx_mapping = { "python": ("https://docs.python.org/3", None), diff --git a/docsrc/configuration.md b/docsrc/configuration.md new file mode 100644 index 00000000..8b0df58c --- /dev/null +++ b/docsrc/configuration.md @@ -0,0 +1,511 @@ +# Configuration + +`bump-my-version` looks in three places for configuration information (in order of precedence): + +1. command line +2. configuration file +3. environment variables + + +## Configuration files + +`bump-my-version` looks in four places for the configuration file to parse (in order of precedence): + +1. `--config-file ` _(command line argument)_ +2. `BUMPVERSION_CONFIG_FILE=file` _(environment variable)_ +3. `.bumpversion.cfg` _(legacy)_ +4. `.bumpversion.toml` +5. `setup.cfg` _(legacy)_ +6. `pyproject.toml` + +`.toml` files are recommended. We will likely drop support for `ini`-style formats in the future. You should add your configuration file to your source code management system. + +By using a configuration file, you no longer need to specify those options on the command line. The configuration file also allows greater flexibility in specifying how files are modified. + + +## Global Configuration + +The general configuration is grouped in a `[tool.bumpversion]` or `[bumpversion]` section, depending on if it is a TOML or INI file respectfully. + +TOML example: + +```toml +[tool.bumpversion] +allow_dirty = false +commit = false +message = "Bump version: {current_version} → {new_version}" +commit_args = "" +tag = false +sign_tags = false +tag_name = "v{new_version}" +tag_message = "Bump version: {current_version} → {new_version}" +current_version = "1.0.0" +parse = "(?P\\d+)\\.(?P\\d+)\\.(?P\\d+)" +serialize = [ + "{major}.{minor}.{patch}" +] +search = "{current_version}" +replace = "{new_version}" +``` + +INI-style example: + +```ini +[bumpversion] +allow_dirty = False +commit = False +message = Bump version: {current_version} → {new_version} +commit_args = +tag = False +sign_tags = False +tag_name = v{new_version} +tag_message = Bump version: {current_version} → {new_version} +current_version = 1.0.0 +parse = (?P\d+)\.(?P\d+)\.(?P\d+) +serialize = + {major}.{minor}.{patch} +search = {current_version} +replace = {new_version} +``` + +### `allow_dirty` + +:required: No + +:default: `False` (Don't do anything if there are uncommitted changes) + +:type: boolean + +:command line option: `--allow-dirty | --no-allow-dirty` + +:environment var: `BUMPVERSION_ALLOW_DIRTY` + +Bump-my-version's default behavior is to abort if the working directory is dirty. This is to protect you from releasing unversioned files and/or overwriting unsaved changes. + +### `commit` + +:required: No + +:default: `False` (Don't create a commit) + +:type: boolean + +:command line option: `--commit | --no-commit` + +:environment var: `BUMPVERSION_COMMIT` + +Whether to create a commit using git or Mercurial. + +If you have pre-commit hooks, you might also want to add an option to [`commit_args`](#commit-args) to disable your pre-commit hooks. For Git use `--no-verify` and use `--config hooks.pre-commit=` for Mercurial. + +### `message` + +:required: No + +:default: `Bump version: {current_version} → {new_version}` + +:type: string + +:command line option: `--message` + +:environment var: `BUMPVERSION_MESSAGE` + +The commit message template to use when creating a commit. This is only used when the [`commit`](#commit) option is set to `True`. + +This string is templated using the [Python Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax). Available in the template context are: + +- `current_version` +- `new_version` +- `current_[part]` (e.g. `current_major`) +- `new_[part]` (e.g. `new_major`) +- all environment variables are exposed, prefixed with `$`, such as `$BUILD_NUMBER` +- `now` or `utcnow` to get a current timestamp. Both accept [datetime formatting](https://docs.python.org/3.11/library/datetime.html#strftime-and-strptime-behavior) (e.g. `{now:%d.%m.%Y}`). + +### `commit_args` + +:required: No + +:default: `""` + +:type: string + +:command line option: `--commit-args` + +:environment var: `BUMPVERSION_COMMIT_ARGS` + +Extra arguments to pass to commit command. This is only used when the [`commit`](#commit) option is set to `True`. + +If you have pre-commit hooks, you might also want to add an option to disable your pre-commit hooks. For Git use `--no-verify` and use `--config hooks.pre-commit=` for Mercurial. + +### `tag` + +:required: No + +:default: `False` (Don't create a tag) + +:type: boolean + +:command line option: `(--tag | --no-tag)` + +:environment var: `BUMPVERSION_TAG` + +If `True`, create a tag after committing the changes. The tag is named using the [`tag_name`](#tag-name) option. + +If you are using `git`, don't forget to `git-push` with the `--tags` flag when you are done. + +### `sign_tags` +:required: No + +:default: `False` (Don't sign tags) + +:type: boolean + +:command line option: `(--sign-tags | --no-sign-tags)` + +:environment var: `BUMPVERSION_SIGN_TAGS` + +If `True`, sign the created tag, when [`tag`](#tag) is `True`. + +### `tag_name` +:required: No + +:default: `v{new_version}` + +:type: string + +:command line option: `--tag-name` + +:environment var: `BUMPVERSION_TAG_NAME` + +The name template used to render the tag, when [`tag`](#tag) is `True`. + +This string is templated using the [Python Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax). Available in the template context are: + +- `current_version` +- `new_version` +- `current_[part]` (e.g. `current_major`) +- `new_[part]` (e.g. `new_major`) +- all environment variables are exposed, prefixed with `$`, such as `$BUILD_NUMBER` +- `now` or `utcnow` to get a current timestamp. Both accept [datetime formatting](https://docs.python.org/3.11/library/datetime.html#strftime-and-strptime-behavior) (e.g. `{now:%d.%m.%Y}`). + +### `tag_message` +:required: No + +:default: `Bump version: {current_version} → {new_version}` + +:type: string + +:command line option: `--tag-message` + +:environment var: `BUMPVERSION_TAG_MESSAGE` + +The tag message template to use when creating a tag, when [`tag`](#tag) is `True` + +This string is templated using the [Python Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax). Available in the template context are: + +- `current_version` +- `new_version` +- `current_[part]` (e.g. `current_major`) +- `new_[part]` (e.g. `new_major`) +- all environment variables are exposed, prefixed with `$`, such as `$BUILD_NUMBER` +- `now` or `utcnow` to get a current timestamp. Both accept [datetime formatting](https://docs.python.org/3.11/library/datetime.html#strftime-and-strptime-behavior) (e.g. `{now:%d.%m.%Y}`). + +`bump-my-version` creates an *annotated* tag in Git by default. To disable this and create a *lightweight* tag, you must explicitly set an empty `tag_message`: + +### `current_version` + +:required: **Yes** + +:default: `""` + +:type: string + +:command line option: `--current-version` + +:environment var: `BUMPVERSION_CURRENT_VERSION` + +The current version of the software package before bumping. A value for this is required. + +### `parse` +:required: No + +:default: `(?P\d+)\.(?P\d+)\.(?P\d+)` + +:type: string + +:command line option: `--parse` + +:environment var: `BUMPVERSION_PARSE` + +This is the default regular expression (using [Python regular expression syntax](https://docs.python.org/3/library/re.html#regular-expression-syntax)) for finding and parsing the version string into its components. Individual part or file configurations may override this. + +The regular expression must be able to parse all strings produced by the configured [`serialize`](#serialize) value. Named matching groups ("`(?P...)`") indicate the version part the matched value belongs to. + +### `serialize` +:required: No + +:default: `["{major}.{minor}.{patch}"]` + +:type: an array of strings + +:command line option: `--serialize` + +:environment var: `BUMPVERSION_SERIALIZE` + +This is the default list of templates specifying how to serialize the version parts back to a version string. Individual part or file configurations may override this. + +Since version parts can be optional, bumpversion will try the serialization formats beginning with the first and choose the last one where all values can all non-optional values are represented. + +In this example (in TOML): + +```toml +serialize = [ + "{major}.{minor}.{patch}", + "{major}.{minor}", + "{major}" +] +``` + +Since `0` is optional by default, Version `1.8.9` will serialize to `1.8.9`, `1.9.0` will serialize to `1.9`, and version `2.0.0` will serialize as `2`. + +Each string is templated using the [Python Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax). Available in the template context are: + +- Each named group from the `parse` regular expression (e.g. `major`, `minor`, and `patch`) +- `current_version` +- `new_version` +- `current_[part]` (e.g. `current_major`) +- `new_[part]` (e.g. `new_major`) +- all environment variables are exposed, prefixed with `$`, such as `$BUILD_NUMBER` +- `now` or `utcnow` to get a current timestamp. Both accept [datetime formatting](https://docs.python.org/3.11/library/datetime.html#strftime-and-strptime-behavior) (e.g. `{now:%d.%m.%Y}`). + +### `search` +:required: No + +:default: `{current_version}` + +:type: string + +:command line option: `--search` + +:environment var: `BUMPVERSION_SEARCH` + +This is the template string how to search for the string to be replaced in the file. Individual file configurations may override this. This can span multiple lines, and is templated using [Python Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax). + +This is useful if there is the remotest possibility that the current version number might be present multiple times in the file and you mean to only bump one of the occurrences. + +### `replace` +:required: No + +:default: `{new_version}` + +:type: string + +:command line option: `--replace` + +:environment var: `BUMPVERSION_REPLACE` + +This is the template to create the string that will replace the current version number in the file. + +## Version part-specific configuration + +Version part configuration is grouped in a `[tool.bumpversion.parts.]` or `[bumpversion:part:]` section, depending on if it is a TOML or INI file respectfully. + +You only need to configure version parts if they deviate from the default, and then you only need to specify the options that are different. + +TOML example: + +```toml +[tool.bumpversion.parts.release] +values = [ + "alpha", + "beta", + "gamma" +] +optional_value = "gamma" +``` + +INI-style example: + +```ini +[bumpversion:part:release] +optional_value = gamma +values = + alpha + beta + gamma +``` + +### `values` + +:required: No + +:default: numeric (i.e. `0`, `1`, `2`, …) + +:type: an array of strings. An empty array is treated as indicating `numeric` values. + +An explicit list of all values to iterate through when bumping this part. + +### `optional_value` +:required: No + +:default: The first entry in `values`, `0` when using numeric values + +:type: string + +When the version part matches this value it is considered optional when serializing the final version string. + +:::{note} + +Numeric values are still treated as strings internally, so when specifying an optional value, you must use a string. + +::: + +### `first_value` +:required: No + +:default: The first entry in `values`, `0` when using numeric values + +:type: string + +When the part is reset, the value will be set to the value specified here. + +:::{note} + +Numeric values are still treated as strings internally, so when specifying a first value, you must use a string. + +::: + + +### `independent` +:required: No + +:default: `False` + +:type: boolean + +When this value is set to `True`, the part is not reset when other parts are incremented. Its incrementation is +independent of the other parts. It is useful when you have a build number in your version that is incremented independently of the actual version. + + +## File-specific configuration + +This section configures which files bump-my-version should update by replacing their current version with the newly bumped version. + +### INI-style configuration files + +INI-style configuration is in the section: `[bumpversion:file:]` or `[bumpversion:glob:]`. + +Both, `file:` and `glob:` are configured the same. Their difference is that file will match file names directly like `requirements.txt`. While glob also matches multiple files via wildcards like `**/pom.xml`. + +:::{note} + +The configuration file format requires each section header to be unique. If you want to process a certain file multiple times, you may append a description between parens to the `file` keyword: `[bumpversion:file (special one):…]`. + +::: + +For example, to change `coolapp/__init__.py` with the defaults, and alter `CHANGELOG.md` in twice: + +```ini +[bumpversion:file:coolapp/__init__.py] + +[bumpversion:file(version heading):CHANGELOG.md] +search = Unreleased + +[bumpversion:file(previous version):CHANGELOG.md] +search = {current_version}...HEAD +replace = {current_version}...{new_version} +``` + +### TOML configuration files + +TOML allows us to specify the files using an [array of tables.](https://toml.io/en/v1.0.0#array-of-tables) TOML configuration files add two configuration fields to each file configuration: `filename` and `glob`. These fields are mutually exclusive: if you specify a value for both, only the `glob` value is used. + +For example, to change `coolapp/__init__.py` with the defaults, and alter `CHANGELOG.md` in twice: + +```toml +[[tool.bumpversion.files]] +filename = "coolapp/__init__.py" + +[[tool.bumpversion.files]] +filename = "CHANGELOG.md" +search = "Unreleased" + +[[tool.bumpversion.files]] +filename = "CHANGELOG.md" +search = "{current_version}...HEAD" +replace = "{current_version}...{new_version}" +``` + +### `filename` + +:required: **Yes‡** + +:default: empty + +:type: string + +The name of the file to modify. + +:::{Note} + +‡ This is only used with TOML configuration, and is only required if [`glob`](#glob) is _not_ specified. INI-style configuration files specify the file name as part of the grouping. + +::: + +### `glob` + +:required: **Yes‡** + +:default: empty + +:type: string + +The glob pattern specifying the files to modify. + +:::{Note} + +‡ This is only used with TOML configuration, and is only required if [`filename`](#filename) is _not_ specified. INI-style configuration files specify the glob pattern as part of the grouping. + +::: + +### `parse` + +:required: No + +:default: the value configured in the global `parse` field + +:type: string + +This is an override to the default pattern to parse the version number from this file. + +### `serialize` + +:required: No + +:default: The value configured in the global `serialize` field + +:type: an array of strings + +This is an override to the default templates to serialize the new version number in this file. + +### `search` + +:required: No + +:default: The value configured in the global `search` field + +:type: string + +This is an override to the default template string how to search for the string to be replaced in the file. + +### `replace` + +:required: No + +:default: The value configured in the global `replace` field + +:type: string + +This is an override to the template to create the string that will replace the current version number in the file. + +## diff --git a/docsrc/index.md b/docsrc/index.md index d4f5fe3c..9185eca9 100644 --- a/docsrc/index.md +++ b/docsrc/index.md @@ -7,6 +7,8 @@ caption: Contents --- Introduction usage +configuration +cli api contributing changelog diff --git a/docsrc/search-and-replace.md b/docsrc/search-and-replace.md new file mode 100644 index 00000000..5b3d38ca --- /dev/null +++ b/docsrc/search-and-replace.md @@ -0,0 +1,90 @@ +# Searching and replacing versions + +Given this `requirements.txt`: + + Django>=1.5.6,<1.6 + MyProject==1.5.6 + +using this `.bumpversion.cfg` will ensure only the line containing +`MyProject` will be changed: + +```ini +[bumpversion] +current_version = 1.5.6 + +[bumpversion:file:requirements.txt] +search = MyProject=={current_version} +replace = MyProject=={new_version} +``` + +Can be multiple lines, templated using [Python Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax). + +**NOTE**: (*Updated in v1.0.1*) It is important to point out that if a +custom search pattern is configured, then `bump-my-version` will only perform +a change if it finds an exact match and will not fallback to the default +pattern. This is to prevent accidentally changing strings that match the +default pattern when there is a typo in the custom search pattern. + +For example, if the string to be replaced includes literal quotes, +the search and replace patterns must include them too to match. Given the +file `version.sh`: + + MY_VERSION="1.2.3" + +Then the following search and replace patterns (including quotes) would be +required: + +```ini +[bumpversion:file:version.sh] +search = MY_VERSION="{current_version}" +replace = MY_VERSION="{new_version}" +``` + +--- + +## Using bumpversion to maintain a go.mod file within a Go project + +In a module-aware Go project, when you create a major version of your module beyond v1, your module name will need to include the major version number (e.g. `github.com/myorg/myproject/v2`). + +You can use bump-my-version to maintain the major version number within the `go.mod` file by using the `parse` and `serialize` options, as in this example: + +- Example `.bumpversion.toml` file: + +```toml +[tool.bumpversion] +current_version = 2.0.0 +commit = True + +[[tool.bumpversion.files]] +filename: go.mod +parse = (?P\d+) +serialize = {major} +search = module github.com/myorg/myproject/v{current_version} +replace = module github.com/myorg/myproject/v{new_version} +``` + +- Example `go.mod` file: + +```go +module github.com/myorg/myproject/v2 + +go 1.12 + +require ( + ... +) +``` + +Then run this command to create version 3.0.0 of your project: + +```console +bump-my-version --new-version 3.0.0 major +``` + +Your `go.mod` file now contains this module directive: + +```go +module github.com/myorg/myproject/v3 +``` + +## diff --git a/docsrc/usage.md b/docsrc/usage.md index cf27f744..465ac247 100644 --- a/docsrc/usage.md +++ b/docsrc/usage.md @@ -1,7 +1,50 @@ # Usage -To use bump_version in a project: +```{admonition} NOTE -```python -import bumpversion +Throughout this document, you can use `bumpversion` or `bump-my-version` interchangeably. +``` + +There are two modes of operation: On the command line for single-file operation +and using a configuration file (`pyproject.toml`) for more complex multi-file operations. + +```console +bump-my-version [OPTIONS] VERSION_PART [FILES]... +``` + +## `VERSION_PART` + +_**required**_ + +The part of the version to increase, e.g. `minor`. + +Valid values include those given in the `--serialize` / `--parse` option. + +Example bumping 0.5.1 to 0.6.0: + +```console +bump-my-version --current-version 0.5.1 minor src/VERSION +``` + + +## `FILES` + +_**[optional]**_
+**default**: `None` + +The additional file(s) to modify. + +This file is added to the list of files specified in the configuration file. If you want to rewrite only files +specified on the command line, use `--no-configured-files`. + +Example bumping version 1.1.9 to 2.0.0 in the `setup.py` file: + +```console +bump-my-version --current-version 1.1.9 major setup.py +``` + +Example bumping version 1.1.9 to 2.0.0 in _only_ the `setup.py` file: + +```console +bump-my-version --current-version 1.1.9 --no-configured-files major setup.py ``` diff --git a/docsrc/version-parts.md b/docsrc/version-parts.md new file mode 100644 index 00000000..12fa3f98 --- /dev/null +++ b/docsrc/version-parts.md @@ -0,0 +1,112 @@ +# Version parts + +A version string consists of one or more parts, e.g. the version `1.0.2` has three parts, separated by a dot (`.`) character. The names of these parts are defined in the named groups within the `parse` regular expression. The default configuration ( `(?P\d+)\.(?P\d+)\.(?P\d+)`) names them *major, minor,* and *patch.* + +By default all parts are considered numeric, that is their initial value is `0` and they are increased as integers. Also, the value `0` is considered to be +optional if it's not needed for serialization, i.e. the version `1.4.0` is +equal to `1.4` if `{major}.{minor}` is given as a `serialize` value. + +For advanced versioning schemes, non-numeric parts may be desirable (e.g. to +identify [alpha or beta versions](http://en.wikipedia.org/wiki/Software_release_life_cycle#Stages_of_development) +to indicate the stage of development, the flavor of the software package or +a release name). To do so, you can use a `[bumpversion:part:…]` section +containing the part's name (e.g. a part named `release_name` is configured in +a section called `[bumpversion:part:release_name]`. + +The following options are valid inside a part configuration: + + + + + +Example: + +```ini +[bumpversion:part:release_name] +values = +witty-warthog +ridiculous-rat +marvelous-mantis +``` + +--- + +Example: + +```ini +[bumpversion] +current_version = 1.alpha +parse = (?P\d+)(\.(?P.*))? +serialize = +{num}.{release} +{num} + +[bumpversion:part:release] +optional_value = gamma +values = +alpha +beta +gamma +``` + +Here, `bump-my-version release` would bump `1.alpha` to `1.beta`. Executing +`bump-my-version release` again would bump `1.beta` to `1`, because +`release` being `gamma` is configured optional. + +You should consider the version of `1` to technically be `1.gamma` +with the `.gamma` part not being serialized since it is optional. +The `{num}` entry in the `serialize` list allows the release part to be +hidden. If you only had `{num}.{release}`, an optional release will always +be serialized. + +Attempting to bump the release when it is the value of +`gamma` will cause a `ValueError` as it will think you are trying to +exceed the `values` list of the release part. + +--- + +Example: + +```ini +[bumpversion] +current_version = 1.alpha1 +parse = (?P\d+)(\.(?P.*)(?P\d+))? +serialize = +{num}.{release}{build} + +[bumpversion:part:release] +values = +alpha +beta +gamma + +[bumpversion:part:build] +first_value = 1 +``` + +Here, `bump-my-version release` would bump `1.alpha1` to `1.beta1`. + +Without the `first_value = 1` of the build part configured, +`bump-my-version release` would bump `1.alpha1` to `1.beta0`, starting +the build at `0`. + + + +--- + +Example: + +```ini +[bumpversion] +current_version: 2.1.6-5123 +parse = (?P\d+)\.(?P\d+)\.(?P\d+)\-(?P\d+) +serialize = {major}.{minor}.{patch}-{build} + +[bumpversion:file:VERSION.txt] + +[bumpversion:part:build] +independent = True +``` + +Here, `bump-my-version build` would bump `2.1.6-5123` to `2.1.6-5124`. Executing`bump-my-version major` +would bump `2.1.6-5124` to `3.0.0-5124` without resetting the build number.