diff --git a/Makefile b/Makefile deleted file mode 100644 index 90f1977b..00000000 --- a/Makefile +++ /dev/null @@ -1,22 +0,0 @@ -.PHONY: help docs pubdocs update-requires -.DEFAULT_GOAL := help - -help: - @grep '^[a-zA-Z]' $(MAKEFILE_LIST) | sort | awk -F ':.*?## ' 'NF==2 {printf "\033[36m %-25s\033[0m %s\n", $$1, $$2}' - - -docs: ## generate Sphinx HTML documentation, including API docs - mkdir -p docs - ls -A1 docs | xargs -I {} rm -rf docs/{} - $(MAKE) -C docsrc clean html - cp -a docsrc/_build/html/. docs - -pubdocs: docs ## Publish the documentation to GitHub - ghp-import -op docs - - -update-requires: ## Update the requirements.txt file - pip-compile --output-file=requirements/prod.txt pyproject.toml - pip-compile --extra=test --output-file=requirements/test.txt pyproject.toml - pip-compile --extra=docs --output-file=requirements/docs.txt pyproject.toml - pip-compile --extra=dev --extra=docs --extra=test --output-file=requirements/dev.txt pyproject.toml diff --git a/README.md b/README.md index 43239e49..4cd21fe8 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ The default configuration only allows bumping the major, minor, or patch version ### 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 parts from the current version. +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. ```toml title="New parse configuration" parse = """(?x) diff --git a/bumpversion/bump.py b/bumpversion/bump.py index 935f64de..2d135e08 100644 --- a/bumpversion/bump.py +++ b/bumpversion/bump.py @@ -64,7 +64,7 @@ def do_bump( Bump the version_part to the next value or set the version to new_version. Args: - version_part: The version part to bump + version_part: The name of the version component to bump new_version: The explicit version to set config: The configuration to use config_file: The configuration file to update diff --git a/bumpversion/cli.py b/bumpversion/cli.py index c9a68321..9fafdee5 100644 --- a/bumpversion/cli.py +++ b/bumpversion/cli.py @@ -287,7 +287,7 @@ def bump( config = get_configuration(found_config_file, **overrides) if args: if args[0] not in config.parts.keys(): - raise click.BadArgumentUsage(f"Unknown version part: {args[0]}") + raise click.BadArgumentUsage(f"Unknown version component: {args[0]}") version_part = args[0] files = args[1:] else: @@ -335,7 +335,7 @@ def bump( required=False, envvar="BUMPVERSION_INCREMENT", type=str, - help="Increment the version part and add `new_version` to the configuration.", + help="Increment the version component and add `new_version` to the configuration.", ) def show(args: List[str], config_file: Optional[str], format_: str, increment: Optional[str]) -> None: """ diff --git a/bumpversion/config/__init__.py b/bumpversion/config/__init__.py index 27e8f3e3..1195b757 100644 --- a/bumpversion/config/__init__.py +++ b/bumpversion/config/__init__.py @@ -70,7 +70,7 @@ def get_configuration(config_file: Union[str, Path, None] = None, **overrides: A parsed_config = read_config_file(config_file) if config_file else {} config_dict = set_config_defaults(parsed_config, **overrides) - # Set any missing version parts + # Set any missing version components config_dict["parts"] = get_all_part_configs(config_dict) # Set any missing file configuration diff --git a/bumpversion/config/utils.py b/bumpversion/config/utils.py index 365992fb..1f2eae6a 100644 --- a/bumpversion/config/utils.py +++ b/bumpversion/config/utils.py @@ -13,7 +13,7 @@ def get_all_file_configs(config_dict: dict) -> List[FileChange]: - """Make sure all version parts are included.""" + """Make sure all version components are included.""" defaults = { "parse": config_dict["parse"], "serialize": config_dict["serialize"], @@ -31,7 +31,7 @@ def get_all_file_configs(config_dict: dict) -> List[FileChange]: def get_all_part_configs(config_dict: dict) -> Dict[str, VersionComponentSpec]: - """Make sure all version parts are included.""" + """Make sure all version components are included.""" try: parsing_groups = list(re.compile(config_dict["parse"]).groupindex.keys()) except re.error as e: diff --git a/bumpversion/files.py b/bumpversion/files.py index ce29f98f..98708da0 100644 --- a/bumpversion/files.py +++ b/bumpversion/files.py @@ -151,7 +151,7 @@ def _contains_change_pattern( return True # The `search` pattern did not match, but the original supplied - # version number (representing the same version part values) might + # version number (representing the same version component values) might # match instead. This is probably the case if environment variables are used. # check whether `search` isn't customized diff --git a/docs/assets/explanations.jpg b/docs/assets/explanations.jpg new file mode 100644 index 00000000..b592487f Binary files /dev/null and b/docs/assets/explanations.jpg differ diff --git a/docs/assets/how-to.jpg b/docs/assets/how-to.jpg new file mode 100644 index 00000000..12139d7d Binary files /dev/null and b/docs/assets/how-to.jpg differ diff --git a/docs/assets/reference.jpg b/docs/assets/reference.jpg new file mode 100644 index 00000000..0efd8e45 Binary files /dev/null and b/docs/assets/reference.jpg differ diff --git a/docs/assets/tutorial.jpg b/docs/assets/tutorial.jpg new file mode 100644 index 00000000..6f3ecdc7 Binary files /dev/null and b/docs/assets/tutorial.jpg differ diff --git a/docs/explanation/index.md b/docs/explanation/index.md index b1303b40..9a23d53e 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -1 +1 @@ -# Explanation +- *.md diff --git a/docs/reference/subcommands/show.md b/docs/explanation/show-subcommand.md similarity index 100% rename from docs/reference/subcommands/show.md rename to docs/explanation/show-subcommand.md diff --git a/docs/reference/version-parts.md b/docs/explanation/version-parts.md similarity index 99% rename from docs/reference/version-parts.md rename to docs/explanation/version-parts.md index 06900061..61fe606a 100644 --- a/docs/reference/version-parts.md +++ b/docs/explanation/version-parts.md @@ -1,4 +1,4 @@ -# Version parts +# Version components - The version string is the rendering of some or all version parts. - While the version string may be rendered differently in various places, the value for all parts is maintained in Bump My Version's configuration. diff --git a/docs/gen_doc_stubs.py b/docs/gen_doc_stubs.py index c2a3bf2f..605b78b4 100755 --- a/docs/gen_doc_stubs.py +++ b/docs/gen_doc_stubs.py @@ -47,5 +47,5 @@ mkdocs_gen_files.set_edit_path(full_doc_path, path) -with mkdocs_gen_files.open("reference/api/SUMMARY.md", "w") as nav_file: +with mkdocs_gen_files.open("reference/api/nav.md", "w") as nav_file: nav_file.writelines(nav.build_literate_nav()) diff --git a/docs/howtos/avoid-incorrect-replacements.md b/docs/howtos/avoid-incorrect-replacements.md index c7997fbb..b077c15f 100644 --- a/docs/howtos/avoid-incorrect-replacements.md +++ b/docs/howtos/avoid-incorrect-replacements.md @@ -1,4 +1,4 @@ -# Avoiding incorrect replacements +# Avoid incorrect replacements In files that have multiple version strings, Bump My Version may find the wrong string and replace it. Given this `requirements.txt` for `MyProject`: diff --git a/docs/howtos/calver.md b/docs/howtos/calver.md index 3a63a57d..406dfd83 100644 --- a/docs/howtos/calver.md +++ b/docs/howtos/calver.md @@ -7,7 +7,6 @@ For this example, we will use the following format: `YYYY.MM.DD.patch`. It will - `2022.2.1` for the first patch of February 1, 2022 - `2022.2.1.1` for the second patch of February 1, 2022 - ## Initial configuration ```toml title=".bumpversion.toml" @@ -31,7 +30,12 @@ You can look up the regular expressions for the CalVer format in the [CalVer ref ## Expected behavior -You can find out more about the logic behind the CalVer incrementing in the [CalVer reference](../reference/calver_reference.md#calver-incrementing-logic). +- CalVer version components are marked as `always_increment` by default. +- When bumping a version, you specify which component to increment. It is called the target component. +- When bumping a version, the components marked as `always_increment` are incremented first. +- If an `always_increment` component's value changed, its dependent components are marked for reset to their default values. +- If the target component is in the set of components marked for reset, the target component is reset to its default value. +- If the target component is not in the set of components marked for reset, the target component is incremented and its dependent components are reset to their default values. ### Bumping the release resets the patch part diff --git a/docs/howtos/index.md b/docs/howtos/index.md deleted file mode 100644 index 869c35ee..00000000 --- a/docs/howtos/index.md +++ /dev/null @@ -1,6 +0,0 @@ -# How-To Guides - - -- [Avoid incorrect replacements](avoid-incorrect-replacements.md) -- [Custom version formats by file](custom-version-formats-by-file.md) -- [Multiple replacements](multiple-replacements.md) diff --git a/docs/howtos/nav.md b/docs/howtos/nav.md new file mode 100644 index 00000000..9a23d53e --- /dev/null +++ b/docs/howtos/nav.md @@ -0,0 +1 @@ +- *.md diff --git a/docs/index.md b/docs/index.md index 5626cde8..18a106e1 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,10 +5,81 @@ title: Bump My Version # Bump My Version -{% - include-markdown - "../README.md" - start="" - end="" - rewrite-relative-urls=false -%} +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 + - Support 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: + +```console +pip install --upgrade bump-my-version +``` + diff --git a/docs/reference/calver_reference.md b/docs/reference/calver_reference.md index 7a0c8ed3..9580810c 100644 --- a/docs/reference/calver_reference.md +++ b/docs/reference/calver_reference.md @@ -2,7 +2,9 @@ ## Calendar versioning codes -The following table lists the available format codes for calendar versioning (CalVer) schemes. The codes can be used to define the version format in the `calver_format` configuration options. Formatting codes, surrounded by `{ }` can be combined to create a custom version format. For example, the format `YYYY.MM.DD` can be defined as `"{YYYY}.{MM}.{DD}"`. +The following table lists the available format codes for calendar versioning (CalVer) schemes. The codes can be used to +define the version format in the `calver_format` configuration options. Formatting codes, surrounded by `{ }` can be +combined to create a custom version format. For example, the format `YYYY.MM.DD` can be defined as `"{YYYY}.{MM}.{DD}"`. | Code | Example(s) | Comment | |--------|---------------------|-----------------------------------------------| @@ -32,7 +34,6 @@ The following table lists the available format codes for calendar versioning (Ca calver_format = "{YYYY}.{MM}.{DD}" ``` - ## Parsing CalVer versions Using the following chart, we can set up the version parsing: @@ -68,7 +69,9 @@ Using the following chart, we can set up the version parsing: `(?:jan|fév|mar|avr|mai|jui|jui|aoû|sep|oct|nov|déc)` for French -You can use these regular expressions to parse CalVer versions in your project. For example, the following `parse` configuration can be used to parse a version string in the format `YYYY.MM.DD` as the `release` part of the version string: +You can use these regular expressions to parse CalVer versions in your project. For example, the following `parse` +configuration can be used to parse a version string in the format `YYYY.MM.DD` as the `release` part of the version +string: ```toml [tool.bumpversion] @@ -80,12 +83,3 @@ parse = """(?x) # Verbose mode ) """ ``` - -## CalVer incrementing logic - -- CalVer version components are marked as `always_increment` by default. -- When bumping a version, you specify which component to increment. It is called the target component. -- When bumping a version, the components marked as `always_increment` are incremented first. -- If an `always_increment` component's value changed, its dependent components are marked for reset to their default values. -- If the target component is in the set of components marked for reset, the target component is reset to its default value. -- If the target component is not in the set of components marked for reset, the target component is incremented and its dependent components are reset to their default values. diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md deleted file mode 100644 index dac2c5ed..00000000 --- a/docs/reference/configuration.md +++ /dev/null @@ -1,805 +0,0 @@ -# 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. - -### allow_dirty - -::: field-list - required - : No - - default - : `False` - - 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 has uncommitted changes. This protects you from releasing unversioned files and overwriting unsaved changes. - -### commit - -::: field-list - 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, add an option to [`commit_args`](configuration.md#commit_args) to turn off your pre-commit hooks. For Git, use `--no-verify` and use `--config hooks.pre-commit=` for Mercurial. - -### commit_args - -::: field-list - - 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`](configuration.md#commit) option is set to `True`. - -If you have pre-commit hooks, add an option to turn off your pre-commit hooks. For Git, use `--no-verify` and use `--config hooks.pre-commit=` for Mercurial. - -### 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_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 - : No - - default - : `False` - - type - : boolean - - command line option - : `--ignore-missing-version` - - environment var - : `BUMPVERSION_IGNORE_MISSING_VERSION` - -If `True`, don't fail if the version string to be replaced is not found in the file. - -### message - -::: field-list - - 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`](configuration.md#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). The [formatting context reference](formatting-context.md) describes the available variables. - -### parse - -::: field-list - 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 ([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`](configuration.md#serialize) value. Named matching groups ("`(?P...)`") indicate the version part the matched value belongs to. - -### 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 - - 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. - -### search - -::: field-list - required - : No - - default - : `{current_version}` - - type - : string - - command line option - : `--search` - - environment var - : `BUMPVERSION_SEARCH` - -This is the template string for searching. It is rendered using the [formatting context](formatting-context.md) for searching 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). The [formatting context reference](formatting-context.md) describes the available variables. - -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 bump only one of the occurrences. - -### serialize - -::: field-list - 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). The [formatting context reference](formatting-context.md) describes the available variables. - -### sign_tags - -::: field-list - - 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`](configuration.md#tag) is `True`. - -### tag - -::: field-list - - 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`](configuration.md#tag_name) option. - -If you are using `git`, don't forget to `git-push` with the `--tags` flag when you are done. - -### tag_message - -::: field-list - 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`](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 turn this off and create a *lightweight* tag, you must explicitly set an empty `tag_message` value. - -### tag_name - -::: field-list - - required - : No - - default - : `v{new_version}` - - type - : string - - command line option - : `--tag-name` - - environment var - : `BUMPVERSION_TAG_NAME` - -The 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. - -### Examples - -=== "TOML" - - ```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}" - ``` - -=== "CFG" - - ```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} - ``` - -## 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 overridden options. - -### values - -::: field-list - required - : No - - default - : numeric (i.e. `0`, `1`, `2`, …) - - type - : array of strings - -An explicit list of all values to iterate through when bumping this part. An empty array is treated as indicating `numeric` values. - -### optional_value - -::: field-list - 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 - -::: field-list - 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 - -::: field-list - 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. - -### always_increment - -::: field-list - required - : No - - default - : `False` (`True` if `calver_format` is set) - - type - : boolean - -When this value is set to `True`, the part is always incremented when the version is bumped, regardless of the target part. - - -### calver_format - -::: field-list - required - : No - - default - : empty - - type - : string - -The `calver_format` is a string that specifies the format of the version part. It is used to determine the next value when bumping the version. The format is a string that uses the placeholders defined in the [CalVer reference](calver_reference.md#calver_format). - -### Examples - -=== "TOML" - - ```toml - [tool.bumpversion.parts.release] - values = [ - "alpha", - "beta", - "gamma" - ] - optional_value = "gamma" - ``` - -=== "CFG" - - ```ini - [bumpversion:part:release] - optional_value = gamma - values = - alpha - beta - gamma - ``` - - -## File-specific configuration - -This section configures which files Bump My Version should update by replacing their current version with the newly bumped version. - -### filename - -::: field-list - 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 - -::: field-list - 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. - -### glob_exclude - -::: field-list - required - : No - - default - : empty - - type - : list of string - -A list of glob patterns to exclude from the files found via the `glob` parameter. Does nothing if `filename` is specified. - - -### parse - -::: field-list - - 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 - -::: field-list - - 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 - -::: field-list - - 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. - -### regex - -::: field-list - - required - : No - - default - : the value configured in the global `regex` field - - type - : boolean - -If `True`, treat the `search` parameter as a regular expression. - -### replace - -::: field-list - - 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. - -### ignore_missing_version - -::: field-list - - required - : No - - default - : The value configured in the global `ignore_missing_version` field - - type - : boolean - -If `True`, don't fail if the version string to be replaced is not found in the file. - -### ignore_missing_file - -::: field-list - - required - : No - - default - : The value configured in the global `ignore_missing_file` field - - type - : boolean - -if `True`, don't fail if the configured file is missing. - -### include_bumps - -::: field-list - - required - : No - - default - : all version components - - type - : list of strings - -The `include_bumps` file configuration allows you to control when bump-my-version includes this file for changes. Its alternative is the `exclude_bumps` configuration. When a `bump ` command is issued, this file is changed only if the version component is in this list and not in [`exclude_bumps`](#exclude_bumps). The [parse](#parse) configuration defines version components. - -The default value, or an empty list, includes all version components. - -### exclude_bumps - -::: field-list - - required - : No - - default - : `[]` - - type - : list of strings - -The `exclude_bumps` file configuration allows you to control when bump-my-version excludes this file for changes. Its alternative is the `include_bumps` configuration. When a `bump ` command is issued, this file is only changed if the version component is *not in this list.* The [parse](#parse) configuration defines version components. - -The default value does not exclude anything. - -### Examples - -=== "TOML" - - TOML allows us to specify the files using an [array of tables.](https://toml.io/en/v1.0.0#array-of-tables) TOML configuration adds two 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` 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}" - ``` - -=== "CFG" - - 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` 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/docs/reference/configuration/file.md b/docs/reference/configuration/file.md new file mode 100644 index 00000000..b678e262 --- /dev/null +++ b/docs/reference/configuration/file.md @@ -0,0 +1,249 @@ +--- +title: File-specific Configuration +description: Configuration for changing files +icon: +date: 2024-08-11 +comments: true +--- +# File-specific configuration + +This section configures which files Bump My Version should update by replacing their current version with the newly bumped version. + +## filename + +::: field-list + 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 + +::: field-list + 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. + +## glob_exclude + +::: field-list + required + : No + + default + : empty + + type + : list of string + +A list of glob patterns to exclude from the files found via the `glob` parameter. Does nothing if `filename` is specified. + + +## parse + +::: field-list + + 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 + +::: field-list + + 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 + +::: field-list + + 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. + +## regex + +::: field-list + + required + : No + + default + : the value configured in the global `regex` field + + type + : boolean + +If `True`, treat the `search` parameter as a regular expression. + +## replace + +::: field-list + + 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. + +## ignore_missing_version + +::: field-list + + required + : No + + default + : The value configured in the global `ignore_missing_version` field + + type + : boolean + +If `True`, don't fail if the version string to be replaced is not found in the file. + +## ignore_missing_file + +::: field-list + + required + : No + + default + : The value configured in the global `ignore_missing_file` field + + type + : boolean + +if `True`, don't fail if the configured file is missing. + +## include_bumps + +::: field-list + + required + : No + + default + : all version components + + type + : list of strings + +The `include_bumps` file configuration allows you to control when bump-my-version includes this file for changes. Its alternative is the `exclude_bumps` configuration. When a `bump ` command is issued, this file is changed only if the version component is in this list and not in [`exclude_bumps`](#exclude_bumps). The [parse](#parse) configuration defines version components. + +The default value, or an empty list, includes all version components. + +## exclude_bumps + +::: field-list + + required + : No + + default + : `[]` + + type + : list of strings + +The `exclude_bumps` file configuration allows you to control when bump-my-version excludes this file for changes. Its alternative is the `include_bumps` configuration. When a `bump ` command is issued, this file is only changed if the version component is *not in this list.* The [parse](#parse) configuration defines version components. + +The default value does not exclude anything. + +## Examples + +=== "TOML" + + TOML allows us to specify the files using an [array of tables.](https://toml.io/en/v1.0.0#array-of-tables) TOML configuration adds two 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` 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}" + ``` + +=== "CFG" + + 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` 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/docs/reference/configuration/global.md b/docs/reference/configuration/global.md new file mode 100644 index 00000000..1e90d48a --- /dev/null +++ b/docs/reference/configuration/global.md @@ -0,0 +1,416 @@ +--- +title: Global Configuration +description: Configuration values that affect all of Bump My Version +icon: +date: 2024-08-11 +comments: true +--- +# 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. + +## allow_dirty + +::: field-list + required + : No + + default + : `False` + + 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 has uncommitted changes. This protects you from releasing unversioned files and overwriting unsaved changes. + +## commit + +::: field-list + 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, add an option to [`commit_args`](global.md#commit_args) to turn off your pre-commit hooks. For Git, use `--no-verify` and use `--config hooks.pre-commit=` for Mercurial. + +## commit_args + +::: field-list + + 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`](global.md#commit) option is set to `True`. + +If you have pre-commit hooks, add an option to turn off your pre-commit hooks. For Git, use `--no-verify` and use `--config hooks.pre-commit=` for Mercurial. + +## 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_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 + : No + + default + : `False` + + type + : boolean + + command line option + : `--ignore-missing-version` + + environment var + : `BUMPVERSION_IGNORE_MISSING_VERSION` + +If `True`, don't fail if the version string to be replaced is not found in the file. + +## message + +::: field-list + + 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`](global.md#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). The [formatting context reference](../formatting-context.md) describes the available variables. + +## parse + +::: field-list + 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 ([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`](global.md#serialize) value. Named matching groups ("`(?P...)`") indicate the version part the matched value belongs to. + +## 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 + + 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. + +## search + +::: field-list + required + : No + + default + : `{current_version}` + + type + : string + + command line option + : `--search` + + environment var + : `BUMPVERSION_SEARCH` + +This is the template string for searching. It is rendered using the [formatting context](../formatting-context.md) for searching 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). The [formatting context reference](../formatting-context.md) describes the available variables. + +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 bump only one of the occurrences. + +## serialize + +::: field-list + 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). The [formatting context reference](../formatting-context.md) describes the available variables. + +## sign_tags + +::: field-list + + 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`](global.md#tag) is `True`. + +## tag + +::: field-list + + 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`](global.md#tag_name) option. + +If you are using `git`, don't forget to `git-push` with the `--tags` flag when you are done. + +## tag_message + +::: field-list + 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`](global.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 turn this off and create a *lightweight* tag, you must explicitly set an empty `tag_message` value. + +## tag_name + +::: field-list + + required + : No + + default + : `v{new_version}` + + type + : string + + command line option + : `--tag-name` + + environment var + : `BUMPVERSION_TAG_NAME` + +The template used to render the tag when [`tag`](global.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. + +## Examples + +=== "TOML" + + ```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}" + ``` + +=== "CFG" + + ```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} + ``` diff --git a/docs/reference/configuration/index.md b/docs/reference/configuration/index.md new file mode 100644 index 00000000..d7469840 --- /dev/null +++ b/docs/reference/configuration/index.md @@ -0,0 +1,37 @@ +--- +title: Configuration +description: How to configure Bump My Version +icon: +date: 2024-08-11 +comments: true +--- +# 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. + + +## Configuration sections + +- [Global](global.md) +- [Version Component](version-component.md) +- [File](file.md) diff --git a/docs/reference/configuration/version-component.md b/docs/reference/configuration/version-component.md new file mode 100644 index 00000000..2bc89d7f --- /dev/null +++ b/docs/reference/configuration/version-component.md @@ -0,0 +1,133 @@ +--- +title: Version component-specific configuration +description: Configuration options for a specific version part +icon: +date: 2024-08-11 +comments: true +--- +# Version component-specific configuration + +Version component 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 overridden options. + +## values + +::: field-list + required + : No + + default + : numeric (i.e. `0`, `1`, `2`, …) + + type + : array of strings + +An explicit list of all values to iterate through when bumping this part. An empty array is treated as indicating `numeric` values. + +## optional_value + +::: field-list + 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 + +::: field-list + 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 + +::: field-list + 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. + +## always_increment + +::: field-list + required + : No + + default + : `False` (`True` if `calver_format` is set) + + type + : boolean + +When this value is set to `True`, the part is always incremented when the version is bumped, regardless of the target part. + + +## calver_format + +::: field-list + required + : No + + default + : empty + + type + : string + +The `calver_format` is a string that specifies the format of the version part. It is used to determine the next value when bumping the version. The format is a string that uses the placeholders defined in the [CalVer reference](../calver_reference.md#calendar-versioning-codes). + +## Examples + +=== "TOML" + + ```toml + [tool.bumpversion.parts.release] + values = [ + "alpha", + "beta", + "gamma" + ] + optional_value = "gamma" + ``` + +=== "CFG" + + ```ini + [bumpversion:part:release] + optional_value = gamma + values = + alpha + beta + gamma + ``` diff --git a/docs/reference/formatting-context.md b/docs/reference/formatting-context.md index 345fe0c9..5edb5dd0 100644 --- a/docs/reference/formatting-context.md +++ b/docs/reference/formatting-context.md @@ -58,22 +58,22 @@ These fields will only have values if the code is in a Git or Mercurial reposito `current_version` : The current version serialized as a string - `current_` - : Each version part defined by the [version configuration parsing regular expression](version-parts.md#version-configuration). The default configuration would have `current_major`, `current_minor`, and `current_patch` available. + `current_` + : Each version component defined by the [version configuration parsing regular expression](configuration/global.md#parse). The default configuration would have `current_major`, `current_minor`, and `current_patch` available. `new_version` : The new version serialized as a string - `new_` - : Each version part defined by the [version configuration parsing regular expression](version-parts.md#version-configuration). The default configuration would have `new_major`, `new_minor`, and `new_patch` available. + `new_` + : Each version component defined by the [version configuration parsing regular expression](configuration/global.md#parse). The default configuration would have `new_major`, `new_minor`, and `new_patch` available. !!! note The following fields are only available when serializing a version. ::: field-list - `` - : Each version part defined by the [version configuration parsing regular expression](version-parts.md#version-configuration). The default configuration would have `major`, `minor`, and `patch` available. + `` + : Each version part defined by the [version configuration parsing regular expression](configuration/global.md#parse). The default configuration would have `major`, `minor`, and `patch` available. ## Environment variables diff --git a/docs/reference/index.md b/docs/reference/index.md index 086c4f99..d1ed3da7 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,10 +1,6 @@ -# Reference - -- [Subcommands](subcommands/index.md) - [Command-line interface](cli.md) -- [Configuration](configuration.md) +- [Configuration](configuration/) - [Calendar versioning reference](calver_reference.md) - [Formatting context](formatting-context.md) -- [Version parts](version-parts.md) - [Search and replace configuration](search-and-replace-config.md) -- [API](api/bumpversion/index.md) +- [API](api/) diff --git a/docs/reference/subcommands/index.md b/docs/reference/subcommands/index.md deleted file mode 100644 index ec7b3f28..00000000 --- a/docs/reference/subcommands/index.md +++ /dev/null @@ -1,9 +0,0 @@ -# Subcommand reference - -Bump-my-version uses subcommands to focus its functionality. - -- `bump` triggers the version incrementing workflow -- `replace` replaces the version in files without triggering a version increment. -- `sample-config` helps new users configure bumpy-my-version by printing a sample configuration file. -- `show` provides access to current configuration information. -- `show-bump` helps developers understand the current versioning convention by showing the possible versions resulting from the `bump` subcommand. diff --git a/docs/tutorials/getting-started.md b/docs/tutorials/getting-started.md new file mode 100644 index 00000000..e687fa9e --- /dev/null +++ b/docs/tutorials/getting-started.md @@ -0,0 +1,146 @@ +# Getting Started + +## Installation + +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 +``` + +## Create a default configuration + +The default configuration uses a simplified version of [semantic versioning](https://semver.org/). + +!!! Note + + Python projects can use `pyproject.toml` as the `--destination` of the sample config. + +```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 = "" +``` + +## Visualize the versioning path + +You can see the potential versioning paths with the `show-bump` subcommand. This visualization will help debug any versioning logic you implement. + +```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 +``` + +You can also pass in a specific version to see how bumping that version would work. + +```console title="Showing the potential versioning path from a specific version" +$ bump-my-version show-bump 1.2.3 +1.2.3 ── bump ─┬─ major ─ 2.0.0 + ├─ minor ─ 1.3.0 + ╰─ patch ─ 1.2.4 +``` + + +## Configure a file to modify when bumping + +Let's say your version is stored in a file named `VERSION`. Every time you bump your version, that file needs to change. + +Create the `VERSION` file with the current version `0.1.0`: + +```console title="Create a VERSION file" +$ echo "0.1.0" >> VERSION +``` + +Add the following to the `.bumpversion.toml` file. + +```toml title=".bumpversion.toml" +[[tool.bumpversion.files]] +filename = "VERSION" +``` + +Now bump-my-version will look in the `VERSION` file for the current version in that file and replace it with the new version on each `bump-my-version bump` command. + +## Seeing what would happen with dry-run + +You will increment the version using the `bump` subcommand. You "bump" a specific segment of the version. These segments are defined in the `parse` configuration. In this configuration (`(?P\\d+)\\.(?P\\d+)\\.(?P\\d+)`) the segments are `major`, `minor`, `patch`. + +The `--dry-run` option will explain all the steps it performs without permanent changes. Use the `-vv` option to get the full description for debugging later. + +!!! Note + + If you are in a Git or Mercurial repository, you may see additional messages. + +```console title="Incrementing the minor segment" +$ bump-my-version bump minor --dry-run -vv +Starting BumpVersion 0.25.1 +Reading configuration + Reading config file: /users/gettingstarted/.bumpversion.toml + Parsing current version '0.1.0' + Parsing version '0.1.0' using regexp '(?P\d+)\.(?P\d+)\.(?P\d+)' + Parsed the following values: major=0, minor=1, patch=0 + Attempting to increment part 'minor' + Values are now: major=0, minor=2, patch=0 + Serializing version '' + Using serialization format '{major}.{minor}.{patch}' + Serialized to '0.2.0' + New version will be '0.2.0' +Dry run active, won't touch any files. + +File VERSION: replace `{current_version}` with `{new_version}` + Serializing the current version + Serializing version '' + Using serialization format '{major}.{minor}.{patch}' + Serialized to '0.1.0' + Serializing the new version + Serializing version '' + Using serialization format '{major}.{minor}.{patch}' + Serialized to '0.2.0' + Rendering search pattern with context + No RegEx flag detected. Searching for the default pattern: '0\.1\.0' + Found '0\.1\.0' at line 1: 0.1.0 + Would change file VERSION: + *** before VERSION + --- after VERSION + *************** + *** 1 **** + ! 0.1.0 + --- 1 ---- + ! 0.2.0 + +Processing config file: /users/gettingstarted/.bumpversion.toml + Serializing version '' + Using serialization format '{major}.{minor}.{patch}' + Serialized to '0.1.0' + Serializing version '' + Using serialization format '{major}.{minor}.{patch}' + Serialized to '0.2.0' + Rendering search pattern with context + No RegEx flag detected. Searching for the default pattern: '0\.1\.0' + Found '0\.1\.0' at line 1: 0.1.0 + Would change file /users/gettingstarted/.bumpversion.toml:tool.bumpversion.current_version: + *** before /users/gettingstarted/.bumpversion.toml:tool.bumpversion.current_version + --- after /users/gettingstarted/.bumpversion.toml:tool.bumpversion.current_version + *************** + *** 1 **** + ! 0.1.0 + --- 1 ---- + ! 0.2.0 +Done. +``` diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md deleted file mode 100644 index 4978d42d..00000000 --- a/docs/tutorials/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# Tutorials - - -- [Versioning using semantic versioning](semantic-versioning-example.md) -- [Basic usage](usage.md) diff --git a/docs/tutorials/nav.md b/docs/tutorials/nav.md new file mode 100644 index 00000000..5463892c --- /dev/null +++ b/docs/tutorials/nav.md @@ -0,0 +1,2 @@ +- [Getting Started](getting-started.md) +- [Semantic Versioning](semantic-versioning-example.md) diff --git a/docs/tutorials/usage.md b/docs/tutorials/usage.md deleted file mode 100644 index c906d949..00000000 --- a/docs/tutorials/usage.md +++ /dev/null @@ -1,115 +0,0 @@ -# Usage - -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 processes. We recommend using a configuration file for all but the simplest of projects. - -!!! Warning - - The invocation of `bump-my-version` changed in version 0.6.0. It splits functionality into sub-commands. It remains backward-compatible with previous versions. Previous usage is discouraged and may be removed in a 1.0 release. - -## Incrementing a version - -```console -bump-my-version bump [OPTIONS] [ARGS]... -``` - -The `bump` sub-command triggers a version increment. The [complete list of options](../reference/cli.md#bump-my-version-bump) is available. The `ARGS` may contain a `VERSION_PART` or `FILES` - - -### `VERSION_PART` - -_**[optional]**_ - -The part of the version to increase, e.g., `minor`. - -Valid values include those given in the [`--serialize`](../reference/configuration.md#serialize) / [`--parse`](../reference/configuration.md#parse) option. - -For example, if the current version is `0.5.1` and you want to bump it to `0.6.0`: - -```console -bump-my-version bump minor -``` - - -### `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`. - -For example, if the current version is `1.1.9` and you want to bump the version to `2.0.0` and also change the version in the `_version.txt` file: - -```console -bump-my-version bump major _version.txt -``` - -If you want to bump the current version of `1.1.9` to `2.0.0` and _only_ change the `_version.txt` file: - -```console -bump-my-version bump --no-configured-files major _version.txt -``` - -## Showing configuration information - -```console -bump-my-version show [OPTIONS] [ARGS] -``` - -The `show` subcommand allows you to output the entire or parts of the configuration to the console. The default invocation will output in the default format. The default format changes if one or more than one item is requested. If more than one item is asked for, it outputs the result of Python's `pprint` function. If only one thing is asked for, it outputs that value only. - -```console -$ bump-my-version show current_version -1.0.0 -$ bump-my-version show current_version commit -{'current_version': '1.0.0', 'commit': False} -``` - -You can use the `--increment` option to enable a `new_version` key. - -```console -$ bump-my-version show --increment minor current_version new_version -{'current_version': '1.0.0', 'new_version': '1.1.0'} -``` - -You can also specify the output to be in JSON or YAML format: - -```console -$ bump-my-version show --format yaml current_version -current_version: "1.0.0" -$ bump-my-version show --format yaml current_version commit -current_version: "1.0.0" -commit: false -$ bump-my-version show --format json current_version -{ - "current_version": "1.0.0" -} -$ bump-my-version show --format json current_version commit -{ - "current_version": "1.0.0", - "commit": false, -} -``` - -## Searching and replacing without bumping - -More complex workflows may require you to change one or more files without changing the `current_version` in the configuration file. - -The `replace` sub-command works identically to the `bump` sub-command except for the following: - -- It will not commit or tag any changes -- It will not increment the version -- It will not change the configuration file - -!!! NOTE - - If you do not include the `--new-version` option, the `new_version` context variable will be `None`. - - -One way of providing the `--new-version` option is to use the `bump-my-version show` subcommand with an environment variable: - -```console -$ export BUMPVERSION_NEW_VERSION=$(bump-my-version show new_version --increment ) -$ bump-my-version replace -``` diff --git a/mkdocs.yml b/mkdocs.yml index 1267be10..2168ab9e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,15 +10,15 @@ theme: logo: assets/bump-my-version-logo.svg favicon: assets/favicon.png features: - - navigation.tabs - navigation.sections - navigation.path - navigation.indexes - - toc.integrate + - navigation.top - content.action.edit - content.action.view - content.code.annotate - content.tabs.link + - toc.integrate palette: - media: "(prefers-color-scheme: light)" scheme: default @@ -74,7 +74,7 @@ plugins: - include-markdown - drawio - literate-nav: - nav_file: SUMMARY.md + nav_file: nav.md - gen-files: scripts: - docs/gen_doc_stubs.py @@ -115,9 +115,11 @@ extra_css: - assets/css/cards.css - assets/css/field-list.css -#nav: -# - General: "general/" -# - Provisioning LLMs for Applications: "provisioning-llms/" -# - Tutorials: "tutorials/" -# - Security & Privacy: "security-and-privacy/" -# - Guilds: "guilds/" +nav: + - Home: "index.md" + - Tutorials: "tutorials/" + - How Tos: "howtos/" + - Reference: "reference/" + - Explanation: "explanation/" + - "CHANGELOG.md" + - "CONTRIBUTING.md" diff --git a/pyproject.toml b/pyproject.toml index e02a03eb..060fad88 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -68,7 +68,7 @@ docs = [ "mkdocs-gen-files", "mkdocs-git-authors-plugin", "mkdocs-git-committers-plugin", - "mkdocs-git-revision-date-localized-plugin", + "mkdocs-git-revision-date-localized-plugin>=1.2.6", "mkdocs-include-markdown-plugin", "mkdocs-literate-nav", "mkdocs-material", diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 5eaadb8e..00000000 --- a/requirements.txt +++ /dev/null @@ -1 +0,0 @@ --r requirements/prod.txt diff --git a/requirements/dev.txt b/requirements/dev.txt deleted file mode 100644 index f3863a15..00000000 --- a/requirements/dev.txt +++ /dev/null @@ -1,222 +0,0 @@ -# -# This file is autogenerated by pip-compile with Python 3.11 -# by the following command: -# -# pip-compile --extra=dev --extra=docs --extra=test --output-file=requirements/dev.txt pyproject.toml -# -alabaster==0.7.13 - # via sphinx -annotated-types==0.6.0 - # via pydantic -argopt==0.8.2 - # via git-fame -astroid==3.0.1 - # via sphinx-autodoc2 -babel==2.13.1 - # via sphinx -beautifulsoup4==4.12.2 - # via furo -build==1.0.3 - # via pip-tools -certifi==2023.11.17 - # via requests -cfgv==3.4.0 - # via pre-commit -charset-normalizer==3.3.2 - # via requests -click==8.1.7 - # via - # bump-my-version (pyproject.toml) - # pip-tools - # rich-click - # sphinx-click - # typer -coverage[toml]==7.3.2 - # via - # bump-my-version (pyproject.toml) - # pytest-cov -distlib==0.3.7 - # via virtualenv -docutils==0.20.1 - # via - # myst-parser - # sphinx - # sphinx-click -dotted-notation==0.10.0 - # via bump-my-version (pyproject.toml) -filelock==3.13.1 - # via virtualenv -furo==2023.9.10 - # via bump-my-version (pyproject.toml) -generate-changelog==0.10.0 - # via bump-my-version (pyproject.toml) -ghp-import==2.1.0 - # via bump-my-version (pyproject.toml) -git-fame==2.0.1 - # via bump-my-version (pyproject.toml) -gitdb==4.0.11 - # via gitpython -gitpython==3.1.40 - # via generate-changelog -identify==2.5.33 - # via pre-commit -idna==3.6 - # via requests -imagesize==1.4.1 - # via sphinx -iniconfig==2.0.0 - # via pytest -jinja2==3.1.2 - # via - # generate-changelog - # myst-parser - # sphinx -linkify-it-py==2.0.2 - # via bump-my-version (pyproject.toml) -markdown-it-py==3.0.0 - # via - # mdit-py-plugins - # myst-parser - # rich -markupsafe==2.1.3 - # via jinja2 -mdit-py-plugins==0.4.0 - # via myst-parser -mdurl==0.1.2 - # via markdown-it-py -more-itertools==10.1.0 - # via generate-changelog -myst-parser==2.0.0 - # via bump-my-version (pyproject.toml) -nodeenv==1.8.0 - # via pre-commit -packaging==23.2 - # via - # build - # pytest - # sphinx -pip-tools==7.3.0 - # via bump-my-version (pyproject.toml) -platformdirs==4.1.0 - # via virtualenv -pluggy==1.3.0 - # via pytest -pre-commit==3.5.0 - # via bump-my-version (pyproject.toml) -pydantic==2.5.2 - # via - # bump-my-version (pyproject.toml) - # pydantic-settings -pydantic-core==2.14.5 - # via pydantic -pydantic-settings==2.1.0 - # via bump-my-version (pyproject.toml) -pygments==2.17.2 - # via - # furo - # rich - # sphinx -pyparsing==3.1.1 - # via dotted-notation -pyproject-hooks==1.0.0 - # via build -pytest==7.4.3 - # via - # bump-my-version (pyproject.toml) - # pytest-cov - # pytest-mock -pytest-cov==4.1.0 - # via bump-my-version (pyproject.toml) -pytest-mock==3.12.0 - # via bump-my-version (pyproject.toml) -python-dateutil==2.8.2 - # via ghp-import -python-dotenv==1.0.0 - # via pydantic-settings -pyyaml==6.0.1 - # via - # myst-parser - # pre-commit -requests==2.31.0 - # via sphinx -rich==13.7.0 - # via - # bump-my-version (pyproject.toml) - # rich-click -rich-click==1.7.2 - # via bump-my-version (pyproject.toml) -ruamel-yaml==0.18.5 - # via generate-changelog -ruamel-yaml-clib==0.2.8 - # via ruamel-yaml -six==1.16.0 - # via python-dateutil -smmap==5.0.1 - # via gitdb -snowballstemmer==2.2.0 - # via sphinx -soupsieve==2.5 - # via beautifulsoup4 -sphinx==7.2.6 - # via - # bump-my-version (pyproject.toml) - # furo - # myst-parser - # sphinx-autodoc-typehints - # sphinx-basic-ng - # sphinx-click - # sphinx-copybutton - # sphinxcontrib-applehelp - # sphinxcontrib-devhelp - # sphinxcontrib-htmlhelp - # sphinxcontrib-qthelp - # sphinxcontrib-serializinghtml -sphinx-autodoc-typehints==1.25.2 - # via bump-my-version (pyproject.toml) -sphinx-autodoc2==0.5.0 - # via bump-my-version (pyproject.toml) -sphinx-basic-ng==1.0.0b2 - # via furo -sphinx-click==5.1.0 - # via bump-my-version (pyproject.toml) -sphinx-copybutton==0.5.2 - # via bump-my-version (pyproject.toml) -sphinxcontrib-applehelp==1.0.7 - # via sphinx -sphinxcontrib-devhelp==1.0.5 - # via sphinx -sphinxcontrib-htmlhelp==2.0.4 - # via sphinx -sphinxcontrib-jsmath==1.0.1 - # via sphinx -sphinxcontrib-qthelp==1.0.6 - # via sphinx -sphinxcontrib-serializinghtml==1.1.9 - # via sphinx -tabulate==0.9.0 - # via git-fame -tomlkit==0.12.3 - # via bump-my-version (pyproject.toml) -tqdm==4.66.1 - # via git-fame -typer==0.9.0 - # via generate-changelog -typing-extensions==4.8.0 - # via - # pydantic - # pydantic-core - # rich-click - # sphinx-autodoc2 - # typer -uc-micro-py==1.0.2 - # via linkify-it-py -urllib3==2.1.0 - # via requests -virtualenv==20.25.0 - # via pre-commit -wheel==0.42.0 - # via pip-tools - -# The following packages are considered to be unsafe in a requirements file: -# pip -# setuptools diff --git a/requirements/docs.txt b/requirements/docs.txt deleted file mode 100644 index fa9959d3..00000000 --- a/requirements/docs.txt +++ /dev/null @@ -1,144 +0,0 @@ -# -# This file is autogenerated by pip-compile with Python 3.11 -# by the following command: -# -# pip-compile --extra=docs --output-file=requirements/docs.txt pyproject.toml -# -alabaster==0.7.13 - # via sphinx -annotated-types==0.6.0 - # via pydantic -astroid==3.0.1 - # via sphinx-autodoc2 -babel==2.13.1 - # via sphinx -beautifulsoup4==4.12.2 - # via furo -certifi==2023.11.17 - # via requests -charset-normalizer==3.3.2 - # via requests -click==8.1.7 - # via - # bump-my-version (pyproject.toml) - # rich-click - # sphinx-click -docutils==0.20.1 - # via - # myst-parser - # sphinx - # sphinx-click -dotted-notation==0.10.0 - # via bump-my-version (pyproject.toml) -furo==2023.9.10 - # via bump-my-version (pyproject.toml) -ghp-import==2.1.0 - # via bump-my-version (pyproject.toml) -idna==3.6 - # via requests -imagesize==1.4.1 - # via sphinx -jinja2==3.1.2 - # via - # myst-parser - # sphinx -linkify-it-py==2.0.2 - # via bump-my-version (pyproject.toml) -markdown-it-py==3.0.0 - # via - # mdit-py-plugins - # myst-parser - # rich -markupsafe==2.1.3 - # via jinja2 -mdit-py-plugins==0.4.0 - # via myst-parser -mdurl==0.1.2 - # via markdown-it-py -myst-parser==2.0.0 - # via bump-my-version (pyproject.toml) -packaging==23.2 - # via sphinx -pydantic==2.5.2 - # via - # bump-my-version (pyproject.toml) - # pydantic-settings -pydantic-core==2.14.5 - # via pydantic -pydantic-settings==2.1.0 - # via bump-my-version (pyproject.toml) -pygments==2.17.2 - # via - # furo - # rich - # sphinx -pyparsing==3.1.1 - # via dotted-notation -python-dateutil==2.8.2 - # via ghp-import -python-dotenv==1.0.0 - # via pydantic-settings -pyyaml==6.0.1 - # via myst-parser -requests==2.31.0 - # via sphinx -rich==13.7.0 - # via - # bump-my-version (pyproject.toml) - # rich-click -rich-click==1.7.2 - # via bump-my-version (pyproject.toml) -six==1.16.0 - # via python-dateutil -snowballstemmer==2.2.0 - # via sphinx -soupsieve==2.5 - # via beautifulsoup4 -sphinx==7.2.6 - # via - # bump-my-version (pyproject.toml) - # furo - # myst-parser - # sphinx-autodoc-typehints - # sphinx-basic-ng - # sphinx-click - # sphinx-copybutton - # sphinxcontrib-applehelp - # sphinxcontrib-devhelp - # sphinxcontrib-htmlhelp - # sphinxcontrib-qthelp - # sphinxcontrib-serializinghtml -sphinx-autodoc-typehints==1.25.2 - # via bump-my-version (pyproject.toml) -sphinx-autodoc2==0.5.0 - # via bump-my-version (pyproject.toml) -sphinx-basic-ng==1.0.0b2 - # via furo -sphinx-click==5.1.0 - # via bump-my-version (pyproject.toml) -sphinx-copybutton==0.5.2 - # via bump-my-version (pyproject.toml) -sphinxcontrib-applehelp==1.0.7 - # via sphinx -sphinxcontrib-devhelp==1.0.5 - # via sphinx -sphinxcontrib-htmlhelp==2.0.4 - # via sphinx -sphinxcontrib-jsmath==1.0.1 - # via sphinx -sphinxcontrib-qthelp==1.0.6 - # via sphinx -sphinxcontrib-serializinghtml==1.1.9 - # via sphinx -tomlkit==0.12.3 - # via bump-my-version (pyproject.toml) -typing-extensions==4.8.0 - # via - # pydantic - # pydantic-core - # rich-click - # sphinx-autodoc2 -uc-micro-py==1.0.2 - # via linkify-it-py -urllib3==2.1.0 - # via requests diff --git a/requirements/prod.txt b/requirements/prod.txt deleted file mode 100644 index 3fd69fec..00000000 --- a/requirements/prod.txt +++ /dev/null @@ -1,45 +0,0 @@ -# -# This file is autogenerated by pip-compile with Python 3.11 -# by the following command: -# -# pip-compile --output-file=requirements/prod.txt pyproject.toml -# -annotated-types==0.6.0 - # via pydantic -click==8.1.7 - # via - # bump-my-version (pyproject.toml) - # rich-click -dotted-notation==0.10.0 - # via bump-my-version (pyproject.toml) -markdown-it-py==3.0.0 - # via rich -mdurl==0.1.2 - # via markdown-it-py -pydantic==2.5.2 - # via - # bump-my-version (pyproject.toml) - # pydantic-settings -pydantic-core==2.14.5 - # via pydantic -pydantic-settings==2.1.0 - # via bump-my-version (pyproject.toml) -pygments==2.17.2 - # via rich -pyparsing==3.1.1 - # via dotted-notation -python-dotenv==1.0.0 - # via pydantic-settings -rich==13.7.0 - # via - # bump-my-version (pyproject.toml) - # rich-click -rich-click==1.7.2 - # via bump-my-version (pyproject.toml) -tomlkit==0.12.3 - # via bump-my-version (pyproject.toml) -typing-extensions==4.8.0 - # via - # pydantic - # pydantic-core - # rich-click diff --git a/requirements/test.txt b/requirements/test.txt deleted file mode 100644 index 9ff09f39..00000000 --- a/requirements/test.txt +++ /dev/null @@ -1,85 +0,0 @@ -# -# This file is autogenerated by pip-compile with Python 3.11 -# by the following command: -# -# pip-compile --extra=test --output-file=requirements/test.txt pyproject.toml -# -annotated-types==0.6.0 - # via pydantic -cfgv==3.4.0 - # via pre-commit -click==8.1.7 - # via - # bump-my-version (pyproject.toml) - # rich-click -coverage[toml]==7.3.2 - # via - # bump-my-version (pyproject.toml) - # pytest-cov -distlib==0.3.7 - # via virtualenv -dotted-notation==0.10.0 - # via bump-my-version (pyproject.toml) -filelock==3.13.1 - # via virtualenv -identify==2.5.33 - # via pre-commit -iniconfig==2.0.0 - # via pytest -markdown-it-py==3.0.0 - # via rich -mdurl==0.1.2 - # via markdown-it-py -nodeenv==1.8.0 - # via pre-commit -packaging==23.2 - # via pytest -platformdirs==4.1.0 - # via virtualenv -pluggy==1.3.0 - # via pytest -pre-commit==3.5.0 - # via bump-my-version (pyproject.toml) -pydantic==2.5.2 - # via - # bump-my-version (pyproject.toml) - # pydantic-settings -pydantic-core==2.14.5 - # via pydantic -pydantic-settings==2.1.0 - # via bump-my-version (pyproject.toml) -pygments==2.17.2 - # via rich -pyparsing==3.1.1 - # via dotted-notation -pytest==7.4.3 - # via - # bump-my-version (pyproject.toml) - # pytest-cov - # pytest-mock -pytest-cov==4.1.0 - # via bump-my-version (pyproject.toml) -pytest-mock==3.12.0 - # via bump-my-version (pyproject.toml) -python-dotenv==1.0.0 - # via pydantic-settings -pyyaml==6.0.1 - # via pre-commit -rich==13.7.0 - # via - # bump-my-version (pyproject.toml) - # rich-click -rich-click==1.7.2 - # via bump-my-version (pyproject.toml) -tomlkit==0.12.3 - # via bump-my-version (pyproject.toml) -typing-extensions==4.8.0 - # via - # pydantic - # pydantic-core - # rich-click -virtualenv==20.25.0 - # via pre-commit - -# The following packages are considered to be unsafe in a requirements file: -# setuptools diff --git a/tests/test_cli/test_bump.py b/tests/test_cli/test_bump.py index e52383b9..2afe3a49 100644 --- a/tests/test_cli/test_bump.py +++ b/tests/test_cli/test_bump.py @@ -195,11 +195,11 @@ def test_non_scm_operations_if_scm_not_installed(tmp_path: Path, monkeypatch, ru @pytest.mark.parametrize( ["version_part"], [ - param("charlie", id="bad_version_part"), - param("", id="missing_version_part"), + param("charlie", id="bad_version_component"), + param("", id="missing_version_component"), ], ) -def test_detects_bad_or_missing_version_part(version_part: str, tmp_path: Path, monkeypatch, runner): +def test_detects_bad_or_missing_version_component(version_part: str, tmp_path: Path, monkeypatch, runner): """It properly detects bad or missing version part.""" # Arrange monkeypatch.setenv("PATH", "") @@ -217,7 +217,7 @@ def test_detects_bad_or_missing_version_part(version_part: str, tmp_path: Path, # Assert assert result.exception is not None - assert "Unknown version part:" in result.stdout + assert "Unknown version component:" in result.stdout def test_ignores_missing_files_with_option(tmp_path, fixtures_path, runner):