From 8ac10871135a1c71c9244901b419f3ab95103d1a Mon Sep 17 00:00:00 2001 From: Corey Oordt Date: Sat, 24 Feb 2024 19:24:04 -0600 Subject: [PATCH] Fixed docs and cli help --- README.md | 227 ++++++++++----- bumpversion/cli.py | 3 +- docsrc/_static/css/field-list.css | 39 +-- docsrc/reference/configuration.md | 260 +++++++++++------- .../tutorials/semantic-versioning-example.md | 209 +------------- 5 files changed, 343 insertions(+), 395 deletions(-) diff --git a/README.md b/README.md index 650f953e..5bb5ca38 100644 --- a/README.md +++ b/README.md @@ -44,102 +44,193 @@ pip install --upgrade bump-my-version Please find the changelog here: [CHANGELOG.md](CHANGELOG.md) -## Usage for version incrementing - -There are two modes of operation: On the command line for single-file operation and using a configuration file (`pyproject.toml` or `.bumpversion.toml`) for more complex multi-file operations. - -> **WARNING:** -> -> The invocation of `bump-my-version` changed in version 0.6.0. It split functionality into sub-commands. It remains backward-compatible with previous versions. Previous usage is discouraged and may be removed in a 1.0 release. - - bump-my-version bump [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 bump --current-version 0.5.1 minor - -### `file` - -_**[optional]**_
-**default**: none - -Additional files to modify. +## Semantic versioning example + + +### Create a default configuration + +The default configuration uses a simplified version of [semantic versioning](https://semver.org/). + +```console title="Generating a default configuration" +$ bump-my-version sample-config --no-prompt --destination .bumpversion.toml +$ cat .bumpversion.toml +[tool.bumpversion] +current_version = "0.1.0" +parse = "(?P\\d+)\\.(?P\\d+)\\.(?P\\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 = "" +``` -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`. +### Visualize the versioning path -Example bumping 1.1.9 to 2.0.0: +You can see the potential versioning paths with the `show-bump` subcommand. - bump-my-version bump --current-version 1.1.9 major setup.py +```console title="Showing the potential versioning path" +$ 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 +``` -## Configuration file +The default configuration only allows bumping the major, minor, or patch version. What if you wanted to support pre-release versions? -`bump-my-version` looks in four places for the configuration file to parse (in order of precedence): +### Add support for pre-release versions -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` +Alter the `parse` configuration to support pre-release versions. This `parse` option uses an extended (or verbose) regular expression to extract the version parts from the current version. -`.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. +```toml title="New parse configuration" +parse = """(?x) + (?P0|[1-9]\\d*)\\. + (?P0|[1-9]\\d*)\\. + (?P0|[1-9]\\d*) + (?: + - # dash seperator for pre-release section + (?P[a-zA-Z-]+) # pre-release label + (?P0|[1-9]\\d*) # pre-release version number + )? # pre-release section is optional +""" +``` -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. +Alter the `serialize` configuration to support pre-release versions. -## Command-line Options +```toml title="New serialize configuration" +serialize = [ + "{major}.{minor}.{patch}-{pre_l}{pre_n}", + "{major}.{minor}.{patch}", +] +``` -Most of the configuration values above can also be given as an option on the command line. -Additionally, the following options are available: +Add a new configuration section for the `pre_l` part. -`--dry-run, -n` -Don't touch any files, just pretend. Best used with `--verbose`. +```toml title="New pre_l configuration" -`--no-configured-files` -Will not update/check files specified in the configuration file. +[tool.bumpversion.parts.pre_l] +values = ["dev", "rc", "final"] +optional_value = "final" +``` -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` +### Visualize the new versioning path -`--verbose, -v` -Print useful information to stderr. If specified more than once, it will output more information. +Now when you run `bump-my-version show-bump`, you can see the new pre-release versioning path. -`--list` -_DEPRECATED. Use `bump-my-version show` instead._ List machine-readable information to stdout for consumption by other programs. +```console title="Showing the new 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 +``` -Example output: +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. - current_version=0.0.18 - new_version=0.0.19 +If we run `bump-my-version show-bump 1.0.0-dev0`, we can see the new versioning path for a `dev` starting version. -`-h, --help` -Print help and exit +```console title="Showing the new versioning path for a dev 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 +``` -## Using Bump My Version in a script +Finally, we can see the new versioning path for a `rc` starting version. -If you need to use the version generated by Bump My Version in a script, you can make use of the `show` subcommand. +```console title="Showing the new versioning path for an rc 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 +``` -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 need to know the new version before applying the change. +The full development and release path is: -The standard way to get it in a bash script 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` - bump-my-version show new_version --increment +1. You must decide on the next version before you start developing. +2. Development versions increase using `bump-my-version bump pre_n`. +3. Switch from development to release candidate using `bump-my-version bump pre_l`. +4. Release candidates increase using `bump-my-version bump pre_n`. +5. Switch from the release candidate to the final release using `bump-my-version bump pre_l`. -where `part` is the part of the version number you are updating. +### Automate the pre-release numbering -For example, if you are updating the minor number and looking for the new version number, this becomes: +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. -```console -$ bump-my-version show new_version --increment minor -1.1.0 +```toml title="Serialize configuration with pre_n automation" +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. + +```console title="Showing the new versioning path with pre_n automation" + +$ 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` +- `bump pre_l` → `1.0.1-rc0` +- each commit will increase → `1.0.1-rc1` +- `bump pre_l` → `1.0.1` + +1. You must decide on the next version before you start developing. +2. Development versions increase automatically with each commit. +3. Switch from development to release candidate using `bump-my-version bump pre_l`. +4. Release candidate versions increase automatically with each commit. +5. 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 diff --git a/bumpversion/cli.py b/bumpversion/cli.py index 43a096aa..37064f58 100644 --- a/bumpversion/cli.py +++ b/bumpversion/cli.py @@ -65,7 +65,8 @@ def cli(ctx: Context) -> None: { "name": "Committing and tagging", "options": [ - "--allow-dirty" "--commit", + "--allow-dirty", + "--commit", "--commit-args", "--message", "--tag", diff --git a/docsrc/_static/css/field-list.css b/docsrc/_static/css/field-list.css index aff82aa0..ace471b2 100644 --- a/docsrc/_static/css/field-list.css +++ b/docsrc/_static/css/field-list.css @@ -2,18 +2,13 @@ dl.field-list .doc-param-default, dl.doc-field-list .doc-param-default { float: none; } -dd.doc-field-def > p:last-child { - padding-bottom: 0; - margin-bottom: 0; -} - -dl.field-list, dl.doc-field-list { +.field-list > dl, dl.field-list, dl.doc-field-list { display: flex; flex-flow: row wrap; padding-left: 10px; } -dl.field-list > dt, dl.doc-field-list > dt { +.field-list > dl > dt, dl.field-list > dt, dl.doc-field-list > dt { flex-basis: 20%; font-weight: bold; word-break: break-word; @@ -21,11 +16,11 @@ dl.field-list > dt, dl.doc-field-list > dt { border-bottom: 1px solid #e5e5e5; } -dl.field-list > dt:after { +.field-list > dl > dt:after, dl.field-list > dt:after { content: ":"; } -dl.field-list > dd.doc-field-def, dl.doc-field-list > dd.doc-field-def { +[dir=ltr] .field-list > dl > dd, dl.field-list > dd.doc-field-def, dl.doc-field-list > dd.doc-field-def { flex-basis: 70%; flex-grow: 1; margin: 0; @@ -33,29 +28,7 @@ dl.field-list > dd.doc-field-def, dl.doc-field-list > dd.doc-field-def { border-bottom: 1px solid #e5e5e5; } -dl { - margin-bottom: 15px; -} - -dd > :first-child { - margin-top: 0; -} - -dd ul, dd table { - margin-bottom: 10px; -} - -dd { - margin-top: 3px; - margin-bottom: 10px; - margin-left: 30px; -} - -dl > dd:last-child, -dl > dd:last-child > :last-child { +dd.doc-field-def > p:last-child { + padding-bottom: 0; margin-bottom: 0; } - -dt:target, span.highlighted { - background-color: #fbe54e; -} diff --git a/docsrc/reference/configuration.md b/docsrc/reference/configuration.md index 6b424e25..7e93ffa4 100644 --- a/docsrc/reference/configuration.md +++ b/docsrc/reference/configuration.md @@ -27,7 +27,7 @@ By using a configuration file, you no longer need to specify those options on th The general configuration is grouped in a `[tool.bumpversion]` or `[bumpversion]` section, depending on if it is a TOML or INI file respectfully. -### `allow_dirty` +### allow_dirty ::: field-list required @@ -48,7 +48,7 @@ The general configuration is grouped in a `[tool.bumpversion]` or `[bumpversion Bump-my-version's default behavior is to abort if the working directory has uncommitted changes. This is to protect you from releasing unversioned files and/or overwriting unsaved changes. -### `commit` +### commit ::: field-list required @@ -70,22 +70,22 @@ 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`](configuration.md#commit-args) to disable your pre-commit hooks. For Git use `--no-verify` and use `--config hooks.pre-commit=` for Mercurial. -### `commit_args` +### commit_args ::: field-list required : No - + default : `""` - + type : string - + command line option : `--commit-args` - + environment var : `BUMPVERSION_COMMIT_ARGS` @@ -93,28 +93,49 @@ Extra arguments to pass to commit command. This is only used when the [`commit`] 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. -### `current_version` +### current_version ::: field-list 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. -### `ignore_missing_version` +### ignore_missing_files + +::: field-list + + required + : No + + default + : `False` + + type + : boolean + + command line option + : `--ignore-missing-files` + + environment var + : `BUMPVERSION_IGNORE_MISSING_FILES` + +If `True`, don't fail if the configured file is missing. + +### ignore_missing_version ::: field-list required @@ -134,7 +155,7 @@ The current version of the software package before bumping. A value for this is If `True`, don't fail if the version string to be replaced is not found in the file. -### `message` +### message ::: field-list @@ -157,7 +178,8 @@ The commit message template to use when creating a commit. This is only used whe This string is templated using the [Python Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax). The [formatting context reference](formatting-context.md) describes the available variables. -### `parse` +### parse + ::: field-list required : No @@ -178,7 +200,29 @@ This is the default regular expression (using [Python regular expression syntax] The regular expression must be able to parse all strings produced by the configured [`serialize`](configuration.md#serialize) value. Named matching groups ("`(?P...)`") indicate the version part the matched value belongs to. -### `replace` +### regex + +::: field-list + + required + : No + + default + : `False` + + type + : boolean + + command line option + : `--regex | --no-regex` + + environment var + : `BUMPVERSION_REGEX` + +Treat the `search` string as a regular expression. + +### replace + ::: field-list required : No @@ -197,7 +241,7 @@ The regular expression must be able to parse all strings produced by the configu This is the template to create the string that will replace the current version number in the file. -### `search` +### search ::: field-list required @@ -219,7 +263,7 @@ This is the template string how to search for the string to be replaced in the f 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. -### `serialize` +### serialize ::: field-list required @@ -255,7 +299,7 @@ Since `0` is optional by default, Version `1.8.9` will serialize to `1.8.9`, `1 Each string is templated using the [Python Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax). The [formatting context reference](formatting-context.md) describes the available variables. -### `sign_tags` +### sign_tags ::: field-list @@ -269,29 +313,29 @@ Each string is templated using the [Python Format String Syntax](https://docs.py : boolean command line option - : `(--sign-tags | --no-sign-tags)` + : `--sign-tags | --no-sign-tags` environment var : `BUMPVERSION_SIGN_TAGS` If `True`, sign the created tag, when [`tag`](configuration.md#tag) is `True`. -### `tag` +### tag ::: field-list required : No - + default : `False` (Don't create a tag) - + type : boolean - + command line option - : `(--tag | --no-tag)` - + : `--tag | --no-tag` + environment var : `BUMPVERSION_TAG` @@ -299,53 +343,53 @@ If `True`, create a tag after committing the changes. The tag is named using the If you are using `git`, don't forget to `git-push` with the `--tags` flag when you are done. -### `tag_name` +### tag_message ::: field-list - required : No - + default - : `v{new_version}` - + : `Bump version: {current_version} → {new_version}` + type : string - + command line option - : `--tag-name` - + : `--tag-message` + environment var - : `BUMPVERSION_TAG_NAME` + : `BUMPVERSION_TAG_MESSAGE` -The name template used to render the tag, when [`tag`](configuration.md#tag) is `True`. +The tag message template to use when creating a tag, when [`tag`](configuration.md#tag) is `True` This string is templated using the [Python Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax). The [formatting context reference](formatting-context.md) describes the available variables. -### `tag_message` +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` value. + +### tag_name ::: field-list + required : No default - : `Bump version: {current_version} → {new_version}` + : `v{new_version}` type : string command line option - : `--tag-message` + : `--tag-name` environment var - : `BUMPVERSION_TAG_MESSAGE` + : `BUMPVERSION_TAG_NAME` -The tag message template to use when creating a tag, when [`tag`](configuration.md#tag) is `True` +The name template used to render the tag, when [`tag`](configuration.md#tag) is `True`. This string is templated using the [Python Format String Syntax](https://docs.python.org/3/library/string.html#format-string-syntax). The [formatting context reference](formatting-context.md) describes the available variables. -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` value. - ### Examples === "TOML" @@ -391,11 +435,11 @@ Bump My Version creates an *annotated* tag in Git by default. To disable this an ## 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. +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. +You only need to configure version parts if they deviate from the default, and then you only need to specify the overridden options. -### `values` +### values ::: field-list required @@ -409,7 +453,7 @@ You only need to configure version parts if they deviate from the default, and t An explicit list of all values to iterate through when bumping this part. An empty array is treated as indicating `numeric` values. -### `optional_value` +### optional_value ::: field-list required @@ -428,7 +472,7 @@ When the version part matches this value it is considered optional when serializ Numeric values are still treated as strings internally, so when specifying an optional value, you must use a string. -### `first_value` +### first_value ::: field-list required @@ -436,7 +480,7 @@ When the version part matches this value it is considered optional when serializ default : The first entry in `values`, `0` when using numeric values - + type : string @@ -447,7 +491,7 @@ When the part is reset, the value will be set to the value specified here. Numeric values are still treated as strings internally, so when specifying a first value, you must use a string. -### `independent` +### independent ::: field-list required @@ -492,7 +536,7 @@ independent of the other parts. It is useful when you have a build number in you This section configures which files Bump My Version should update by replacing their current version with the newly bumped version. -### `filename` +### filename ::: field-list required @@ -511,7 +555,7 @@ The name of the file to modify. ‡ 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` +### glob ::: field-list required @@ -530,7 +574,7 @@ The glob pattern specifying the files to modify. ‡ 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` +### parse ::: field-list @@ -545,7 +589,7 @@ The glob pattern specifying the files to modify. This is an override to the default pattern to parse the version number from this file. -### `serialize` +### serialize ::: field-list @@ -560,7 +604,7 @@ This is an override to the default pattern to parse the version number from this This is an override to the default templates to serialize the new version number in this file. -### `search` +### search ::: field-list @@ -575,7 +619,22 @@ This is an override to the default templates to serialize the new version number This is an override to the default template string how to search for the string to be replaced in the file. -### `replace` +### regex + +::: field-list + + required + : No + + default + : the valued configured in the global `regex` field + + type + : boolean + +If `True`, treat the `search` parameter as a regular expression. + +### replace ::: field-list @@ -590,7 +649,7 @@ This is an override to the default template string how to search for the string This is an override to the template to create the string that will replace the current version number in the file. -### `ignore_missing_version` +### ignore_missing_version ::: field-list @@ -605,46 +664,63 @@ This is an override to the template to create the string that will replace the c If `True`, don't fail if the version string to be replaced is not found in the file. -### INI-style configuration files - -INI-style configuration is in the section: `[bumpversion:file:]` or `[bumpversion:glob:]`. +### ignore_missing_file -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 +::: field-list -[bumpversion:file(previous version):CHANGELOG.md] -search = {current_version}...HEAD -replace = {current_version}...{new_version} -``` + required + : No + + default + : The value configured in the global `ignore_missing_file` field + + type + : boolean -### TOML configuration files +if `True`, don't fail if the configured file is missing. -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. +### Examples -For example, to change `coolapp/__init__.py` with the defaults, and alter `CHANGELOG.md` in twice: +=== "TOML" -```toml -[[tool.bumpversion.files]] -filename = "coolapp/__init__.py" + 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}" + ``` -[[tool.bumpversion.files]] -filename = "CHANGELOG.md" -search = "Unreleased" +=== "CFG" -[[tool.bumpversion.files]] -filename = "CHANGELOG.md" -search = "{current_version}...HEAD" -replace = "{current_version}...{new_version}" -``` + 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} + ``` diff --git a/docsrc/tutorials/semantic-versioning-example.md b/docsrc/tutorials/semantic-versioning-example.md index d69d91fc..c751c255 100644 --- a/docsrc/tutorials/semantic-versioning-example.md +++ b/docsrc/tutorials/semantic-versioning-example.md @@ -1,201 +1,8 @@ -# Semantic versioning example - -## Create a default configuration - -The default configuration uses a simplified version of [semantic versioning](https://semver.org/). - -```{code-block} console -:caption: Generating a default configuration - -$ bump-my-version sample-config --no-prompt --destination .bumpversion.toml -$ cat .bumpversion.toml -[tool.bumpversion] -current_version = "0.1.0" -parse = "(?P\\d+)\\.(?P\\d+)\\.(?P\\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 = "" -``` - -### Visualizing the versioning path - -You can see the potential versioning paths with the `show-bump` subcommand. - -```{code-block} console -:caption: Showing the potential versioning path - -$ 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? - -## Supporting 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 parts from the current version. - -```{code-block} toml -:caption: New parse configuration - -parse = """(?x) - (?P0|[1-9]\\d*)\\. - (?P0|[1-9]\\d*)\\. - (?P0|[1-9]\\d*) - (?: - - # dash seperator for pre-release section - (?P[a-zA-Z-]+) # pre-release label - (?P0|[1-9]\\d*) # pre-release version number - )? # pre-release section is optional -""" -``` - -Alter the `serialize` configuration to support pre-release versions. - -```{code-block} toml -:caption: New serialize configuration - -serialize = [ - "{major}.{minor}.{patch}-{pre_l}{pre_n}", - "{major}.{minor}.{patch}", -] -``` - -Add a new configuration section for the `pre_l` part. - -```{code-block} toml -:caption: New pre_l configuration - -[tool.bumpversion.parts.pre_l] -values = ["dev", "rc", "final"] -optional_value = "final" -``` - -### Visualizing the new versioning path - -Now when you run `bump-my-version show-bump`, you can see the new pre-release versioning path. - -```{code-block} console -:caption: Showing the new 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. - -```{code-block} console -:caption: Showing the new versioning path for a dev 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. - -```{code-block} console -:caption: Showing the new versioning path for an rc 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` - -1. You must decide on the next version before you start developing. -2. Development versions increase using `bump-my-version bump pre_n`. -3. Switch from development to release candidate using `bump-my-version bump pre_l`. -4. Release candidates increase using `bump-my-version bump pre_n`. -5. Switch from the release candidate to the final release using `bump-my-version bump pre_l`. - -## Automating 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. - -```{code-block} toml -:caption: Serialize configuration with pre_n automation - -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. - -### Visualizing the pre_n versioning path - -Now when you run `bump-my-version show-bump`, you can see the new pre-release versioning path. - -```{code-block} console -:caption: Showing the new versioning path with pre_n automation - -$ 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` -- `bump pre_l` → `1.0.1-rc0` -- each commit will increase → `1.0.1-rc1` -- `bump pre_l` → `1.0.1` - -1. You must decide on the next version before you start developing. -2. Development versions increase automatically with each commit. -3. Switch from development to release candidate using `bump-my-version bump pre_l`. -4. Release candidate versions increase automatically with each commit. -5. Switch from the release candidate to the final release using `bump-my-version bump pre_l`. +{% + include-markdown + "../../README.md" + start="" + end="" + rewrite-relative-urls=false + heading-offset=0 +%}