python-kacl 0.7.6__tar.gz → 0.7.7__tar.gz

{python_kacl-0.7.6 → python_kacl-0.7.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-kacl
-Version: 0.7.6
+Version: 0.7.7
 Summary: Python module and CLI tool for validating and modifying Changelogs in "keep-a-changelog" format"
 Author-email: Matthias Schmieder <schmieder.matthias@gmail.com>
 License: MIT
@@ -56,6 +56,7 @@ A tool for verifying and modifying changelog in the [**K**eep-**A-C**hange-**L**
     - [Workflow Integration](#workflow-integration)
     - [Benefits](#benefits)
   - [Link Generation](#link-generation)
+    - [Custom Link References](#custom-link-references)
   - [Squashing releases](#squashing-releases)
     - [Example](#example)
   - [Issue Management Integration](#issue-management-integration)
@@ -778,6 +779,25 @@ kacl:
 
 Using the python format syntax you can generate any links you want. The available replacement variables are `version`, `previous_version`, `host` and `latest_version`.
 
+### Custom Link References
+
+Besides version links, you can use your own link references in changelog entries, for example to link to merge requests or issues. A reference is accepted as long as `[label]` is used in at least one entry:
+
+```markdown
+## [1.0.0] - 2026-04-10
+
+### Changed
+
+- a big change ([!1234])
+
+[1.0.0]: https://gitlab.com/my/repo/-/tags/v1.0.0
+[!1234]: https://gitlab.com/my/repo/-/merge_requests/1234
+```
+
+- `kacl-cli verify` reports references that are never used with `Link not referenced anywhere in the document`.
+- Custom references are preserved when `kacl-cli` rewrites the changelog (`add`, `release`, ...). They are written after the version links.
+- `kacl-cli squash` removes the references of the squashed versions.
+
 ## Squashing releases
 
 If you are follwing a automated versioning approach, you will often times create a number of versions that might clutter Changelog. For this purpose, `kacl-cli` provides a `squash` command that let's you squash releases into a single one without loosing valuable information.

python_kacl-0.7.6/python_kacl.egg-info/PKG-INFO → python_kacl-0.7.7/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.4
-Name: python-kacl
-Version: 0.7.6
-Summary: Python module and CLI tool for validating and modifying Changelogs in "keep-a-changelog" format"
-Author-email: Matthias Schmieder <schmieder.matthias@gmail.com>
-License: MIT
-Project-URL: Homepage, https://gitlab.com/schmieder.matthias/python-kacl.git
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Version Control
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: click
-Requires-Dist: semver
-Requires-Dist: gitpython
-Requires-Dist: pyyaml
-Requires-Dist: jira
-Dynamic: license-file
-
 # python-kacl
 
 [![Build Status](https://gitlab.com/schmieder.matthias/python-kacl/badges/main/pipeline.svg?ignore_skipped=true)](https://gitlab.com/schmieder.matthias/python-kacl)
@@ -56,6 +34,7 @@ A tool for verifying and modifying changelog in the [**K**eep-**A-C**hange-**L**
     - [Workflow Integration](#workflow-integration)
     - [Benefits](#benefits)
   - [Link Generation](#link-generation)
+    - [Custom Link References](#custom-link-references)
   - [Squashing releases](#squashing-releases)
     - [Example](#example)
   - [Issue Management Integration](#issue-management-integration)
@@ -778,6 +757,25 @@ kacl:
 
 Using the python format syntax you can generate any links you want. The available replacement variables are `version`, `previous_version`, `host` and `latest_version`.
 
+### Custom Link References
+
+Besides version links, you can use your own link references in changelog entries, for example to link to merge requests or issues. A reference is accepted as long as `[label]` is used in at least one entry:
+
+```markdown
+## [1.0.0] - 2026-04-10
+
+### Changed
+
+- a big change ([!1234])
+
+[1.0.0]: https://gitlab.com/my/repo/-/tags/v1.0.0
+[!1234]: https://gitlab.com/my/repo/-/merge_requests/1234
+```
+
+- `kacl-cli verify` reports references that are never used with `Link not referenced anywhere in the document`.
+- Custom references are preserved when `kacl-cli` rewrites the changelog (`add`, `release`, ...). They are written after the version links.
+- `kacl-cli squash` removes the references of the squashed versions.
+
 ## Squashing releases
 
 If you are follwing a automated versioning approach, you will often times create a number of versions that might clutter Changelog. For this purpose, `kacl-cli` provides a `squash` command that let's you squash releases into a single one without loosing valuable information.

{python_kacl-0.7.6 → python_kacl-0.7.7}/kacl/__init__.py

@@ -1,5 +1,5 @@
 # Version of the python-kacl package
-__version__ = "0.7.6"
+__version__ = "0.7.7"
 
 from kacl.document import KACLDocument
 from kacl.serializer import KACLMarkdownSerializer

{python_kacl-0.7.6 → python_kacl-0.7.7}/kacl/document.py

@@ -229,10 +229,11 @@ class KACLDocument:
                 pass
 
         # 4 link references
-        # 4.1 check that there are only linked references
-        version_strings = [v.version().lower() for v in versions]
-        for v, link in self.__link_references.items():
-            if v.lower() not in version_strings:
+        # 4.1 check that every reference is either a version link or is used
+        # inside of the changelog (e.g. "[!1234]" pointing to a merge request)
+        content = self._referencable_content().lower()
+        for link in self.extra_link_references():
+            if f"[{link.title().lower()}]" not in content:
                 validation.add_error(
                     line=link.raw(),
                     line_number=link.line_number(),
@@ -243,6 +244,27 @@ class KACLDocument:
 
         return validation
 
+    def extra_link_references(self):
+        """Returns all link references that do not belong to a version."""
+        version_strings = [v.version().lower() for v in self.__versions]
+        return [
+            link
+            for label, link in self.__link_references.items()
+            if label.lower() not in version_strings
+        ]
+
+    def _referencable_content(self):
+        """Returns the text of all versions in which link references can be used."""
+        parts = []
+        for v in self.__versions:
+            parts.append(v.body() or "")
+            try:
+                for changes in v.sections().values():
+                    parts.extend(changes.items())
+            except ValueError:
+                pass
+        return "\n".join(parts)
+
     def is_valid(self):
         """Checks if the current changelog is valid
         Returns:
@@ -289,6 +311,8 @@ class KACLDocument:
                         else:
                             change = f"[{v.version()}] {change}"
                     squash_version.add(section, change)
+            # the squashed version is gone, so is its link reference
+            self.__link_references.pop(v.version().lower(), None)
 
         versions_unsquashed.append(squash_version)
         versions_unsquashed.sort(reverse=True)

{python_kacl-0.7.6 → python_kacl-0.7.7}/kacl/serializer.py

@@ -30,6 +30,10 @@ class KACLMarkdownSerializer:
                 if version.has_link_reference():
                     link_references.append(self.__serialize_link_reference(version))
 
+            # keep references that do not belong to a version (e.g. merge requests)
+            for link in document.extra_link_references():
+                link_references.append(f"[{link.title()}]: {link.body()}")
+
         elif isinstance(document, KACLVersion):
             data.extend([self.__serialize_version(document), ""])
 

{python_kacl-0.7.6 → python_kacl-0.7.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-kacl"
-version = "0.7.6"
+version = "0.7.7"
 description = "Python module and CLI tool for validating and modifying Changelogs in \"keep-a-changelog\" format\""
 readme = "README.md"
 requires-python = ">=3.9"

python_kacl-0.7.6/README.md → python_kacl-0.7.7/python_kacl.egg-info/PKG-INFO

@@ -1,3 +1,25 @@
+Metadata-Version: 2.4
+Name: python-kacl
+Version: 0.7.7
+Summary: Python module and CLI tool for validating and modifying Changelogs in "keep-a-changelog" format"
+Author-email: Matthias Schmieder <schmieder.matthias@gmail.com>
+License: MIT
+Project-URL: Homepage, https://gitlab.com/schmieder.matthias/python-kacl.git
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Version Control
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click
+Requires-Dist: semver
+Requires-Dist: gitpython
+Requires-Dist: pyyaml
+Requires-Dist: jira
+Dynamic: license-file
+
 # python-kacl
 
 [![Build Status](https://gitlab.com/schmieder.matthias/python-kacl/badges/main/pipeline.svg?ignore_skipped=true)](https://gitlab.com/schmieder.matthias/python-kacl)
@@ -34,6 +56,7 @@ A tool for verifying and modifying changelog in the [**K**eep-**A-C**hange-**L**
     - [Workflow Integration](#workflow-integration)
     - [Benefits](#benefits)
   - [Link Generation](#link-generation)
+    - [Custom Link References](#custom-link-references)
   - [Squashing releases](#squashing-releases)
     - [Example](#example)
   - [Issue Management Integration](#issue-management-integration)
@@ -756,6 +779,25 @@ kacl:
 
 Using the python format syntax you can generate any links you want. The available replacement variables are `version`, `previous_version`, `host` and `latest_version`.
 
+### Custom Link References
+
+Besides version links, you can use your own link references in changelog entries, for example to link to merge requests or issues. A reference is accepted as long as `[label]` is used in at least one entry:
+
+```markdown
+## [1.0.0] - 2026-04-10
+
+### Changed
+
+- a big change ([!1234])
+
+[1.0.0]: https://gitlab.com/my/repo/-/tags/v1.0.0
+[!1234]: https://gitlab.com/my/repo/-/merge_requests/1234
+```
+
+- `kacl-cli verify` reports references that are never used with `Link not referenced anywhere in the document`.
+- Custom references are preserved when `kacl-cli` rewrites the changelog (`add`, `release`, ...). They are written after the version links.
+- `kacl-cli squash` removes the references of the squashed versions.
+
 ## Squashing releases
 
 If you are follwing a automated versioning approach, you will often times create a number of versions that might clutter Changelog. For this purpose, `kacl-cli` provides a `squash` command that let's you squash releases into a single one without loosing valuable information.

{python_kacl-0.7.6 → python_kacl-0.7.7}/tests/test_cli_workflow.py

@@ -223,3 +223,30 @@ def test_release_with_nested_stash_directory(tmp_path):
         )
         assert result.exit_code == 0, result.output
         assert os.listdir(stash_dir) == []
+
+
+def test_non_version_link_reference_survives_release(tmp_path):
+    runner = CliRunner()
+    changelog = (
+        "# Changelog\n\n"
+        "All notable changes to this project will be documented in this file.\n\n"
+        "The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), "
+        "and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n"
+        "## [Unreleased]\n\n"
+        "### Changed\n\n"
+        "- a big change ([!1234])\n\n"
+        "[Unreleased]: https://gitlab.com/my/repo/-/compare/v0.9.0...HEAD\n"
+        "[!1234]: https://gitlab.com/my/repo/-/merge_requests/1234\n"
+    )
+    with runner.isolated_filesystem(temp_dir=tmp_path):
+        with open("CHANGELOG.md", "w") as f:
+            f.write(changelog)
+        result = runner.invoke(
+            cli,
+            ["-f", "CHANGELOG.md", "release", "1.0.0", "-m", "--no-commit"],
+            catch_exceptions=False,
+        )
+        assert result.exit_code == 0, result.output
+        with open("CHANGELOG.md") as f:
+            content = f.read()
+        assert "[!1234]: https://gitlab.com/my/repo/-/merge_requests/1234" in content

{python_kacl-0.7.6 → python_kacl-0.7.7}/tests/test_kacl.py

@@ -680,3 +680,28 @@ def test_validate_reports_every_duplicated_section():
         (17, "### Added"),
         (21, "### Changed"),
     ]
+
+
+MR_CHANGELOG = (
+    "# Changelog\n\n"
+    "All notable changes to this project will be documented in this file.\n\n"
+    "The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), "
+    "and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n"
+    "## [1.0.0] - 2026-04-10\n\n"
+    "### Changed\n\n"
+    "- a big change ([!1234])\n\n"
+    "[1.0.0]: https://gitlab.com/my/repo/-/tags/v1.0.0\n"
+    "[!1234]: https://gitlab.com/my/repo/-/merge_requests/1234\n"
+)
+
+
+def test_used_non_version_link_reference_is_valid_and_preserved():
+    changelog = kacl.parse(MR_CHANGELOG)
+    assert changelog.is_valid()
+    assert kacl.dump(changelog) == MR_CHANGELOG
+
+
+def test_unused_non_version_link_reference_is_invalid():
+    changelog = kacl.parse(MR_CHANGELOG.replace(" ([!1234])", ""))
+    errors = [e.error_message() for e in changelog.validate().errors()]
+    assert errors == ["Link not referenced anywhere in the document"]