Added how-to doc.

- "How to update a date in a file"

Author: coordt

docsrc/howtos/update-a-date.md

@@ -0,0 +1,30 @@
+# How to update a date in a file
+
+Many times when bumping a version, you will also want to update a date in a file. This is a common use case for changelogs, but it could be any file that contains a date. In this example, we have an `__init__.py` that looks like this:
+
+```python title="my_package/__init__.py"
+__date__ = '2022-12-19'
+__version__ = '0.4.0'
+```
+
+The desired outcome is to update the date to the current date. For example, if today is February 23, 2024, the __init__.py file should look like this after a `minor` bump:
+
+```python title="my_package/__init__.py"
+__date__ = '2024-02-23'
+__version__ = '0.5.0'
+```
+
+## Setting up the file configurations
+
+We need Bump My Version to update the `__init__.py` file twice: once for the version and once for the date. Here is the necessary configuration:
+
+```toml title=".bumpversion.toml or other config file"
+[[tool.bumpversion.files]]
+filename = '__init__.py'
+search = "__date__ = '\\d{{4}}-\\d{{2}}-\\d{{2}}'"
+replace = "__date__ = '{now:%Y-%m-%d}'"
+regex = true
+
+[[tool.bumpversion.files]]
+filename = '__init__.py'
+```

tests/fixtures/replace-date-config.toml

@@ -0,0 +1,11 @@
+[tool.bumpversion]
+current_version = '1.2.3'
+
+[[tool.bumpversion.files]]
+filename = 'VERSION'
+search = "__date__ = '\\d{{4}}-\\d{{2}}-\\d{{2}}'"
+replace = "__date__ = '{now:%Y-%m-%d}'"
+regex = true
+
+[[tool.bumpversion.files]]
+filename = 'VERSION'

tests/test_files.py

@@ -410,6 +410,29 @@ def test_regex_search_with_escaped_chars(tmp_path: Path) -> None:
     assert version_path.read_text() == f"## [Release] 1.2.4 {now}"
 
 
+def test_regex_search_in_toml(tmp_path: Path, fixtures_path: Path) -> None:
+    """Tests how-to doc 'update-a-date.md'."""
+    # Arrange
+    version_path = tmp_path / "VERSION"
+    version_path.write_text("__date__ = '1234-56-78'\n__version__ = '1.2.3'")
+    config_path = tmp_path / ".bumpversion.toml"
+    shutil.copyfile(fixtures_path / "replace-date-config.toml", config_path)
+    with inside_dir(tmp_path):
+        conf = config.get_configuration(config_file=config_path)
+        version_config = VersionConfig(conf.parse, conf.serialize, conf.search, conf.replace, conf.parts)
+        current_version = version_config.parse(conf.current_version)
+
+        new_version = current_version.bump("patch")
+        cfg_files = [files.ConfiguredFile(file_cfg, version_config) for file_cfg in conf.files]
+
+        # Act
+        files.modify_files(cfg_files, current_version, new_version, get_context(conf))
+
+    # Assert
+    now = datetime.now().isoformat()[:10]
+    assert version_path.read_text() == f"__date__ = '{now}'\n__version__ = '1.2.4'"
+
+
 def test_regex_search_with_caret(tmp_path: Path, fixtures_path: Path) -> None:
     """A search that uses a caret to indicate the beginning of the line works correctly."""
     # Arrange