Added documentation for ignore missing version

coordt · coordt · commit e0731c37b8cc · 2023-07-13T12:10:14.000-05:00
diff --git a/docsrc/howtos/avoid-incorrect-replacements.md b/docsrc/howtos/avoid-incorrect-replacements.md
@@ -0,0 +1,42 @@
+# Avoiding 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`:
+
+```text
+Django>=1.5.6,<1.6
+MyProject==1.5.6
+```
+
+The default search and replace templates will replace the wrong text. Instead of changing `MyProject`'s version from `1.5.6` to `1.6.0`, it changes `Django`'s version:
+
+```text
+Django>=1.6.0,<1.6
+MyProject==1.5.6
+```
+
+Providing search and replace templates for the `requirements.txt` file will avoid this.
+
+This `.bumpversion.toml` will ensure only the line containing `MyProject` will be changed:
+
+```toml
+[tool.bumpversion]
+current_version = "1.5.6"
+
+[[tool.bumpversion.files]]
+filename = "requirements.txt"
+search = "MyProject=={current_version}"
+replace = "MyProject=={new_version}"
+```
+
+If the string to be replaced includes literal quotes, the search and replace patterns must include them to match. Given the file `version.sh`:
+
+    MY_VERSION="1.2.3"
+
+Then the following search and replace patterns (including quotes) would be required:
+
+```toml
+[[tool.bumpversion.files]]
+filename = "version.sh"
+search = "MY_VERSION=\"{current_version}\""
+replace = "MY_VERSION=\"{new_version}\""
+```
diff --git a/docsrc/howtos/custom-version-formats-by-file.md b/docsrc/howtos/custom-version-formats-by-file.md
@@ -0,0 +1,48 @@
+# Custom version formats in different files
+
+You can use file configurations to replace the version in multiple files, even if each file has the version formatted differently.
+
+In a module-aware Go project, when you create a major version of your module beyond `v1`, your module name must include the major version number (e.g., `github.com/myorg/myproject/v2`). However, you also have the full version in a YAML file named `release-channels.yaml`.
+
+`go.mod` file:
+
+```go
+module github.com/myorg/myproject/v2
+
+go 1.12
+
+require (
+    ...
+)
+```
+
+`release-channels.yaml` file:
+
+```yaml
+stable: "v2.21.4"
+```
+
+You can use bump-my-version to maintain the major version number within the `go.mod` file by using the `parse` and `serialize` options, as in this example:
+
+ `.bumpversion.toml` file:
+
+```toml
+[tool.bumpversion]
+current_version = "2.21.4"
+
+[[tool.bumpversion.files]]
+filename = "go.mod"
+parse = "(?P<major>\\d+)"
+serialize = "{major}"
+search = "module github.com/myorg/myproject/v{current_version}"
+replace = "module github.com/myorg/myproject/v{new_version}"
+
+[[tool.bumpversion.files]]
+filename = "release-channels.yaml"
+```
+
+While all the version bumps are `minor` or `patch`, the `go.mod` file doesn't change, while the `release-channels.yaml` file will. As soon as you do a `major` version bump, the `go.mod` file now contains this module directive:
+
+```go
+module github.com/myorg/myproject/v3
+```
diff --git a/docsrc/howtos/index.md b/docsrc/howtos/index.md
@@ -3,4 +3,7 @@
 
 
 ```{toctree}
+avoid-incorrect-replacements
+custom-version-formats-by-file
+multiple-replacements
 ```
diff --git a/docsrc/howtos/multiple-replacements.md b/docsrc/howtos/multiple-replacements.md
@@ -0,0 +1,20 @@
+# Multiple replacements within the same file
+
+To make several replacements in the same file, you must configure multiple `[[tool.bumpversion.files]]` sections for the same file with different configuration options.
+
+In this example, the changelog is generated before the version bump. It uses `Unreleased` as the heading and includes a link to GitHub to compare this version (`HEAD`) with the previous version.
+
+To change `Unreleased ` to the current version, we have an entry with `search` set to `Unreleased`.  The default `replace` value is `{new_version}`, so changing it is unnecessary.
+
+To change the link, another entry has its `search` set to `{current_version}...HEAD` and the `replace` set to `{current_version}...{new_version}`.
+
+```toml
+[[tool.bumpversion.files]]
+filename = "CHANGELOG.md"
+search = "Unreleased"
+
+[[tool.bumpversion.files]]
+filename = "CHANGELOG.md"
+search = "{current_version}...HEAD"
+replace = "{current_version}...{new_version}"
+```
diff --git a/docsrc/reference/bumpversion/bumpversion.cli.md b/docsrc/reference/bumpversion/bumpversion.cli.md
@@ -64,7 +64,7 @@
 ```
 ````
 
-````{py:function} bump(args: list, config_file: typing.Optional[str], verbose: int, allow_dirty: typing.Optional[bool], current_version: typing.Optional[str], new_version: typing.Optional[str], parse: typing.Optional[str], serialize: typing.Optional[typing.List[str]], search: typing.Optional[str], replace: typing.Optional[str], no_configured_files: bool, dry_run: bool, commit: typing.Optional[bool], tag: typing.Optional[bool], sign_tags: typing.Optional[bool], tag_name: typing.Optional[str], tag_message: typing.Optional[str], message: typing.Optional[str], commit_args: typing.Optional[str], show_list: bool) -> None
+````{py:function} bump(args: list, config_file: typing.Optional[str], verbose: int, allow_dirty: typing.Optional[bool], current_version: typing.Optional[str], new_version: typing.Optional[str], parse: typing.Optional[str], serialize: typing.Optional[typing.List[str]], search: typing.Optional[str], replace: typing.Optional[str], no_configured_files: bool, ignore_missing_version: bool, dry_run: bool, commit: typing.Optional[bool], tag: typing.Optional[bool], sign_tags: typing.Optional[bool], tag_name: typing.Optional[str], tag_message: typing.Optional[str], message: typing.Optional[str], commit_args: typing.Optional[str], show_list: bool) -> None
 :canonical: bumpversion.cli.bump
 
 ```{autodoc2-docstring} bumpversion.cli.bump
@@ -78,7 +78,7 @@
 ```
 ````
 
-````{py:function} replace(files: list, config_file: typing.Optional[str], verbose: int, allow_dirty: typing.Optional[bool], current_version: typing.Optional[str], new_version: typing.Optional[str], parse: typing.Optional[str], serialize: typing.Optional[typing.List[str]], search: typing.Optional[str], replace: typing.Optional[str], no_configured_files: bool, dry_run: bool) -> None
+````{py:function} replace(files: list, config_file: typing.Optional[str], verbose: int, allow_dirty: typing.Optional[bool], current_version: typing.Optional[str], new_version: typing.Optional[str], parse: typing.Optional[str], serialize: typing.Optional[typing.List[str]], search: typing.Optional[str], replace: typing.Optional[str], no_configured_files: bool, ignore_missing_version: bool, dry_run: bool) -> None
 :canonical: bumpversion.cli.replace
 
 ```{autodoc2-docstring} bumpversion.cli.replace
diff --git a/docsrc/reference/bumpversion/bumpversion.config.md b/docsrc/reference/bumpversion/bumpversion.config.md
@@ -35,6 +35,10 @@
 :class: autosummary longtable
 :align: left
 
+* - {py:obj}`get_all_file_configs <bumpversion.config.get_all_file_configs>`
+  - ```{autodoc2-docstring} bumpversion.config.get_all_file_configs
+    :summary:
+    ```
 * - {py:obj}`get_configuration <bumpversion.config.get_configuration>`
   - ```{autodoc2-docstring} bumpversion.config.get_configuration
     :summary:
@@ -229,6 +233,17 @@ Bases: {py:obj}`pydantic.BaseModel`
 
 ````
 
+````{py:attribute} ignore_missing_version
+:canonical: bumpversion.config.FileConfig.ignore_missing_version
+:type: typing.Optional[bool]
+:value: >
+   None
+
+```{autodoc2-docstring} bumpversion.config.FileConfig.ignore_missing_version
+```
+
+````
+
 `````
 
 ``````{py:class} Config
@@ -294,6 +309,17 @@ Bases: {py:obj}`pydantic.BaseSettings`
 
 ````
 
+````{py:attribute} ignore_missing_version
+:canonical: bumpversion.config.Config.ignore_missing_version
+:type: bool
+:value: >
+   None
+
+```{autodoc2-docstring} bumpversion.config.Config.ignore_missing_version
+```
+
+````
+
 ````{py:attribute} tag
 :canonical: bumpversion.config.Config.tag
 :type: bool
@@ -472,6 +498,13 @@ Bases: {py:obj}`pydantic.BaseSettings`
 
 ````
 
+````{py:function} get_all_file_configs(config_dict: dict) -> typing.List[bumpversion.config.FileConfig]
+:canonical: bumpversion.config.get_all_file_configs
+
+```{autodoc2-docstring} bumpversion.config.get_all_file_configs
+```
+````
+
 ````{py:function} get_configuration(config_file: typing.Union[str, pathlib.Path, None] = None, **overrides) -> bumpversion.config.Config
 :canonical: bumpversion.config.get_configuration
 
diff --git a/docsrc/reference/bumpversion/bumpversion.files.md b/docsrc/reference/bumpversion/bumpversion.files.md
@@ -69,7 +69,7 @@
 
 ````
 
-`````{py:class} ConfiguredFile(file_cfg: bumpversion.config.FileConfig, version_config: bumpversion.version_part.VersionConfig)
+`````{py:class} ConfiguredFile(file_cfg: bumpversion.config.FileConfig, version_config: bumpversion.version_part.VersionConfig, search: typing.Optional[str] = None, replace: typing.Optional[str] = None)
 :canonical: bumpversion.files.ConfiguredFile
 
 ```{autodoc2-docstring} bumpversion.files.ConfiguredFile
@@ -117,7 +117,7 @@
 
 `````
 
-````{py:function} resolve_file_config(files: typing.List[bumpversion.config.FileConfig], version_config: bumpversion.version_part.VersionConfig) -> typing.List[bumpversion.files.ConfiguredFile]
+````{py:function} resolve_file_config(files: typing.List[bumpversion.config.FileConfig], version_config: bumpversion.version_part.VersionConfig, search: typing.Optional[str] = None, replace: typing.Optional[str] = None) -> typing.List[bumpversion.files.ConfiguredFile]
 :canonical: bumpversion.files.resolve_file_config
 
 ```{autodoc2-docstring} bumpversion.files.resolve_file_config
@@ -131,7 +131,7 @@
 ```
 ````
 
-````{py:function} get_glob_files(file_cfg: bumpversion.config.FileConfig, version_config: bumpversion.version_part.VersionConfig) -> typing.List[bumpversion.files.ConfiguredFile]
+````{py:function} get_glob_files(file_cfg: bumpversion.config.FileConfig, version_config: bumpversion.version_part.VersionConfig, search: typing.Optional[str] = None, replace: typing.Optional[str] = None) -> typing.List[bumpversion.files.ConfiguredFile]
 :canonical: bumpversion.files.get_glob_files
 
 ```{autodoc2-docstring} bumpversion.files.get_glob_files
diff --git a/docsrc/reference/bumpversion/bumpversion.md b/docsrc/reference/bumpversion/bumpversion.md
@@ -51,7 +51,7 @@ bumpversion.__main__
 :canonical: bumpversion.__version__
 :type: str
 :value: >
-   '0.6.0'
+   '0.7.1'
 
 ```{autodoc2-docstring} bumpversion.__version__
 ```
diff --git a/docsrc/reference/bumpversion/bumpversion.ui.md b/docsrc/reference/bumpversion/bumpversion.ui.md
@@ -23,6 +23,10 @@
   - ```{autodoc2-docstring} bumpversion.ui.print_error
     :summary:
     ```
+* - {py:obj}`print_warning <bumpversion.ui.print_warning>`
+  - ```{autodoc2-docstring} bumpversion.ui.print_warning
+    :summary:
+    ```
 ````
 
 ### API
@@ -40,3 +44,10 @@
 ```{autodoc2-docstring} bumpversion.ui.print_error
 ```
 ````
+
+````{py:function} print_warning(msg: str) -> None
+:canonical: bumpversion.ui.print_warning
+
+```{autodoc2-docstring} bumpversion.ui.print_warning
+```
+````
diff --git a/docsrc/reference/configuration.md b/docsrc/reference/configuration.md
diff --git a/docsrc/reference/search-and-replace-config.md b/docsrc/reference/search-and-replace-config.md
diff --git a/pyproject.toml b/pyproject.toml
