python-kacl 0.6.5__py3-none-any.whl → 0.6.7__py3-none-any.whl

kacl/__init__.py

@@ -1,5 +1,5 @@
 # Version of the python-kacl package
-__version__ = "0.6.5"
+__version__ = "0.6.7"
 
 from kacl.document import KACLDocument
 from kacl.serializer import KACLMarkdownSerializer
@@ -14,14 +14,14 @@ def load(file):
     with open(file, "r") as f:
         document = f.read()
         try:
-            doc = KACLDocument.parse(document)
+            doc = KACLDocument.parse(document, file)
         finally:
             f.close()
     return doc
 
 
-def parse(text):
-    return KACLDocument.parse(text)
+def parse(text, file=None):
+    return KACLDocument.parse(text, file)
 
 
 def dump(document):

kacl/changes.py

@@ -11,6 +11,8 @@ class KACLChanges(KACLElement):
             line_number=element.line_number(),
         )
         self.__items = []
+        # initializes
+        self.items()
 
     def items(self):
         if not len(self.__items) and len(self.body().strip()):

kacl/config/kacl-default.yml

@@ -13,6 +13,8 @@ kacl:
   default_content:
     - All notable changes to this project will be documented in this file.
     - 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).
+  release:
+    add_unreleased: True
   git:
     commit: False
     commit_message: "[skip ci] Releasing Changelog version {new_version}"
@@ -45,4 +47,6 @@ kacl:
         ## 🧭 Reference
 
         Code: [Source Code Management System]({link})
-
+  stash:
+    directory: .kacl_stash
+    always: False

kacl/config.py

@@ -20,6 +20,9 @@ class KACLConfig:
         self.allowed_header_titles = self.__config.get("allowed_header_titles")
         self.allowed_version_sections = self.__config.get("allowed_version_sections")
         self.default_content = self.__config.get("default_content")
+        self.add_unreleased = self.__config.get("release", {}).get(
+            "add_unreleased", True
+        )
         self.git_tag_name = self.__config.get("git", {}).get("tag_name")
         self.git_tag_description = self.__config.get("git", {}).get("tag_description")
         self.changelog_file_path = self.__config.get("file")
@@ -72,6 +75,9 @@ class KACLConfig:
         if not self.issue_tracker_jira_password:
             self.issue_tracker_jira_password = os.getenv("JIRA_PASSWORD", None)
 
+        self.stash_dir = self.__config.get("stash", {}).get("dir", ".kacl_stash")
+        self.stash_always = self.__config.get("stash", {}).get("always", False)
+
     @staticmethod
     def merge(a, b, path=None):
         """merge two dictionaries

kacl/document.py

@@ -4,6 +4,7 @@ import os
 import git
 import semver
 
+import kacl
 from kacl.config import KACLConfig
 from kacl.element import KACLElement
 from kacl.exception import KACLException
@@ -28,6 +29,7 @@ class KACLDocument:
         versions=None,
         link_references=None,
         meta_data=None,
+        file_path=None,
         config=KACLConfig(),
     ):
         self.__data = data
@@ -38,6 +40,80 @@ class KACLDocument:
             self.__link_references = dict()
         self.__meta_data = meta_data
         self.config = config
+        self.stash = []
+        self.file_path = file_path
+
+    @property
+    def stash_directory(self):
+        return self._ensure_stash_directory()
+
+    def load_stash(self):
+        self._refresh_stash()
+        # get all unreleased changes from stash
+        for stashed_changelog in self.stash:
+            unreleased_stash_version = stashed_changelog.get("Unreleased")
+            for title, change in unreleased_stash_version.sections().items():
+                for change_item in change.items():
+                    self.add(section=title, data=change_item)
+
+    def _refresh_stash(self):
+        if not self.file_path:
+            return
+
+        self.stash = []
+        if self.file_path is None:
+            local_stash_dir = os.path.join(
+                os.path.abspath(os.getcwd()), self.config.stash_dir
+            )
+        else:
+            # the stash needs always to be relative to the current file_path
+            local_stash_dir = os.path.join(
+                os.path.abspath(os.path.dirname(self.file_path)), self.config.stash_dir
+            )
+
+        if not os.path.isdir(local_stash_dir):
+            return
+
+        # read all md files in the stash directory
+        for f in os.listdir(local_stash_dir):
+            if f.endswith(".md"):
+                md_file = os.path.join(local_stash_dir, f)
+                with open(md_file, "r") as fh:
+                    data = fh.read()
+                    try:
+                        doc = KACLDocument.parse(data, None)
+                        self.stash.append(doc)
+                    except Exception:
+                        continue
+
+    def _ensure_stash_directory(self):
+        # the stash needs always to be relative to the current file_path
+        local_stash_dir = os.path.join(
+            os.path.abspath(os.path.dirname(self.file_path)), self.config.stash_dir
+        )
+
+        if not os.path.isdir(local_stash_dir):
+            os.makedirs(local_stash_dir, exist_ok=True)
+
+        return local_stash_dir
+
+    def _get_stash_file(self):
+        # the stash file should be named after the current git branch
+        local_stash_dir = self._ensure_stash_directory()
+        try:
+            repo = git.Repo(
+                os.path.abspath(os.path.dirname(self.file_path)),
+                search_parent_directories=True,
+            )
+            branch_name = repo.active_branch.name
+            # sanitize branch name for filename
+            branch_name = branch_name.replace("/", "__").replace("\\", "_")
+            stash_file_name = f"{branch_name}.md"
+        except Exception:
+            # fallback to with date
+            stash_file_name = f"{datetime.datetime.now().strftime('%Y%m%d')}.md"
+
+        return os.path.join(local_stash_dir, stash_file_name)
 
     def validate(self):
         """Validates the current changelog and returns KACLValidation object containing all information
@@ -46,6 +122,14 @@ class KACLDocument:
             [KACLValidation] -- object holding all error information
         """
         validation = KACLValidation()
+
+        # first load the stash
+        self._refresh_stash()
+        for stashed_changelog in self.stash:
+            val = stashed_changelog.validate()
+            for e in val.errors():
+                validation.add(e)
+
         # 1. assert only one header and starts on first line
         if len(self.__headers) == 0:
             validation.add_error(
@@ -213,18 +297,38 @@ class KACLDocument:
 
         return False
 
-    def add(self, section, data):
+    def add(self, section, data, stash=False):
         """adds a new change to a given section in the 'unreleased' version
 
         Arguments:
             section {[str]} -- section to add data to
             data {[str]} -- change information
+            stash {[bool]} -- if true the change will be stashed instead of added to the changelog (default: {False})
         """
-        unreleased_version = self.get("Unreleased")
-        if unreleased_version is None:
-            unreleased_version = KACLVersion(version="Unreleased")
-            self.__versions.insert(0, unreleased_version)
-        unreleased_version.add(section.capitalize(), data)
+
+        if stash:
+            # check if the stash directory already contains the required changelog file, if not initialize it
+            stash_file = self._get_stash_file()
+
+            if not os.path.exists(stash_file):
+                kacl_changelog = kacl.new()
+                kacl_changelog_content = kacl.dump(kacl_changelog)
+                with open(stash_file, "w") as f:
+                    f.write(kacl_changelog_content)
+                f.close()
+
+            kacl_changelog = kacl.load(stash_file)
+            kacl_changelog.add(section.capitalize(), data)
+            kacl_changelog_content = kacl.dump(kacl_changelog)
+            with open(stash_file, "w") as f:
+                f.write(kacl_changelog_content)
+            f.close()
+        else:
+            unreleased_version = self.get("Unreleased")
+            if unreleased_version is None:
+                unreleased_version = KACLVersion(version="Unreleased")
+                self.__versions.insert(0, unreleased_version)
+            unreleased_version.add(section.capitalize(), data)
 
     def release(
         self,
@@ -326,13 +430,9 @@ class KACLDocument:
         # remove current unrelease version from list
         self.__versions.pop(0)
 
-        self.__versions.insert(
-            0, KACLVersion(version="Unreleased", link=unreleased_version.link())
-        )
-
         # convert unreleased version to version
         self.__versions.insert(
-            1,
+            0,
             KACLVersion(
                 version=version,
                 link=KACLElement(title=version, body=link),
@@ -341,6 +441,11 @@ class KACLDocument:
             ),
         )
 
+        if self.config.add_unreleased:
+            self.__versions.insert(
+                0, KACLVersion(version="Unreleased", link=unreleased_version.link())
+            )
+
         if auto_link:
             link_provider = self.__get_link_provider()
             for i in range(2):
@@ -584,7 +689,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
         )
 
     @staticmethod
-    def parse(data):
+    def parse(data, file=None):
         """Parses a given text object and returns the KACLDocument
 
         Arguments:
@@ -624,6 +729,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
             versions=versions,
             link_references=link_references,
             meta_data=meta_data,
+            file_path=file,
         )
 
     def __get_link_provider(

kacl/kacl_cli.py

@@ -69,6 +69,7 @@ def load_changelog(ctx):
     # read the changelog
     kacl_changelog = kacl.load(kacl_config.changelog_file_path)
     kacl_changelog.config = kacl_config
+    kacl_changelog.load_stash()
 
     # share the objects
     return kacl_changelog
@@ -128,17 +129,32 @@ def cli(ctx, version=None, config=None, file=None):
     is_flag=True,
     help="This option will add the changes directly into changelog file.",
 )
-def add(ctx, section, message, modify):
+@click.option(
+    "-s",
+    "--stash",
+    is_flag=True,
+    help="This option will stash changes instead of applying them.",
+)
+def add(ctx, section, message, modify, stash):
     """Adds a given message to a specified unreleased section. Use '--modify' to directly modify the changelog file."""
     kacl_changelog = load_changelog(ctx)
 
+    if not modify:
+        stash = False
+    else:
+        # check if we need to stash
+        stash = stash or kacl_changelog.config.stash_always
+
     # add changes to changelog
-    kacl_changelog.add(section=section, data=message)
+    kacl_changelog.add(section=section, data=message, stash=stash)
+
     kacl_changelog_content = kacl.dump(kacl_changelog)
+    # if stashing is enabled, do not modify the changelog file
     if modify:
-        with open(kacl_changelog.config.changelog_file_path, "w") as f:
-            f.write(kacl_changelog_content)
-        f.close()
+        if not stash:
+            with open(kacl_changelog.config.changelog_file_path, "w") as f:
+                f.write(kacl_changelog_content)
+            f.close()
     else:
         click.echo(kacl_changelog_content)
 
@@ -472,6 +488,13 @@ def release(
         if no_commit:
             return
 
+        # delete all file in the stash directory
+        stash_files = []
+        for f in os.listdir(kacl_changelog.stash_directory):
+            stash_file = os.path.join(kacl_changelog.stash_directory, f)
+            os.remove(stash_file)
+            stash_files.append(stash_file)
+
         if commit or tag or kacl_config.git_create_commit or kacl_config.git_create_tag:
             vcs_context = {
                 "latest_version": latest_version,
@@ -516,6 +539,11 @@ def release(
                     repo.git.add(kacl_config.changelog_file_path)
                     for f in kacl_config.git_commit_additional_files:
                         repo.git.add(f)
+                    for f in stash_files:
+                        try:
+                            repo.git.add(f)
+                        except git.GitCommandError:
+                            pass
                     repo.git.commit("-m", commit_message.format(**vcs_context))
 
                 if tag or kacl_config.git_create_tag:
@@ -618,6 +646,52 @@ def new(output_file):
         click.echo(kacl_changelog_content)
 
 
+@cli.command()
+@click.option(
+    "-f",
+    "--force",
+    required=False,
+    is_flag=True,
+    help="Will overwrite existing files.",
+)
+def init(force):
+    """Initializes a project with all necessary kacl setting."""
+    kacl_changelog = kacl.new()
+    kacl_changelog_content = kacl.dump(kacl_changelog)
+
+    if os.path.exists("CHANGELOG.md") and not force:
+        click.echo(
+            click.style("Error: ", fg="red")
+            + "CHANGELOG.md already exists. Use '--force' to overwrite."
+        )
+        sys.exit(1)
+
+    if os.path.exists(".kacl.yml") and not force:
+        click.echo(
+            click.style("Error: ", fg="red")
+            + ".kacl.yml already exists. Use '--force' to overwrite."
+        )
+        sys.exit(1)
+
+    with open("CHANGELOG.md", "w") as f:
+        f.write(kacl_changelog_content)
+    f.close()
+
+    default_config_file = os.path.join(
+        os.path.dirname(os.path.abspath(__file__)), "config", "kacl-default.yml"
+    )
+
+    # copy the default config file
+    if os.path.exists(default_config_file):
+        with open(default_config_file, "r") as df:
+            default_config_content = df.read()
+        df.close()
+
+        with open(".kacl.yml", "w") as cf:
+            cf.write(default_config_content)
+        cf.close()
+
+
 @cli.command("add-comments")
 @click.pass_context
 @click.option(

{python_kacl-0.6.5.dist-info → python_kacl-0.6.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-kacl
-Version: 0.6.5
+Version: 0.6.7
 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
@@ -47,12 +47,23 @@ A tool for verifying and modifying changelog in the [**K**eep-**A-C**hange-**L**
     - [Docker](#docker)
     - [pre-commit](#pre-commit)
   - [CLI](#cli)
+  - [Initialize a new project](#initialize-a-new-project)
   - [Create a Changelog](#create-a-changelog)
   - [Verify a Changelog](#verify-a-changelog)
   - [Print the current release version](#print-the-current-release-version)
   - [Print a single release changelog](#print-a-single-release-changelog)
   - [Add an entry to an unreleased section](#add-an-entry-to-an-unreleased-section)
   - [Prepare a Changelog for a Release](#prepare-a-changelog-for-a-release)
+  - [Changelog Fragments](#changelog-fragments)
+    - [Configuration](#configuration)
+    - [How It Works](#how-it-works)
+    - [Usage Patterns](#usage-patterns)
+      - [Automatic Fragment Creation](#automatic-fragment-creation)
+      - [Manual Fragment Control](#manual-fragment-control)
+    - [Fragment Structure](#fragment-structure)
+    - [Release Integration](#release-integration)
+    - [Workflow Integration](#workflow-integration)
+    - [Benefits](#benefits)
   - [Link Generation](#link-generation)
   - [Squashing releases](#squashing-releases)
     - [Example](#example)
@@ -63,6 +74,9 @@ A tool for verifying and modifying changelog in the [**K**eep-**A-C**hange-**L**
   - [Extensions](#extensions)
     - [Post-release/Hotfix](#post-releasehotfix)
   - [Config file](#config-file)
+    - [Default Config](#default-config)
+    - [Configuration Parameters](#configuration-parameters)
+    - [Template Variables](#template-variables)
   - [Development](#development)
 
 ## Installation
@@ -143,10 +157,97 @@ Commands:
   verify   Verifies if the changelog is in "keep-a-changelog" format.
 ```
 
+## Initialize a new project
 
-## Create a Changelog
+```bash
+Usage: kacl-cli init [OPTIONS]
+
+  Initializes a project with all necessary kacl setting.
+
+Options:
+  -f, --force  Will overwrite existing files.
+  --help       Show this message and exit.
+```
+
+The `init` command provides a quick way to set up a new project with all necessary KACL files and configuration. This command creates two essential files:
+
+1. **CHANGELOG.md** - A new changelog file with the standard Keep a Changelog format
+2. **.kacl.yml** - A complete configuration file with all available options and sensible defaults
 
+**Usage**
+
+```bash
+kacl-cli init
+```
+
+This will create both files in the current directory. If either file already exists, the command will fail unless you use the `--force` option:
+
+```bash
+kacl-cli init --force
 ```
+
+**Created Files**
+
+The `init` command creates a standard CHANGELOG.md file and copies the complete default configuration. The `.kacl.yml` file includes all available configuration options:
+
+```yaml
+kacl:
+  file: CHANGELOG.md
+  allowed_header_titles:
+    - Changelog
+    - Change Log
+  allowed_version_sections:
+    - Added
+    - Changed
+    - Deprecated
+    - Removed
+    - Fixed
+    - Security
+  default_content:
+    - All notable changes to this project will be documented in this file.
+    - 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).
+  git:
+    commit: False
+    commit_message: "[skip ci] Releasing Changelog version {new_version}"
+    commit_additional_files: []
+    tag: False
+    tag_name: "v{new_version}"
+    tag_description: "Version v{new_version} released"
+  links:
+    auto_generate: False
+    compare_versions_template: '{host}/compare/{previous_version}...{version}'
+    unreleased_changes_template: '{host}/compare/{latest_version}...master'
+    initial_version_template: '{host}/tree/{version}'
+  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})
+  stash:
+    directory: .kacl_stash
+    always: False
+```
+
+You can customize any of these settings according to your project's needs. The configuration provides sensible defaults that work for most projects while offering extensive customization options for advanced use cases.
+
+## Create a Changelog
+
+```bash
 Usage: kacl-cli new [OPTIONS]
 
   Creates a new changelog.
@@ -254,8 +355,9 @@ kacl-cli get 0.2.2
 ```
 Usage: kacl-cli add [OPTIONS] SECTION MESSAGE
 
-  Adds a given message to a specified unreleased section. Use '--modify' to
-  directly modify the changelog file.
+  Adds a given message to a specified unreleased section. A new unreleased
+  section is added if it doesn't exist. Use '--modify' to directly modify
+  the changelog file.
 
 Options:
   -m, --modify  This option will add the changes directly into changelog file
@@ -277,7 +379,9 @@ Usage: kacl-cli release [OPTIONS] VERSION
 
   Creates a release for the latest 'unreleased' changes. Use '--modify' to
   directly modify the changelog file. You can automatically use the latest
-  version by using the version keywords 'major', 'minor', 'patch', 'post'
+  version by using the version keywords 'major', 'minor', 'patch', 'post'.
+  Creates a new empty unreleased section if not disabled in the configuration
+  file.
 
   Example:
 
@@ -429,6 +533,102 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 [Unreleased]: https://gitlab.com/schmieder.matthias/python-kacl/compare/v1.0.0...HEAD
 ```
 
+## Changelog Fragments
+
+**kacl-cli** supports "changelog fragments" starting from version 6.6.0, which provides a powerful solution for managing unreleased changes in collaborative development environments. This feature helps avoid merge conflicts and simplifies changelog management when multiple developers are working on different branches simultaneously.
+
+### Configuration
+
+Enable changelog fragments through the `.kacl.yml` configuration file:
+
+```yaml
+kacl:
+  stash:
+    dir: .kacl_stash
+    always: True
+```
+
+**Configuration Options:**
+
+- `dir`: Directory where changelog fragments are stored (default: `.kacl_stash`)
+- `always`: When `True`, all `kacl add` commands automatically create fragments instead of modifying the main changelog
+
+### How It Works
+
+The stash functionality stores "Unreleased" changes in separate fragment files within the configured stash directory. These fragment files are **git-branch aware**:
+
+- **Inside a git repository**: Fragment files are named `{git_branch}.md`
+- **Outside a git repository**: Fragment files use a timestamp-based name
+
+This branch-aware naming ensures maximum segregation of changes, preventing merge conflicts and rebase issues that commonly occur when multiple merge requests modify the same changelog file simultaneously.
+
+### Usage Patterns
+
+#### Automatic Fragment Creation
+
+With `always: True` in your configuration, all changelog additions are automatically directed to fragments:
+
+```bash
+kacl add -m Changed "my new changelog entry"
+```
+
+This command creates or updates a fragment file (e.g., `feature-branch.md`) instead of modifying the main `CHANGELOG.md`.
+
+#### Manual Fragment Control
+
+With `always: False`, you have explicit control over where changes are added:
+
+```bash
+# Add directly to CHANGELOG.md
+kacl add -m Changed "directly to the CHANGELOG.md"
+
+# Add to a fragment file
+kacl add -m --stash Changed "into the fragment"
+```
+
+### Fragment Structure
+
+Each fragment file contains a standard changelog structure:
+
+```markdown
+# Changelog
+All notable changes to this project will be documented in this file.
+
+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).
+
+## Unreleased
+### Changed
+- my new changelog entry
+```
+
+### Release Integration
+
+When executing `kacl release`, the system automatically:
+
+1. **Collects all fragments** from the stash directory
+2. **Merges fragment content** into the main changelog under the new release version
+3. **Deletes processed fragments** from the stash directory
+4. **Stages deletions in git** so fragments are removed when the release is committed
+
+This seamless integration ensures that all distributed changes across branches are consolidated into a single release entry.
+
+### Workflow Integration
+
+Changelog fragments are fully integrated into all kacl workflows:
+
+- **`kacl verify`**: Validates both the main changelog and all fragments
+- **`kacl get`**: Considers fragment content when retrieving version information
+- **Git operations**: Fragment cleanup is automatically handled during release commits
+
+### Benefits
+
+- **Eliminates merge conflicts** on changelog files
+- **Enables parallel development** without coordination overhead
+- **Maintains changelog quality** through individual fragment validation
+- **Simplifies release process** with automatic fragment consolidation
+- **Preserves git history** of changelog contributions per branch
+
+
 ## Link Generation
 
 `kacl-cli` let's you easily generate links to your versions. You can automatically generate all links following the desired patterns using `kacl-cli link generate`.
@@ -581,12 +781,12 @@ Options:
 
 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                                     |
+| 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                                                                             |
+| `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:
 
@@ -651,11 +851,11 @@ required _default content_.
 By specifying a `.kacl.yml` with any of those options, the _default config_ will be merged with those local changes. Most options are also available on the CLI which take precedence over the ones
 within the config files.
 
-**Default Config**
+### Default Config
 
 ```yaml
 kacl:
-  changelog_file: CHANGELOG.md
+  file: CHANGELOG.md
   allowed_header_titles:
     - Changelog
     - Change Log
@@ -669,20 +869,20 @@ kacl:
   default_content:
     - All notable changes to this project will be documented in this file.
     - 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).
+  release:
+    add_unreleased: True
   git:
-    commit: True
+    commit: False
     commit_message: "[skip ci] Releasing Changelog version {new_version}"
     commit_additional_files: []
     tag: False
     tag_name: "v{new_version}"
     tag_description: "Version v{new_version} released"
   links:
-      # The host url is optional and will be automatically determined using your git repository
-      # host_url: https://github.com/mschmieder/kacl-cli
-      compare_versions_template: '{host}/compare/{previous_version}...{version}'
-      unreleased_changes_template: '{host}/compare/{latest_version}...master'
-      initial_version_template: '{host}/tree/{version}'
-      auto_generate: True
+    auto_generate: False
+    compare_versions_template: '{host}/compare/{previous_version}...{version}'
+    unreleased_changes_template: '{host}/compare/{latest_version}...master'
+    initial_version_template: '{host}/tree/{version}'
   extension:
     post_release_version_prefix: null
   issue_tracker:
@@ -703,7 +903,59 @@ kacl:
         ## 🧭 Reference
 
         Code: [Source Code Management System]({link})
-```
+  stash:
+    directory: .kacl_stash
+    always: False
+```
+
+### Configuration Parameters
+
+| Parameter                               | Type    | Default                                                              | Description                                              |
+| --------------------------------------- | ------- | -------------------------------------------------------------------- | -------------------------------------------------------- |
+| **Basic Settings**                      |         |                                                                      |                                                          |
+| `file`                                  | string  | `CHANGELOG.md`                                                       | Path to the changelog file                               |
+| `allowed_header_titles`                 | array   | `["Changelog", "Change Log"]`                                        | Valid changelog header titles                            |
+| `allowed_version_sections`              | array   | `["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security"]` | Valid section names within version entries               |
+| `default_content`                       | array   | See default config                                                   | Default content lines for new changelog files            |
+| **Git Integration**                     |         |                                                                      |                                                          |
+| `git.commit`                            | boolean | `false`                                                              | Automatically commit changelog changes during release    |
+| `git.commit_message`                    | string  | `"[skip ci] Releasing Changelog version {new_version}"`              | Template for commit messages                             |
+| `git.commit_additional_files`           | array   | `[]`                                                                 | Additional files to include in release commits           |
+| `git.tag`                               | boolean | `false`                                                              | Automatically create git tags during release             |
+| `git.tag_name`                          | string  | `"v{new_version}"`                                                   | Template for git tag names                               |
+| `git.tag_description`                   | string  | `"Version v{new_version} released"`                                  | Template for git tag descriptions                        |
+| **Release Settings**                    |         |                                                                      |                                                          |
+| `release.add_unreleased`                | boolean | `true`                                                               | Automatically add new "Unreleased" section after release |
+| **Link Generation**                     |         |                                                                      |                                                          |
+| `links.auto_generate`                   | boolean | `false`                                                              | Automatically generate version links during release      |
+| `links.compare_versions_template`       | string  | `"{host}/compare/{previous_version}...{version}"`                    | Template for version comparison links                    |
+| `links.unreleased_changes_template`     | string  | `"{host}/compare/{latest_version}...master"`                         | Template for unreleased changes links                    |
+| `links.initial_version_template`        | string  | `"{host}/tree/{version}"`                                            | Template for initial version links                       |
+| **Extensions**                          |         |                                                                      |                                                          |
+| `extension.post_release_version_prefix` | string  | `null`                                                               | Prefix for post-release/hotfix versions (non-SemVer)     |
+| **Issue Tracker Integration**           |         |                                                                      |                                                          |
+| `issue_tracker.jira.host`               | string  | `null`                                                               | JIRA instance hostname (also reads `JIRA_HOST` env var)  |
+| `issue_tracker.jira.username`           | string  | `null`                                                               | JIRA username (also reads `JIRA_USERNAME` env var)       |
+| `issue_tracker.jira.password`           | string  | `null`                                                               | JIRA password (also reads `JIRA_PASSWORD` env var)       |
+| `issue_tracker.jira.issue_patterns`     | array   | `["[A-Z]+-[0-9]+"]`                                                  | Regex patterns to identify issue references in changelog |
+| `issue_tracker.jira.comment_template`   | string  | See default config                                                   | Template for comments posted to JIRA issues              |
+| **Changelog Fragments**                 |         |                                                                      |                                                          |
+| `stash.directory`                       | string  | `.kacl_stash`                                                        | Directory for storing changelog fragments                |
+| `stash.always`                          | boolean | `false`                                                              | Always use fragments instead of modifying main changelog |
+
+### Template Variables
+
+The following variables are available for templating in commit messages, tag names, descriptions, and JIRA comments:
+
+| Variable             | Description                       | Example                        |
+| -------------------- | --------------------------------- | ------------------------------ |
+| `{new_version}`      | The version being released        | `1.2.3`                        |
+| `{latest_version}`   | The previous version              | `1.2.2`                        |
+| `{previous_version}` | Same as latest_version            | `1.2.2`                        |
+| `{host}`             | Git repository host URL           | `https://github.com/user/repo` |
+| `{changes}`          | Changelog content for the version | Markdown content               |
+| `{link}`             | Link to the version in SCM        | Generated link URL             |
+| `{env.VAR_NAME}`     | Environment variable              | Value of `VAR_NAME`            |
 
 ## Development
 
@@ -716,7 +968,7 @@ cd python-kacl
 
 # create a virtual env
 python3 -m venv .venv
-source ./venv/bin/activate
+source ./.venv/bin/activate
 
 # install in development mode
 pip install -e .

{python_kacl-0.6.5.dist-info → python_kacl-0.6.7.dist-info}/RECORD

@@ -1,22 +1,22 @@
-kacl/__init__.py,sha256=WUM42QzTkxNY6Yd-x-FEqcO2NFfzXkqDhRoAyqME1EE,644
+kacl/__init__.py,sha256=LVMIQ2xATXmaQ0FdcE9sRrOy2X7w-s6DKQHtZgSLNpA,667
 kacl/__main__.py,sha256=cpulIGoFUJNN5ZW9oUoNN1PnBvrOyJ24xwtpf_yRwgQ,91
-kacl/changes.py,sha256=A0POz-xFMpFuq7nISnx_K75xOZOMmBuHq6EZ8NOQDsU,661
-kacl/config.py,sha256=Glw-1hRqS3AHpZ-2QRGzHRQ-TSLc1xtneb2MEATWFEQ,3966
-kacl/document.py,sha256=dzeYCIgLA1WzK04jeeCW_AYSOCampc9x2cAHdbnEMpY,24737
+kacl/changes.py,sha256=Speu1KLMNQVn0U2BMaO8ta4IEaQLTQtpW0IhN0JjGdY,704
+kacl/config.py,sha256=c2QiP-BriJJwzrw36oigJWKe6t4o6yhmN_nPSL6bcRk,4242
+kacl/document.py,sha256=oNnxlXWEh4yfqK4dK8xhzjWrUPHbUizEj_PQhP73poQ,28763
 kacl/element.py,sha256=OG02QI8ND5fJpBMceT6dbIHr4uX9gLxK_fPCsOvMDHI,416
 kacl/exception.py,sha256=MfOVpUvhcQtm10rSY__74-oLo445PG8mLFGJPPIfXH0,41
 kacl/jira_client.py,sha256=KPE94bZDkJFKw3okFsCgf2DjoyMlUUTMZKtQGKreVQY,989
-kacl/kacl_cli.py,sha256=KeCT4DydkHjckt5sbTtTwp2BQf0RllXpBUwLj-G5-U0,19987
+kacl/kacl_cli.py,sha256=RshCxLhh5YJa6tzl8f5dnLOYF3Kbl-EDD4m21hIJDPw,22176
 kacl/link_provider.py,sha256=tgvMYhJe2ErH1m_qXMlQEacq9Cg_KGp_-sF03sVFP6E,1866
 kacl/parser.py,sha256=EUtRjgaW0beWVqiYaRJ9Rcf6jbuGoTgWzVBdOdUHnv8,2587
 kacl/serializer.py,sha256=PdR2FFCh9rbBhkxXwUYD0fSjQqTG_Mb6mYws3lNAWQ8,3090
 kacl/utils.py,sha256=bHiDDmjoYB868Bm732vNjpfML-6xcNQQqS7NQn_Sfm0,2824
 kacl/validation.py,sha256=b9r_5CyY6Cmi9BePh47IgZ3j64zdVsoB_fFvucieNbw,2125
 kacl/version.py,sha256=IDYCWIIXzxdYyMptUAidMgf0SXJqoETFVJ8NVyKgA9A,9526
-kacl/config/kacl-default.yml,sha256=BdrQytOsx32_vXXBtR3VRp1-nzWrczNVc-gHuCGYuIA,1424
-python_kacl-0.6.5.dist-info/licenses/LICENSE,sha256=TRSJOIt7LZuMeZXFleJVL_LHczSxqi70HEiTLT-kI8Q,1075
-python_kacl-0.6.5.dist-info/METADATA,sha256=kVBx144zCKsmVBAnZS-RQ1omJ2QiPfIME6DtJRz8loE,24325
-python_kacl-0.6.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-python_kacl-0.6.5.dist-info/entry_points.txt,sha256=rXqqJKfm6Y7fYfioq_7ay2VWOOM9C-hts1IsoGTtojM,76
-python_kacl-0.6.5.dist-info/top_level.txt,sha256=BcmQgo67JyGnVZ3Jc0Ag8hKMGVOqXc8ex01zW4Njw5M,5
-python_kacl-0.6.5.dist-info/RECORD,,
+kacl/config/kacl-default.yml,sha256=cXHl_w04SW0HA7OyJMMuaC6DTeXlhI2Sfsx7lygTPf4,1513
+python_kacl-0.6.7.dist-info/licenses/LICENSE,sha256=TRSJOIt7LZuMeZXFleJVL_LHczSxqi70HEiTLT-kI8Q,1075
+python_kacl-0.6.7.dist-info/METADATA,sha256=WXFDjyEQ1jS_sJyzfcHgx3wfq9OijduqLo1KYSkYpXY,38157
+python_kacl-0.6.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+python_kacl-0.6.7.dist-info/entry_points.txt,sha256=rXqqJKfm6Y7fYfioq_7ay2VWOOM9C-hts1IsoGTtojM,76
+python_kacl-0.6.7.dist-info/top_level.txt,sha256=BcmQgo67JyGnVZ3Jc0Ag8hKMGVOqXc8ex01zW4Njw5M,5
+python_kacl-0.6.7.dist-info/RECORD,,