python-kacl 0.6.5__tar.gz → 0.6.7__tar.gz

{python_kacl-0.6.5/python_kacl.egg-info → python_kacl-0.6.7}/PKG-INFO

@@ -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 .