From 68f9eee8f953c23d30b8ef77a3cedf9355ce55a0 Mon Sep 17 00:00:00 2001 From: Corey Oordt Date: Tue, 4 Jun 2024 10:47:24 -0500 Subject: [PATCH 1/2] Renamed version workflow to release --- .github/workflows/{version.yaml => release.yaml} | 0 .pre-commit-config.yaml | 6 +++--- 2 files changed, 3 insertions(+), 3 deletions(-) rename .github/workflows/{version.yaml => release.yaml} (100%) diff --git a/.github/workflows/version.yaml b/.github/workflows/release.yaml similarity index 100% rename from .github/workflows/version.yaml rename to .github/workflows/release.yaml diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0dd9cca6..b4a1604b 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,7 +1,7 @@ repos: - repo: https://github.com/astral-sh/ruff-pre-commit # Ruff version. - rev: 'v0.4.3' + rev: 'v0.4.7' hooks: - id: ruff args: [--fix, --exit-non-zero-on-fix] @@ -11,7 +11,7 @@ repos: hooks: - id: black - repo: https://github.com/codespell-project/codespell - rev: v2.2.6 + rev: v2.3.0 hooks: - id: codespell additional_dependencies: @@ -56,7 +56,7 @@ repos: args: [--no-strict-optional, --ignore-missing-imports] additional_dependencies: ["pydantic>2.0", "toml", "types-all"] - repo: https://github.com/jsh9/pydoclint - rev: 0.4.1 + rev: 0.4.2 hooks: - id: pydoclint args: From 91409d81d647a6dc1e39d3cfbc1e0e95a5c67a82 Mon Sep 17 00:00:00 2001 From: Corey Oordt Date: Tue, 11 Jun 2024 10:50:48 -0500 Subject: [PATCH 2/2] Add extensive documentation for the 'show' subcommand This commit adds extensive documentation for the `show` subcommand in the program's reference. It also includes smaller updates and corrections to other parts of the documentation. An in-depth example usage of `show` is added both to the dedicated `show.md` file and in the function's docstring. --- bumpversion/cli.py | 14 +++++++- docs/reference/cli.md | 2 ++ docs/reference/configuration.md | 6 ++-- docs/reference/index.md | 3 +- docs/reference/subcommands/index.md | 9 +++++ docs/reference/subcommands/show.md | 53 +++++++++++++++++++++++++++++ 6 files changed, 82 insertions(+), 5 deletions(-) create mode 100644 docs/reference/subcommands/index.md create mode 100644 docs/reference/subcommands/show.md diff --git a/bumpversion/cli.py b/bumpversion/cli.py index 78de24f3..3df3ff21 100644 --- a/bumpversion/cli.py +++ b/bumpversion/cli.py @@ -338,7 +338,19 @@ def bump( help="Increment the version part and add `new_version` to the configuration.", ) def show(args: List[str], config_file: Optional[str], format_: str, increment: Optional[str]) -> None: - """Show current configuration information.""" + """ + Show current configuration information. + + ARGS may contain one or more configuration attributes. For example: + + - `bump-my-version show current_version` + + - `bump-my-version show files.0.filename` + + - `bump-my-version show scm_info.branch_name` + + - `bump-my-version show current_version scm_info.distance_to_latest_tag` + """ found_config_file = find_config_file(config_file) config = get_configuration(found_config_file) diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 7e32e484..28232b13 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -1,3 +1,5 @@ +# CLI Reference + ::: mkdocs-click :module: bumpversion.cli :command: cli diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 8779ab06..39fe95c8 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -68,7 +68,7 @@ Bump-my-version's default behavior is to abort if the working directory has unco 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. +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 @@ -339,7 +339,7 @@ If `True`, sign the created tag, when [`tag`](configuration.md#tag) is `True`. 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 `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. @@ -533,7 +533,7 @@ When this value is set to `True`, the part is always incremented when the versio 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). +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 diff --git a/docs/reference/index.md b/docs/reference/index.md index a74ae62a..086c4f99 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -1,8 +1,9 @@ # Reference - +- [Subcommands](subcommands/index.md) - [Command-line interface](cli.md) - [Configuration](configuration.md) +- [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) diff --git a/docs/reference/subcommands/index.md b/docs/reference/subcommands/index.md new file mode 100644 index 00000000..ec7b3f28 --- /dev/null +++ b/docs/reference/subcommands/index.md @@ -0,0 +1,9 @@ +# 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/reference/subcommands/show.md b/docs/reference/subcommands/show.md new file mode 100644 index 00000000..e90f0acc --- /dev/null +++ b/docs/reference/subcommands/show.md @@ -0,0 +1,53 @@ +# The show subcommand + +The main purpose of the `show` subcommand is to provide access to configuration data via scripts. + +## Basic use + +The configuration object is a `dict` containing nested data structures. The arguments and options of this command relate to extracting data from the configuration object and presenting the extracted data. + +## Specifying the output data + +The positional arguments determine the data shown. If nothing or `all` is passed, the entire configuration is shown. + +Positional arguments are specified using a format like [Django variable resolution](https://docs.djangoproject.com/en/5.0/ref/templates/language/#variables). + +Examples: + +- `a.b` specifies the "b" key in the nested dictionaries: `{"a": {"b": "value"}}` +- `a.3` specifies the 4th item (the first is 0) of the list at key "a": `{"a": ["no", "nay", "nyet", "value"]}` + +## Specifying the output format + +If only one positional argument is passed, the default format only shows its value. If no positional arguments, several positional arguments, or `all` is passed, the output from [`pprint.pprint`](https://docs.python.org/3.12/library/pprint.html#pprint.pprint) is shown. + +This makes getting the current version easy: + +```console +$ bump-my-version show current_version +1.0.1 +``` + +You can request the output be formatted as YAML or JSON: + +```console +$ bump-my-version show --format yaml current_version +current_version: "1.0.1" +$ bump-my-version show --format json current_version +{ + "current_version": "1.0.1" +} +``` + +## Including the incremented version before bumping + +Your workflow might want to know the new version before you actually do the bumping. The `--increment` or `-i` option accepts a version part to bump and adds a `new_version` key into the configuration. + +```console +$ bump-my-version --increment patch show +1.0.2 +$ bump-my-version --increment minor show +1.1.0 +$ bump-my-version --increment major show +2.0.0 +```