docs(monorepo): improve docs and add docs to verify it works

Author: woile

docs/tutorials/monorepo_guidance.md

@@ -3,85 +3,70 @@
 This tutorial assumes that your monorepo is structured with multiple components that can be released independently of each other.
 It also assumes that you are using conventional commits with scopes.
 
-Here is a step-by-step example using two libraries, `library-b` and `library-z`:
+Here is a step-by-step example using two libraries, `library-foo` and `library-alice`:
 
 1. **Organize your monorepo**
 
-    For example, you might have one of these layouts:
+For example, you might have one of these layouts:
 
-    ```shell-session
-    .
-    ├── library-b
-    │   └── .cz.toml
-    └── library-z
-        └── .cz.toml
-    ```
+```shell-session
+.
+├── library-foo
+│   └── .cz.toml
+└── library-alice
+    └── .cz.toml
+```
 
-    ```shell-session
-    src
-    ├── library-b
-    │   └── .cz.toml
-    └── library-z
-        └── .cz.toml
-    ```
+```shell-session
+src
+├── library-foo
+│   └── .cz.toml
+└── library-alice
+    └── .cz.toml
+```
 
 2. **Add a Commitizen configuration for each component**
 
-    ```toml
-    # library-b/.cz.toml
-    [tool.commitizen]
-    name = "cz_customize"
-    version = "0.0.0"
-    tag_format = "${version}-library-b" # the component name can be a prefix or suffix with or without a separator
-    ignored_tag_formats = ["${version}-library-*"] # Avoid noise from other tags
-    update_changelog_on_bump = true
-    ```
-
-    ```toml
-    # library-z/.cz.toml
-    [tool.commitizen]
-    name = "cz_customize"
-    version = "0.0.0"
-    tag_format = "${version}-library-z"
-    ignored_tag_formats = ["${version}-library-*"] # Avoid noise from other tags
-    update_changelog_on_bump = true
-    ```
+```toml
+# library-foo/.cz.toml
+[tool.commitizen]
+name = "cz_customize"
+version = "0.0.0"
+tag_format = "${version}-library-foo" # the component name can be a prefix or suffix with or without a separator
+ignored_tag_formats = ["${version}-library-(?!foo$).*"] # Avoid noise from other tags
+update_changelog_on_bump = true
+```
 
-3. **Bump each component independently**
+```toml
+# library-alice/.cz.toml
+[tool.commitizen]
+name = "cz_customize"
+version = "0.0.0"
+tag_format = "${version}-library-alice"
+ignored_tag_formats = ["${version}-library-(?!alice$).*"] # Avoid noise from other tags
+update_changelog_on_bump = true
+```
 
-    ```sh
-    cz --config library-b/.cz.toml bump --yes
-    cz --config library-z/.cz.toml bump --yes
-    ```
+3. **Bump each component independently**
 
+```sh
+cz --config library-foo/.cz.toml bump --yes
+cz --config library-alice/.cz.toml bump --yes
+```
 
-## Changelog per component
+## Changelog Per Component
 
 To filter the correct commits for each component, you'll need to define a strategy.
 
 For example:
 
 - Trigger the pipeline based on the changed path. This can have some downsides, as you'll rely on the developer not including files from unrelated components.
-    - [GitHub Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore) uses `path`
-    - [Jenkins](https://www.jenkins.io/doc/book/pipeline/syntax/#built-in-conditions) uses `changeset`
-    - [GitLab](https://docs.gitlab.com/ee/ci/yaml/#ruleschanges) uses `rules:changes`
+  - [GitHub Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#onpushpull_requestpull_request_targetpathspaths-ignore) uses `path`
+  - [Jenkins](https://www.jenkins.io/doc/book/pipeline/syntax/#built-in-conditions) uses `changeset`
+  - [GitLab](https://docs.gitlab.com/ee/ci/yaml/#ruleschanges) uses `rules:changes`
 - Filter commits by a specific pattern in the commit message (recommended)
 
+### Filtering Commits
 
-### Example with scope in conventional commits
-
-In this example, we want `library-b`'s changelog to only include commits that use the `library-b` scope.
-To achieve this, we configure Commitizen to match only commit messages with that scope.
-
-Here is an example configuration for `library-b`:
-
-```toml
-[tool.commitizen.customize]
-changelog_pattern = "^(feat|fix)\\(library-b\\)(!)?:" # the type pattern can be a wildcard or any types you wish to include
-```
-
-With this configuration, a commit message like the following would be included in `library-b`'s changelog:
-
-```text
-fix(library-b): Some awesome message
-```
+For advanced use cases, filter the commits passed to `version`, `bump` or `changelog` by implementing custom conventional commit rules.
+See [Filter commits before bump and changelog generation](../customization/python_class.md#filter-commits-before-bump-and-changelog-generation)

tests/test_tags.py

@@ -1,3 +1,5 @@
+import pytest
+
 from commitizen.git import GitTag
 from commitizen.tags import TagRules
 
@@ -140,3 +142,81 @@ def test_is_version_tag_accepts_dotless_devrelease_in_custom_tag_format():
 
     extracted = rules.extract_version(_git_tag("version-1.2.3dev1"))
     assert str(extracted) == "1.2.3.dev1"
+
+
+def test_monorepo_ignored_tag_formats_keep_own_tags(capsys: pytest.CaptureFixture):
+    """Regression test for the monorepo workflow in
+    ``docs/tutorials/monorepo_guidance.md``.
+
+    Each component configures a suffixed ``tag_format`` and ignores sibling
+    component tags with a wildcard.
+
+    Ignoring sibling tags must not reject the component's own tags. Ignored
+    tags are expected noise, so they must not emit "Invalid version tag"
+    warnings; only truly unexpected tags warn.
+    """
+    library_foo_rules = TagRules(
+        tag_format="${version}-library-foo",
+        ignored_tag_formats=["${version}-library-(?!foo$).*"],
+    )
+    library_zoo_rules = TagRules(
+        tag_format="${version}-library-zoo",
+        ignored_tag_formats=["${version}-library-(?!zoo$).*"],
+    )
+
+    # Own tags remain version tags, sibling tags are filtered out.
+    assert library_foo_rules.is_version_tag("1.0.0-library-foo") is True
+    assert library_foo_rules.is_version_tag("1.0.0-library-zoo") is False
+
+    assert library_zoo_rules.is_version_tag("1.0.0-library-zoo") is True
+    assert library_zoo_rules.is_version_tag("1.0.0-library-foo") is False
+
+    # Check also for prefix
+    assert library_foo_rules.is_ignored_tag("1.0.0-library-foobar") is True
+
+    # The own tag is parseable, so a rejection above is a filtering problem,
+    # not a parsing one.
+    extracted = library_foo_rules.extract_version(_git_tag("1.0.0-library-foo"))
+    assert str(extracted) == "1.0.0"
+
+    # Ignored tags do not warn. Unknown tags still do.
+    library_foo_rules.is_version_tag("1.0.0-library-zoo", warn=True)
+    library_foo_rules.is_version_tag("unexpected-tag", warn=True)
+    captured = capsys.readouterr()
+    assert "1.0.0-library-zoo" not in captured.err
+    assert "unexpected-tag" in captured.err
+
+
+def test_monorepo_get_version_tags_filters_sibling_components(
+    capsys: pytest.CaptureFixture,
+):
+    """``get_version_tags`` keeps only the component's own tags when the
+    repository also contains sibling component tags, as configured in
+    ``docs/tutorials/monorepo_guidance.md``.
+
+    The changelog and the ``scm`` version provider use this filtering, so the
+    ignored wildcard must silence sibling tags without dropping this
+    component's own tags.
+    """
+    tags = [
+        _git_tag("1.0.0-library-b"),
+        _git_tag("1.0.0-library-z"),
+        _git_tag("1.1.0-library-b"),
+        _git_tag("unexpected-tag"),
+    ]
+    rules = TagRules(
+        tag_format="${version}-library-b",
+        ignored_tag_formats=["${version}-library-(?!b$).*"],
+    )
+
+    version_tags = rules.get_version_tags(tags, warn=True)
+
+    assert [t.name for t in version_tags] == [
+        "1.0.0-library-b",
+        "1.1.0-library-b",
+    ]
+
+    # Only the truly unexpected tag warns; sibling tags are known noise.
+    captured = capsys.readouterr()
+    assert "unexpected-tag" in captured.err
+    assert "1.0.0-library-z" not in captured.err