python-kacl 0.5.0__tar.gz → 0.6.0__tar.gz

{python_kacl-0.5.0/python_kacl.egg-info → python_kacl-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-kacl
-Version: 0.5.0
+Version: 0.6.0
 Summary: Python module and CLI tool for validating and modifying Changelogs in "keep-a-changelog" format"
 Home-page: https://gitlab.com/schmieder.matthias/python-kacl.git
 Author: Matthias Schmieder
@@ -8,16 +8,17 @@ Author-email: schmieder.matthias@gmail.com
 License: MIT
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.9
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Version Control
-Requires-Python: >=3.7
+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
 
 # python-kacl
 
@@ -44,6 +45,10 @@ A tool for verifying and modifying changelog in the [**K**eep-**A-C**hange-**L**
   - [Link Generation](#link-generation)
   - [Squashing releases](#squashing-releases)
     - [Example](#example)
+  - [Issue Management Integration](#issue-management-integration)
+    - [Adding Comments to Issues](#adding-comments-to-issues)
+    - [Command Options](#command-options)
+    - [Templating the Comment](#templating-the-comment)
   - [Extensions](#extensions)
     - [Post-release/Hotfix](#post-releasehotfix)
   - [Config file](#config-file)
@@ -483,6 +488,114 @@ kacl-cli -f CHANGELOG.md squash \
 
 This example will squash all versions between `0.0.1` and `1.0.0` and move them under `1.0.0`
 
+## Issue Management Integration
+
+With `python-kacl >= 0.6.0`, you can integrate changelog and release management directly into your Issue Management System. Currently, the supported system is JIRA.
+
+It is common practice to reference fixed or addressed issues in the changelog, as shown below:
+
+```markdown
+## Unreleased
+### Added
+- JIRA-1754 Just unreleased stuff
+
+## 1.0.0 - 2017-06-20
+### Added
+- JIRA-9: added UI functionality
+
+### Fixed
+- issue JIRA-13 closed by applying the solution
+```
+
+### Adding Comments to Issues
+
+The `add-comments` command allows you to detect issue IDs using a custom pattern and create comments in the Issue Tracking system about a new release.
+
+You can pass all necessary arguments via CLI or set up your `.kacl.yaml` configuration file. The following options are available:
+
+```yaml
+issue_tracker:
+  jira:
+    host: jira.atlassian.com # The host name of your JIRA instance
+    username: null # The username to login. Uses JIRA_USERNAME environment variable if available
+    password: null # The password to login. Uses JIRA_PASSWORD environment variable if available
+    issue_patterns: # List of regex patterns to identify the issues
+      - "[A-Z]+-[0-9]+"
+      - "JIRA-[0-9]+"
+    comment_template: | # A text template used to comment on the issue
+      # 🚀 New version [v{new_version}]({link})
+
+      A new release has been created referencing this issue. Please check it out.
+
+      ## 🚧 Changes in this version
+
+      {changes}
+
+      ## 🧭 Reference
+
+      Code: [Source Code Management System]({link})
+```
+
+Run the following command to create the comments:
+
+```bash
+kacl-cli add-comments 1.0.0
+```
+
+### Command Options
+
+See all available command options:
+
+```bash
+Usage: kacl-cli add-comments [OPTIONS] VERSION
+
+  Adds comments to issues identified within the CHANGELOG. Currently
+  supported system: JIRA
+
+Options:
+  --jira-username TEXT          JIRA username. Will also look for the
+                                JIRA_USERNAME environment variable.
+  --jira-password TEXT          JIRA password. Will also look for the
+                                JIRA_PASSWORD environment variable.
+  --jira-host TEXT              JIRA host. Will also look for the JIRA_HOST
+                                environment variable.
+  --jira-issue-pattern TEXT     Issue pattern to search the changelog for. Can
+                                be specified multiple times.
+  --jira-comment-template TEXT  JIRA comment template.
+  --fail                        Fail if comments could not be added.
+  --help                        Show this message and exit.
+```
+
+### Templating the Comment
+
+The `comment_template` parameter allows various templating options. The following template variables are available:
+
+| Variable       | Description                                                                                          |
+| -------------- | ---------------------------------------------------------------------------------------------------- |
+| `new_version`  | The version that was just released                                                                   |
+| `changes`      | The markdown content within the change section of your CHANGELOG                                     |
+| `link`         | The link to the version within your source code management system according to the link configuration |
+| `env.MYENVVAR` | Any environment variable                                                                             |
+
+This flexibility allows you to adapt the comment patterns to your needs and dynamically create them. For example, adding CI/CD information can be easily achieved as follows:
+
+```yaml
+comment_template: | # A text template used to comment on the issue
+    # 🚀 New version [v{new_version}]({link})
+
+    A new release has been created referencing this issue. Please check it out.
+
+    ## 🚧 Changes in this version
+
+    {changes}
+
+    ## 🧭 Reference
+
+    Code: [Source Code Management System]({link})
+    Pipeline: [Pipeline ({env.CI_PIPELINE_IID})]({env.CI_PIPELINE_URL})
+    GitLab Project: [({env.CI_PROJECT_TITLE})]({env.CI_PROJECT_URL})
+```
+
 ## Extensions
 
 ### Post-release/Hotfix
@@ -561,6 +674,24 @@ kacl:
       auto_generate: True
   extension:
     post_release_version_prefix: null
+  issue_tracker:
+    jira:
+      host: null
+      username: null
+      password: null
+      issue_patterns: ["[A-Z]+-[0-9]+"]
+      comment_template: |
+        # 🚀 New version [v{new_version}]({link})
+
+        A new release has been created referencing this issue. Please check it out.
+
+        ## 🚧 Changes in this version
+
+        {changes}
+
+        ## 🧭 Reference
+
+        Code: [Source Code Management System]({link})
 ```
 
 ## Development

{python_kacl-0.5.0 → python_kacl-0.6.0}/README.md

@@ -23,6 +23,10 @@ A tool for verifying and modifying changelog in the [**K**eep-**A-C**hange-**L**
   - [Link Generation](#link-generation)
   - [Squashing releases](#squashing-releases)
     - [Example](#example)
+  - [Issue Management Integration](#issue-management-integration)
+    - [Adding Comments to Issues](#adding-comments-to-issues)
+    - [Command Options](#command-options)
+    - [Templating the Comment](#templating-the-comment)
   - [Extensions](#extensions)
     - [Post-release/Hotfix](#post-releasehotfix)
   - [Config file](#config-file)
@@ -462,6 +466,114 @@ kacl-cli -f CHANGELOG.md squash \
 
 This example will squash all versions between `0.0.1` and `1.0.0` and move them under `1.0.0`
 
+## Issue Management Integration
+
+With `python-kacl >= 0.6.0`, you can integrate changelog and release management directly into your Issue Management System. Currently, the supported system is JIRA.
+
+It is common practice to reference fixed or addressed issues in the changelog, as shown below:
+
+```markdown
+## Unreleased
+### Added
+- JIRA-1754 Just unreleased stuff
+
+## 1.0.0 - 2017-06-20
+### Added
+- JIRA-9: added UI functionality
+
+### Fixed
+- issue JIRA-13 closed by applying the solution
+```
+
+### Adding Comments to Issues
+
+The `add-comments` command allows you to detect issue IDs using a custom pattern and create comments in the Issue Tracking system about a new release.
+
+You can pass all necessary arguments via CLI or set up your `.kacl.yaml` configuration file. The following options are available:
+
+```yaml
+issue_tracker:
+  jira:
+    host: jira.atlassian.com # The host name of your JIRA instance
+    username: null # The username to login. Uses JIRA_USERNAME environment variable if available
+    password: null # The password to login. Uses JIRA_PASSWORD environment variable if available
+    issue_patterns: # List of regex patterns to identify the issues
+      - "[A-Z]+-[0-9]+"
+      - "JIRA-[0-9]+"
+    comment_template: | # A text template used to comment on the issue
+      # 🚀 New version [v{new_version}]({link})
+
+      A new release has been created referencing this issue. Please check it out.
+
+      ## 🚧 Changes in this version
+
+      {changes}
+
+      ## 🧭 Reference
+
+      Code: [Source Code Management System]({link})
+```
+
+Run the following command to create the comments:
+
+```bash
+kacl-cli add-comments 1.0.0
+```
+
+### Command Options
+
+See all available command options:
+
+```bash
+Usage: kacl-cli add-comments [OPTIONS] VERSION
+
+  Adds comments to issues identified within the CHANGELOG. Currently
+  supported system: JIRA
+
+Options:
+  --jira-username TEXT          JIRA username. Will also look for the
+                                JIRA_USERNAME environment variable.
+  --jira-password TEXT          JIRA password. Will also look for the
+                                JIRA_PASSWORD environment variable.
+  --jira-host TEXT              JIRA host. Will also look for the JIRA_HOST
+                                environment variable.
+  --jira-issue-pattern TEXT     Issue pattern to search the changelog for. Can
+                                be specified multiple times.
+  --jira-comment-template TEXT  JIRA comment template.
+  --fail                        Fail if comments could not be added.
+  --help                        Show this message and exit.
+```
+
+### Templating the Comment
+
+The `comment_template` parameter allows various templating options. The following template variables are available:
+
+| Variable       | Description                                                                                          |
+| -------------- | ---------------------------------------------------------------------------------------------------- |
+| `new_version`  | The version that was just released                                                                   |
+| `changes`      | The markdown content within the change section of your CHANGELOG                                     |
+| `link`         | The link to the version within your source code management system according to the link configuration |
+| `env.MYENVVAR` | Any environment variable                                                                             |
+
+This flexibility allows you to adapt the comment patterns to your needs and dynamically create them. For example, adding CI/CD information can be easily achieved as follows:
+
+```yaml
+comment_template: | # A text template used to comment on the issue
+    # 🚀 New version [v{new_version}]({link})
+
+    A new release has been created referencing this issue. Please check it out.
+
+    ## 🚧 Changes in this version
+
+    {changes}
+
+    ## 🧭 Reference
+
+    Code: [Source Code Management System]({link})
+    Pipeline: [Pipeline ({env.CI_PIPELINE_IID})]({env.CI_PIPELINE_URL})
+    GitLab Project: [({env.CI_PROJECT_TITLE})]({env.CI_PROJECT_URL})
+```
+
 ## Extensions
 
 ### Post-release/Hotfix
@@ -540,6 +652,24 @@ kacl:
       auto_generate: True
   extension:
     post_release_version_prefix: null
+  issue_tracker:
+    jira:
+      host: null
+      username: null
+      password: null
+      issue_patterns: ["[A-Z]+-[0-9]+"]
+      comment_template: |
+        # 🚀 New version [v{new_version}]({link})
+
+        A new release has been created referencing this issue. Please check it out.
+
+        ## 🚧 Changes in this version
+
+        {changes}
+
+        ## 🧭 Reference
+
+        Code: [Source Code Management System]({link})
 ```
 
 ## Development

{python_kacl-0.5.0 → python_kacl-0.6.0}/kacl/__init__.py

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

{python_kacl-0.5.0 → python_kacl-0.6.0}/kacl/config/kacl-default.yml

@@ -26,4 +26,23 @@ kacl:
     unreleased_changes_template: '{host}/compare/{latest_version}...master'
     initial_version_template: '{host}/tree/{version}'
   extension:
-    post_release_version_prefix: null
+    post_release_version_prefix: null
+  issue_tracker:
+    jira:
+      host: null
+      username: null
+      password: null
+      issue_patterns: ["[A-Z]+-[0-9]+"]
+      comment_template: |
+        # 🚀 New version [v{new_version}]({link})
+
+        A new release has been created referencing this issue. Please check it out.
+
+        ## 🚧 Changes in this version
+
+        {changes}
+
+        ## 🧭 Reference
+
+        Code: [Source Code Management System]({link})
+

{python_kacl-0.5.0 → python_kacl-0.6.0}/kacl/config.py

@@ -44,6 +44,34 @@ class KACLConfig:
             "post_release_version_prefix"
         )
 
+        # issue tracker config
+        self.issue_tracker_jira_host = (
+            self.__config.get("issue_tracker", {}).get("jira", {}).get("host")
+        )
+        self.issue_tracker_jira_username = (
+            self.__config.get("issue_tracker", {}).get("jira", {}).get("username")
+        )
+        self.issue_tracker_jira_password = (
+            self.__config.get("issue_tracker", {}).get("jira", {}).get("password")
+        )
+        self.issue_tracker_jira_issue_patterns = (
+            self.__config.get("issue_tracker", {})
+            .get("jira", {})
+            .get("issue_patterns", [])
+        )
+        self.issue_tracker_jira_comment_template = (
+            self.__config.get("issue_tracker", {})
+            .get("jira", {})
+            .get("comment_template")
+        )
+
+        if not self.issue_tracker_jira_host:
+            self.issue_tracker_jira_host = os.getenv("JIRA_HOST", None)
+        if not self.issue_tracker_jira_username:
+            self.issue_tracker_jira_username = os.getenv("JIRA_USERNAME", None)
+        if not self.issue_tracker_jira_password:
+            self.issue_tracker_jira_password = os.getenv("JIRA_PASSWORD", None)
+
     @staticmethod
     def merge(a, b, path=None):
         """merge two dictionaries

{python_kacl-0.5.0 → python_kacl-0.6.0}/kacl/document.py

@@ -7,8 +7,12 @@ import semver
 from kacl.config import KACLConfig
 from kacl.element import KACLElement
 from kacl.exception import KACLException
+from kacl.jira_client import KACLJiraClient
 from kacl.link_provider import LinkProvider
 from kacl.parser import KACLParser
+from kacl.utils import convert_markdown_to_jira
+from kacl.utils import extract_issue_ids
+from kacl.utils import replace_env_variables
 from kacl.validation import KACLValidation
 from kacl.version import KACLVersion
 
@@ -293,10 +297,17 @@ class KACLDocument:
                     ):
                         comp_result = future_version.compare(last_version)
                     #   2.3 if 'last version' was NOT a 'post version' ensure 'post version' has same 'base version'
-                    elif future_version_base != last_version_base:
-                        comp_result = -1  # indicate error
                     else:
-                        comp_result = 1
+                        comp_result = future_version_base.compare(last_version_base)
+                        #  2.4 if 'last version' has same 'base version' as 'future version' this is ok, because we
+                        #  define post version as 'higher' than base version
+                        if comp_result == 0:
+                            comp_result = 1
+                elif (
+                    last_version.prerelease
+                    and post_release_version_prefix in last_version.prerelease
+                ):
+                    comp_result = future_version_base.compare(last_version_base)
                 else:
                     comp_result = future_version.compare(last_version)
             else:
@@ -354,7 +365,7 @@ class KACLDocument:
                             link_provider.initial_version(**fargs)
                         )
 
-    def get(self, version):
+    def get(self, version) -> KACLVersion:
         """Returns the selected version
 
         Arguments:
@@ -455,6 +466,74 @@ class KACLDocument:
             else:
                 versions[0].set_link(link_provider.initial_version(**fargs))
 
+    def get_associated_issues(self, version=None):
+        """returns all issues for the given version"""
+        kacl_version = None
+        if not version:
+            # if no version is given, we will use the current version
+            kacl_version = self.get(self.current_version())
+        else:
+            kacl_version = self.get(version)
+
+        patterns = {"jira": self.config.issue_tracker_jira_issue_patterns}
+
+        # get all issue ids
+        return extract_issue_ids(kacl_version, patterns)
+
+    def render_comments(self, version=None) -> dict[str:str]:
+        if version is None:
+            version = self.current_version()
+
+        changes = self.get(version)
+        link_provider = self.__get_link_provider()
+
+        format_string = {
+            "new_version": version,
+            "changes": changes.body(),
+            "link": link_provider.version_link(version),
+        }
+
+        comments = {}
+
+        if self.config.issue_tracker_jira_comment_template:
+            jira_comment = replace_env_variables(
+                self.config.issue_tracker_jira_comment_template
+            )
+            jira_comment = jira_comment.format(**format_string)
+            jira_comment = convert_markdown_to_jira(jira_comment)
+            comments["jira"] = jira_comment
+
+        return comments
+
+    def add_comments(self, version=None) -> dict[str : dict[str:bool]]:
+        # This function will parse all versions for known issue ids and search the defined
+        # issue tracking system for the issue. If the issue is found, a comment will be added to the
+        # issue with the changelog/release information
+
+        issue_ids = self.get_associated_issues(version)
+
+        jira_client = None
+        if "jira" in issue_ids and len(issue_ids["jira"]) > 0:
+            client = KACLJiraClient(self.config)
+            if client.is_authenticated():
+                jira_client = client
+
+        rendered_comments = self.render_comments(version)
+
+        report = {"jira": {}}
+
+        if jira_client:
+            # comment on jira tickets
+            for jira_issue in issue_ids["jira"]:
+                try:
+                    jira_client.add_comment(jira_issue, rendered_comments["jira"])
+                    report["jira"][jira_issue] = True
+                except Exception:
+                    report["jira"][jira_issue] = False
+                    continue
+
+        return report
+
     def header(self):
         """Gives access to the top level heading element
 

python_kacl-0.6.0/kacl/jira_client.py

@@ -0,0 +1,36 @@
+from jira import JIRA
+
+from kacl.config import KACLConfig
+
+
+class KACLJiraClient:
+    def __init__(self, config: KACLConfig):
+        self.config = config
+        self.client = JIRA(
+            server=config.issue_tracker_jira_host,
+            basic_auth=(
+                config.issue_tracker_jira_username,
+                config.issue_tracker_jira_password,
+            ),
+        )
+
+    def is_authenticated(self):
+        try:
+            # Attempt to fetch the current user as a way to check if authentication was successful
+            self.client.current_user()
+        except Exception:
+            return False
+        return True
+
+    def add_comment(self, issue_key, comment):
+        """
+        Adds a comment to a JIRA issue.
+
+        Args:
+            issue_key (str): The key of the issue to add the comment to.
+            comment (str): The text of the comment to add.
+
+        Returns:
+            None
+        """
+        self.client.add_comment(issue_key, comment)

{python_kacl-0.5.0 → python_kacl-0.6.0}/kacl/kacl_cli.py

@@ -611,6 +611,103 @@ def new(output_file):
         click.echo(kacl_changelog_content)
 
 
+@cli.command("add-comments")
+@click.pass_context
+@click.option(
+    "--jira-username",
+    required=False,
+    type=str,
+    default=os.getenv(
+        "JIRA_USERNAME",
+        None,
+    ),
+    help="JIRA username. Will also look for JIRA_USERNAME environment variable.",
+)
+@click.option(
+    "--jira-password",
+    required=False,
+    type=str,
+    default=os.getenv(
+        "JIRA_PASSWORD",
+        None,
+    ),
+    help="JIRA password. Will also look for JIRA_PASSWORD environment variable.",
+)
+@click.option(
+    "--jira-host",
+    required=False,
+    type=str,
+    default=os.getenv(
+        "JIRA_HOST",
+        None,
+    ),
+    help="JIRA host. Will also look for JIRA_HOST environment variable.",
+)
+@click.option(
+    "--jira-issue-pattern",
+    required=False,
+    multiple=True,
+    help="Issue pattern to search the changlog for. Can be specified multiple times.",
+)
+@click.option(
+    "--jira-comment-template",
+    required=False,
+    default=None,
+    type=str,
+    help="JIRA comment template.",
+)
+@click.option(
+    "--fail",
+    is_flag=True,
+    help="Will fail if comments could not be added.",
+)
+@click.argument("version", type=str)
+def add_comments(
+    ctx,
+    version,
+    jira_username,
+    jira_password,
+    jira_host,
+    jira_issue_pattern,
+    jira_comment_template,
+    fail,
+):
+    """Will add comments to issues identified within the CHANGELOG. Currently supported systems are: [JIRA]"""
+    kacl_changelog = load_changelog(ctx)
+    kacl_config = kacl_changelog.config
+
+    if jira_host:
+        kacl_config.issue_tracker_jira_host = jira_host
+    if jira_username:
+        kacl_config.issue_tracker_jira_username = jira_username
+    if jira_password:
+        kacl_config.issue_tracker_jira_password = jira_password
+    if jira_issue_pattern:
+        kacl_config.issue_tracker_jira_issue_patterns = list(jira_issue_pattern)
+    if jira_comment_template:
+        kacl_config.issue_tracker_jira_comment_template = jira_comment_template
+
+    raise_on_invalid(kacl_changelog)
+
+    issues = kacl_changelog.get_associated_issues(version)
+    for issue_type in issues.keys():
+        click.secho(f"Found {len(issues[issue_type])} '{issue_type}' issues", fg="blue")
+        for issue in issues[issue_type]:
+            click.secho(f"{issue_type}: {issue}")
+
+    report = kacl_changelog.add_comments(version)
+
+    failed = False
+    for issue_type in report.keys():
+        for issue, success in report[issue_type].items():
+            if not success:
+                failed = True
+                click.secho(f"Failed to add comment to {issue_type}: {issue}", fg="red")
+
+    if fail and failed:
+        sys.exit(1)
+
+
 def start():
     try:
         cli(obj={})

{python_kacl-0.5.0 → python_kacl-0.6.0}/kacl/link_provider.py

@@ -49,3 +49,8 @@ class LinkProvider:
             previous_version=previous_version,
             latest_version=latest_version,
         )
+
+    def version_link(self, version=None, previous_version=None, latest_version=None):
+        return self.initial_version(
+            version=version, previous_version=version, latest_version=version
+        )

python_kacl-0.6.0/kacl/utils.py

@@ -0,0 +1,71 @@
+import os
+import re
+
+from kacl.version import KACLVersion
+
+
+def extract_issue_ids(
+    version: KACLVersion,
+    search_patterns: dict[str : list[str]] = {"jira": [r"[A-Z]+-[0-9]+"]},
+) -> dict[str : list[str]]:
+    """
+    Extract JIRA IDs from a version object.
+
+    Args:
+        version (KACLVersion): The version object to extract JIRA IDs from.
+        search_patterns (list[str], optional): A list of search patterns to use. Defaults to ["[A-Z]+-[0-9]+"].
+
+    Returns:
+        list[str]: A list of JIRA IDs.
+    """
+    issue_ids = {}
+    for key in search_patterns.keys():
+        ids = []
+        for pattern in search_patterns[key]:
+            ids.extend(re.findall(pattern, (version.body())))
+        issue_ids[key] = ids
+    return issue_ids
+
+
+def replace_env_variables(text):
+    """
+    Parses a given text and replaces occurrences of {env.VAR} with the value of the environment
+    variable VAR if it exists, or with an empty string if it does not.
+
+    Args:
+        text (str): The text to parse and replace environment variables in.
+
+    Returns:
+        str: The text with environment variables replaced.
+    """
+    # Regular expression to find {env.VAR} patterns
+    pattern = re.compile(r"\{env\.([A-Za-z_][A-Za-z0-9_]*)\}")
+
+    # Function to replace each match
+    def replace_match(match):
+        # Extract the environment variable name from the match
+        env_var = match.group(1)
+        # Return the environment variable's value if it exists, else return an empty string
+        return os.getenv(env_var, "")
+
+    # Replace all occurrences of the pattern in the text
+    return pattern.sub(replace_match, text)
+
+
+def convert_markdown_to_jira(markdown_text):
+    # Convert markdown headings to JIRA headings
+    def replace_heading(match):
+        heading_level = len(match.group(1))
+        return f"h{heading_level}. {match.group(2)}"
+
+    # Convert markdown links to JIRA links
+    def replace_link(match):
+        link_text = match.group(1)
+        url = match.group(2)
+        return f"[{link_text}|{url}]"
+
+    converted_text = re.sub(
+        r"^(#{1,6})\s+(.*)", replace_heading, markdown_text, flags=re.MULTILINE
+    )
+    converted_text = re.sub(r"\[(.*?)\]\((.*?)\)", replace_link, converted_text)
+    return converted_text

{python_kacl-0.5.0 → python_kacl-0.6.0/python_kacl.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-kacl
-Version: 0.5.0
+Version: 0.6.0
 Summary: Python module and CLI tool for validating and modifying Changelogs in "keep-a-changelog" format"
 Home-page: https://gitlab.com/schmieder.matthias/python-kacl.git
 Author: Matthias Schmieder
@@ -8,16 +8,17 @@ Author-email: schmieder.matthias@gmail.com
 License: MIT
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.9
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Version Control
-Requires-Python: >=3.7
+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
 
 # python-kacl
 
@@ -44,6 +45,10 @@ A tool for verifying and modifying changelog in the [**K**eep-**A-C**hange-**L**
   - [Link Generation](#link-generation)
   - [Squashing releases](#squashing-releases)
     - [Example](#example)
+  - [Issue Management Integration](#issue-management-integration)
+    - [Adding Comments to Issues](#adding-comments-to-issues)
+    - [Command Options](#command-options)
+    - [Templating the Comment](#templating-the-comment)
   - [Extensions](#extensions)
     - [Post-release/Hotfix](#post-releasehotfix)
   - [Config file](#config-file)
@@ -483,6 +488,114 @@ kacl-cli -f CHANGELOG.md squash \
 
 This example will squash all versions between `0.0.1` and `1.0.0` and move them under `1.0.0`
 
+## Issue Management Integration
+
+With `python-kacl >= 0.6.0`, you can integrate changelog and release management directly into your Issue Management System. Currently, the supported system is JIRA.
+
+It is common practice to reference fixed or addressed issues in the changelog, as shown below:
+
+```markdown
+## Unreleased
+### Added
+- JIRA-1754 Just unreleased stuff
+
+## 1.0.0 - 2017-06-20
+### Added
+- JIRA-9: added UI functionality
+
+### Fixed
+- issue JIRA-13 closed by applying the solution
+```
+
+### Adding Comments to Issues
+
+The `add-comments` command allows you to detect issue IDs using a custom pattern and create comments in the Issue Tracking system about a new release.
+
+You can pass all necessary arguments via CLI or set up your `.kacl.yaml` configuration file. The following options are available:
+
+```yaml
+issue_tracker:
+  jira:
+    host: jira.atlassian.com # The host name of your JIRA instance
+    username: null # The username to login. Uses JIRA_USERNAME environment variable if available
+    password: null # The password to login. Uses JIRA_PASSWORD environment variable if available
+    issue_patterns: # List of regex patterns to identify the issues
+      - "[A-Z]+-[0-9]+"
+      - "JIRA-[0-9]+"
+    comment_template: | # A text template used to comment on the issue
+      # 🚀 New version [v{new_version}]({link})
+
+      A new release has been created referencing this issue. Please check it out.
+
+      ## 🚧 Changes in this version
+
+      {changes}
+
+      ## 🧭 Reference
+
+      Code: [Source Code Management System]({link})
+```
+
+Run the following command to create the comments:
+
+```bash
+kacl-cli add-comments 1.0.0
+```
+
+### Command Options
+
+See all available command options:
+
+```bash
+Usage: kacl-cli add-comments [OPTIONS] VERSION
+
+  Adds comments to issues identified within the CHANGELOG. Currently
+  supported system: JIRA
+
+Options:
+  --jira-username TEXT          JIRA username. Will also look for the
+                                JIRA_USERNAME environment variable.
+  --jira-password TEXT          JIRA password. Will also look for the
+                                JIRA_PASSWORD environment variable.
+  --jira-host TEXT              JIRA host. Will also look for the JIRA_HOST
+                                environment variable.
+  --jira-issue-pattern TEXT     Issue pattern to search the changelog for. Can
+                                be specified multiple times.
+  --jira-comment-template TEXT  JIRA comment template.
+  --fail                        Fail if comments could not be added.
+  --help                        Show this message and exit.
+```
+
+### Templating the Comment
+
+The `comment_template` parameter allows various templating options. The following template variables are available:
+
+| Variable       | Description                                                                                          |
+| -------------- | ---------------------------------------------------------------------------------------------------- |
+| `new_version`  | The version that was just released                                                                   |
+| `changes`      | The markdown content within the change section of your CHANGELOG                                     |
+| `link`         | The link to the version within your source code management system according to the link configuration |
+| `env.MYENVVAR` | Any environment variable                                                                             |
+
+This flexibility allows you to adapt the comment patterns to your needs and dynamically create them. For example, adding CI/CD information can be easily achieved as follows:
+
+```yaml
+comment_template: | # A text template used to comment on the issue
+    # 🚀 New version [v{new_version}]({link})
+
+    A new release has been created referencing this issue. Please check it out.
+
+    ## 🚧 Changes in this version
+
+    {changes}
+
+    ## 🧭 Reference
+
+    Code: [Source Code Management System]({link})
+    Pipeline: [Pipeline ({env.CI_PIPELINE_IID})]({env.CI_PIPELINE_URL})
+    GitLab Project: [({env.CI_PROJECT_TITLE})]({env.CI_PROJECT_URL})
+```
+
 ## Extensions
 
 ### Post-release/Hotfix
@@ -561,6 +674,24 @@ kacl:
       auto_generate: True
   extension:
     post_release_version_prefix: null
+  issue_tracker:
+    jira:
+      host: null
+      username: null
+      password: null
+      issue_patterns: ["[A-Z]+-[0-9]+"]
+      comment_template: |
+        # 🚀 New version [v{new_version}]({link})
+
+        A new release has been created referencing this issue. Please check it out.
+
+        ## 🚧 Changes in this version
+
+        {changes}
+
+        ## 🧭 Reference
+
+        Code: [Source Code Management System]({link})
 ```
 
 ## Development

{python_kacl-0.5.0 → python_kacl-0.6.0}/python_kacl.egg-info/SOURCES.txt

@@ -9,10 +9,12 @@ kacl/config.py
 kacl/document.py
 kacl/element.py
 kacl/exception.py
+kacl/jira_client.py
 kacl/kacl_cli.py
 kacl/link_provider.py
 kacl/parser.py
 kacl/serializer.py
+kacl/utils.py
 kacl/validation.py
 kacl/version.py
 kacl/config/kacl-default.yml

{python_kacl-0.5.0 → python_kacl-0.6.0}/python_kacl.egg-info/requires.txt

@@ -2,3 +2,4 @@ click
 semver
 gitpython
 pyyaml
+jira

{python_kacl-0.5.0 → python_kacl-0.6.0}/setup.py

@@ -11,7 +11,7 @@ this_directory = path.abspath(path.dirname(__file__))
 with open(path.join(this_directory, "README.md"), encoding="utf-8") as f:
     long_description = f.read()
 
-version = "0.5.0"
+version = "0.6.0"
 
 version = f"{version}{os.environ.get('PIP_VERSION_POSTFIX', '')}"
 
@@ -37,13 +37,13 @@ setup(
     license="MIT",
     packages=find_packages(),
     include_package_data=True,
-    python_requires=">=3.7",
+    python_requires=">=3.9",
     install_requires=requirements,
     zip_safe=False,
     classifiers=[
         "License :: OSI Approved :: MIT License",
         "Programming Language :: Python :: 3",
-        "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.9",
         "Intended Audience :: Developers",
         "Topic :: Software Development :: Version Control",
     ],

{python_kacl-0.5.0 → python_kacl-0.6.0}/tests/test_cli.py

@@ -2,6 +2,7 @@ import json
 import os
 import shutil
 
+import pytest
 from click.testing import CliRunner
 from freezegun import freeze_time
 
@@ -95,6 +96,128 @@ def test_release_patch(tmp_path, snapshot):
         snapshot_directory(snapshot=snapshot, directory_path=project_root_path)
 
 
+@freeze_time("2023-01-01")
+def test_release_post_bump(tmp_path, snapshot):
+    runner = CliRunner()
+    resources_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)), "data/")
+    changelog_file = os.path.join(resources_dir, "CHANGELOG_with_changes.md")
+
+    with runner.isolated_filesystem(temp_dir=tmp_path) as project_root_path:
+        shutil.copyfile(changelog_file, os.path.join(project_root_path, "CHANGELOG.md"))
+        result = runner.invoke(
+            cli,
+            [
+                "-c",
+                os.path.join(resources_dir, "extension-config.yml"),
+                "-f",
+                "CHANGELOG.md",
+                "release",
+                "post",
+                "-m",
+            ],
+            catch_exceptions=False,
+        )
+        assert result.exit_code == 0, result.output
+        snapshot_directory(snapshot=snapshot, directory_path=project_root_path)
+
+
+@freeze_time("2023-01-01")
+def test_release_post_manual(tmp_path, snapshot):
+    runner = CliRunner()
+    resources_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)), "data/")
+    changelog_file = os.path.join(resources_dir, "CHANGELOG_with_changes.md")
+
+    with runner.isolated_filesystem(temp_dir=tmp_path) as project_root_path:
+        shutil.copyfile(changelog_file, os.path.join(project_root_path, "CHANGELOG.md"))
+        result = runner.invoke(
+            cli,
+            [
+                "-c",
+                os.path.join(resources_dir, "extension-config.yml"),
+                "-f",
+                "CHANGELOG.md",
+                "release",
+                "2.0.0-hotfix.0",
+                "-m",
+            ],
+            catch_exceptions=False,
+        )
+        assert result.exit_code == 0, result.output
+        snapshot_directory(snapshot=snapshot, directory_path=project_root_path)
+
+
+@freeze_time("2023-01-01")
+def test_release_post_manual_fail(tmp_path, snapshot):
+    runner = CliRunner()
+    resources_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)), "data/")
+    changelog_file = os.path.join(resources_dir, "CHANGELOG_with_changes.md")
+
+    with runner.isolated_filesystem(temp_dir=tmp_path) as project_root_path:
+        shutil.copyfile(changelog_file, os.path.join(project_root_path, "CHANGELOG.md"))
+        result = runner.invoke(
+            cli,
+            [
+                "-c",
+                os.path.join(resources_dir, "extension-config.yml"),
+                "-f",
+                "CHANGELOG.md",
+                "release",
+                "0.5.0-hotfix.0",
+                "-m",
+            ],
+            catch_exceptions=True,
+        )
+        assert result.exit_code == 1, result.output
+
+
+@freeze_time("2023-01-01")
+def test_release_version_manual_fail_same_base_after_post(tmp_path, snapshot):
+    runner = CliRunner()
+    resources_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)), "data/")
+    changelog_file = os.path.join(resources_dir, "CHANGELOG_post_with_changes.md")
+
+    with runner.isolated_filesystem(temp_dir=tmp_path) as project_root_path:
+        shutil.copyfile(changelog_file, os.path.join(project_root_path, "CHANGELOG.md"))
+        result = runner.invoke(
+            cli,
+            [
+                "-c",
+                os.path.join(resources_dir, "extension-config.yml"),
+                "-f",
+                "CHANGELOG.md",
+                "release",
+                "1.0.0",
+                "-m",
+            ],
+            catch_exceptions=True,
+        )
+        assert result.exit_code == 1, result.output
+
+
+@freeze_time("2023-01-01")
+def test_release_post_manual_same_base(tmp_path, snapshot):
+    runner = CliRunner()
+    resources_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)), "data/")
+    changelog_file = os.path.join(resources_dir, "CHANGELOG_with_changes.md")
+
+    with runner.isolated_filesystem(temp_dir=tmp_path) as project_root_path:
+        shutil.copyfile(changelog_file, os.path.join(project_root_path, "CHANGELOG.md"))
+        result = runner.invoke(
+            cli,
+            [
+                "-c",
+                os.path.join(resources_dir, "extension-config.yml"),
+                "-f",
+                "CHANGELOG.md",
+                "release",
+                "1.0.0-post.0",
+                "-m",
+            ],
+            catch_exceptions=False,
+        )
+        assert result.exit_code == 0, result.output
+
+
 @freeze_time("2023-01-01")
 def test_release_minor(tmp_path, snapshot):
     runner = CliRunner()
@@ -253,3 +376,43 @@ def test_squash_current(tmp_path, snapshot):
         )
         assert result.exit_code == 0, result.output
         snapshot_directory(snapshot=snapshot, directory_path=project_root_path)
+
+
+@pytest.mark.skip(reason="No issue tracker openly available, test locally.")
+def test_add_comments(tmp_path):
+    runner = CliRunner()
+    root_dir = os.path.join(
+        os.path.dirname(os.path.realpath(__file__)),
+        "..",
+    )
+    resources_dir = os.path.join(os.path.dirname(os.path.realpath(__file__)), "data/")
+    changelog_file = os.path.join(resources_dir, "CHANGELOG_issue_management.md")
+
+    with runner.isolated_filesystem(temp_dir=tmp_path) as project_root_path:
+        shutil.copyfile(changelog_file, os.path.join(project_root_path, "CHANGELOG.md"))
+        shutil.copytree(
+            os.path.join(root_dir, ".git"), os.path.join(project_root_path, ".git")
+        )
+        result = runner.invoke(
+            cli,
+            [
+                "-f",
+                "CHANGELOG.md",
+                "add-comments",
+                "1.0.0",
+                "--jira-username",
+                os.getenv("JIRA_USERNAME"),
+                "--jira-password",
+                os.getenv("JIRA_PASSWORD"),
+                "--jira-host",
+                os.getenv("JIRA_HOST"),
+                "--jira-issue-pattern",
+                "JIRA-[0-9]+",
+                "--jira-issue-pattern",
+                "MYJIRA-[0-9]+",
+                "--jira-issue-pattern",
+                "[A-Z]+-[0-9]+",
+            ],
+            catch_exceptions=False,
+        )
+        assert result.exit_code == 0, result.output

{python_kacl-0.5.0 → python_kacl-0.6.0}/tests/test_kacl.py

@@ -1,6 +1,7 @@
 import os
 from unittest import TestCase
 
+import pytest
 import yaml
 
 import kacl
@@ -406,3 +407,40 @@ def test_squash(tmp_path, snapshot):
         f.write(kacl.dump(changelog))
 
     snapshot_directory(snapshot=snapshot, directory_path=tmp_path)
+
+
+@pytest.mark.skip(reason="No issue tracker openly available, test locally.")
+def test_issue_tracker_comment(tmp_path):
+    changelog_file = os.path.join(
+        os.path.dirname(os.path.realpath(__file__)),
+        "data/CHANGELOG_issue_management.md",
+    )
+    changelog = kacl.load(changelog_file)
+    assert changelog.is_valid()
+
+    changelog.add_comments(version=changelog.current_version())
+
+
+def test_render_comments(tmp_path):
+    changelog_file = os.path.join(
+        os.path.dirname(os.path.realpath(__file__)),
+        "data/CHANGELOG_issue_management.md",
+    )
+    changelog = kacl.load(changelog_file)
+    assert changelog.is_valid()
+
+    rendered_comments = changelog.render_comments(version=changelog.current_version())
+
+    assert "jira" in rendered_comments
+
+
+def test_get_issues(tmp_path):
+    changelog_file = os.path.join(
+        os.path.dirname(os.path.realpath(__file__)),
+        "data/CHANGELOG_issue_management.md",
+    )
+    changelog = kacl.load(changelog_file)
+    assert changelog.is_valid()
+
+    issues = changelog.get_associated_issues(version=changelog.current_version())
+    assert len(issues["jira"]) == 5