python-kacl 0.7.0__py3-none-any.whl → 0.7.2__py3-none-any.whl

kacl/__init__.py

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

kacl/document.py

@@ -330,6 +330,60 @@ class KACLDocument:
                 self.__versions.insert(0, unreleased_version)
             unreleased_version.add(section.capitalize(), data)
 
+    def stash_unreleased(self):
+        """Moves all unreleased changes to the stash file.
+
+        This method takes all changes from the Unreleased section and writes them to
+        the stash file, then clears the Unreleased section from the changelog.
+        """
+        # Check if there are any unreleased changes
+        if not self.has_changes():
+            return False
+
+        # Get the unreleased version
+        unreleased_version = self.get("Unreleased")
+        if not unreleased_version:
+            return False
+
+        # Get or create the stash file
+        stash_file = self._get_stash_file()
+
+        if os.path.exists(stash_file):
+            # Load the stash file
+            kacl_changelog = kacl.load(stash_file)
+        else:
+            # Create a new stash file with an empty changelog
+            kacl_changelog = kacl.new()
+
+        # Add all unreleased changes to the stash
+        sections = unreleased_version.sections()
+        if sections:
+            for section_title, section_changes in sections.items():
+                for change_item in section_changes.items():
+                    kacl_changelog.add(section=section_title, data=change_item)
+
+        # Write the updated stash file
+        kacl_changelog_content = kacl.dump(kacl_changelog)
+        with open(stash_file, "w") as f:
+            f.write(kacl_changelog_content)
+        f.close()
+
+        # Clear the unreleased section by replacing it with an empty one
+        # Find and remove the current unreleased version but keep the link reference if it exists
+        link = None
+
+        for i, version in enumerate(self.__versions):
+            if version.version() == "Unreleased":
+                link = version.link()
+                self.__versions.pop(i)
+                break
+
+        # Add a new empty unreleased version
+        new_unreleased = KACLVersion(version="Unreleased", link=link)
+        self.__versions.insert(0, new_unreleased)
+
+        return True
+
     def release(
         self,
         version=None,

kacl/kacl_cli.py

@@ -44,7 +44,7 @@ def raise_on_invalid(kacl_changelog):
         sys.exit(1)
 
 
-def load_changelog(ctx):
+def load_changelog(ctx, load_stash_files=True):
     config_file_path = ctx.obj["config"]
     input_file = ctx.obj["file"]
 
@@ -69,7 +69,8 @@ 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()
+    if load_stash_files:
+        kacl_changelog.load_stash()
 
     # share the objects
     return kacl_changelog
@@ -159,6 +160,51 @@ def add(ctx, section, message, modify, stash):
         click.echo(kacl_changelog_content)
 
 
+@cli.command()
+@click.pass_context
+@click.option(
+    "-m",
+    "--modify",
+    is_flag=True,
+    help="This option will modify the changelog file directly.",
+)
+def stash(ctx, modify):
+    """Moves all unreleased changes from the changelog to the stash."""
+    # Load changelog WITHOUT loading stash files to avoid circular stashing
+    kacl_changelog = load_changelog(ctx, load_stash_files=False)
+
+    # Check if there are changes to stash
+    if not kacl_changelog.has_changes():
+        click.echo(
+            click.style("Info: ", fg="yellow") + "No unreleased changes to stash."
+        )
+        return
+
+    # Stash the unreleased changes
+    kacl_changelog.stash_unreleased()
+
+    stash_file = kacl_changelog._get_stash_file()
+    click.echo(
+        click.style("Success: ", fg="green")
+        + f"Unreleased changes have been moved to {stash_file}"
+    )
+
+    # Update the changelog file if modify flag is set
+    if modify:
+        kacl_changelog_content = kacl.dump(kacl_changelog)
+        with open(kacl_changelog.config.changelog_file_path, "w") as f:
+            f.write(kacl_changelog_content)
+        f.close()
+        click.echo(
+            click.style("Success: ", fg="green")
+            + f"Changelog file {kacl_changelog.config.changelog_file_path} has been updated."
+        )
+    else:
+        # Just print the modified changelog
+        kacl_changelog_content = kacl.dump(kacl_changelog)
+        click.echo(kacl_changelog_content)
+
+
 @cli.command()
 @click.pass_context
 def current(ctx):

{python_kacl-0.7.0.dist-info → python_kacl-0.7.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-kacl
-Version: 0.7.0
+Version: 0.7.2
 Summary: Python module and CLI tool for validating and modifying Changelogs in "keep-a-changelog" format"
 Author-email: Matthias Schmieder <schmieder.matthias@gmail.com>
 License: MIT
@@ -42,6 +42,8 @@ A tool for verifying and modifying changelog in the [**K**eep-**A-C**hange-**L**
   - [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)
+  - [Stashing Unreleased Changes](#stashing-unreleased-changes)
+    - [Pre-commit Hook Integration](#pre-commit-hook-integration)
   - [Prepare a Changelog for a Release](#prepare-a-changelog-for-a-release)
   - [Changelog Fragments](#changelog-fragments)
     - [Configuration](#configuration)
@@ -121,13 +123,26 @@ docker -v $(pwd):$(pwd) -w $(pwd) mschmieder/kacl-cli:latest verify
 
 The package can also be used as a pre-commit hook. Just add the following to your `.pre-commit-config.yaml`
 
+**Verify Changelog Format**
+
 ```yaml
 - repo: https://gitlab.com/schmieder.matthias/python-kacl
-  rev: 'v0.3.0'
+  rev: 'v0.7.0'  # Use the latest version
   hooks:
     - id: kacl-verify
 ```
 
+**Auto-Stash Unreleased Changes (Prevent Merge Conflicts)**
+
+```yaml
+- repo: https://gitlab.com/schmieder.matthias/python-kacl
+  rev: 'v0.7.0'  # Use the latest version
+  hooks:
+    - id: kacl-stash
+```
+
+The `kacl-stash` hook automatically moves unreleased changes to stash files before each commit, preventing merge conflicts in `CHANGELOG.md`. See [Stashing Unreleased Changes](#stashing-unreleased-changes) for more details.
+
 ## CLI
 
 ```
@@ -143,6 +158,7 @@ Commands:
   get      Returns a given version from the Changelog
   new      Creates a new changelog.
   release  Creates a release for the latest 'unreleased' changes.
+  stash    Moves all unreleased changes from the changelog to the stash.
   verify   Verifies if the changelog is in "keep-a-changelog" format.
 ```
 
@@ -361,6 +377,112 @@ kacl-cli add added 'We just added some new cool stuff' --modify
 kacl-cli add changed 'And changed things a bit' --modify
 ```
 
+## Stashing Unreleased Changes
+
+```
+Usage: kacl-cli stash [OPTIONS]
+
+  Moves all unreleased changes from the changelog to the stash.
+
+Options:
+  -m, --modify  This option will modify the changelog file directly.
+  --help        Show this message and exit.
+```
+
+The `stash` command provides a powerful solution for managing unreleased changes and **preventing merge conflicts** in collaborative development environments. It moves all unreleased changes from `CHANGELOG.md` to a stash file, leaving an empty "Unreleased" section in the main changelog.
+
+**Primary Use Case: Avoiding Merge Conflicts**
+
+When multiple team members work on different branches simultaneously and manually edit `CHANGELOG.md`, merge conflicts are inevitable. The `stash` command solves this problem by:
+
+1. **Moving changes out of the main changelog** into separate stash files
+2. **Preventing conflicts** during merges since the main changelog remains minimal
+3. **Preserving all changes** in stash files that are later consolidated during release
+
+**Usage**
+
+```bash
+# Preview what would be stashed (dry-run)
+kacl-cli stash
+
+# Actually stash the changes and update CHANGELOG.md
+kacl-cli stash --modify
+```
+
+**How It Works**
+
+When you run `kacl-cli stash --modify`:
+
+1. All changes from the "Unreleased" section are extracted
+2. Changes are moved to a stash file in `.kacl_stash/` directory (default location)
+3. Stash files are named based on:
+   - Git branch name (when inside a git repository): `feature-branch.md`
+   - Current date (when outside git): `20230101.md`
+4. The "Unreleased" section in `CHANGELOG.md` is cleared
+5. During `kacl-cli release`, all stashed changes are automatically merged into the release
+
+**Example Workflow**
+
+```bash
+# Developer edits CHANGELOG.md directly
+echo "- Added new feature" >> CHANGELOG.md
+
+# Before committing, stash the changes to avoid conflicts
+kacl-cli stash --modify
+
+# CHANGELOG.md now has an empty Unreleased section
+# Changes are in .kacl_stash/your-branch.md
+
+# When ready to release, all stashed changes are included
+kacl-cli release patch --modify
+```
+
+### Pre-commit Hook Integration
+
+For maximum convenience, you can automate the stashing process using a pre-commit hook. This allows developers to continue editing `CHANGELOG.md` manually while automatically moving changes to the stash before each commit.
+
+**Setup**
+
+Add the `kacl-stash` hook to your `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: https://gitlab.com/schmieder.matthias/python-kacl
+    rev: 'v0.7.0'  # Use the latest version
+    hooks:
+      - id: kacl-stash
+```
+
+**How It Works**
+
+1. Developer manually edits `CHANGELOG.md` (traditional workflow)
+2. Pre-commit hook automatically runs `kacl-cli stash -m` before each commit
+3. Changes are moved to stash files
+4. Only the cleaned `CHANGELOG.md` is committed
+5. Multiple branches can work independently without conflicts
+6. During release, all stashed changes are consolidated
+
+**Benefits**
+
+- ✅ **No workflow changes**: Developers continue editing `CHANGELOG.md` normally
+- ✅ **Zero merge conflicts**: Main changelog stays minimal and conflict-free
+- ✅ **Automatic management**: Pre-commit hook handles everything
+- ✅ **Branch isolation**: Each branch has its own stash file
+- ✅ **Seamless integration**: Changes automatically included in releases
+
+**Configuration**
+
+You can customize the stash directory in `.kacl.yml`:
+
+```yaml
+kacl:
+  stash:
+    dir: .kacl_stash  # Custom stash directory
+    always: False     # Set to True to always use stash for 'kacl add'
+```
+
+**Note**: The `stash` command is complementary to [Changelog Fragments](#changelog-fragments). While fragments support the `kacl add` workflow, the `stash` command is specifically designed for teams that prefer manually editing `CHANGELOG.md` but want to avoid merge conflicts.
+
 ## Prepare a Changelog for a Release
 
 ```

{python_kacl-0.7.0.dist-info → python_kacl-0.7.2.dist-info}/RECORD

@@ -1,12 +1,12 @@
-kacl/__init__.py,sha256=MnxkLHetlUiurIRM5_1ECpv-0lmQO3yM4U-x0-U56Z4,667
+kacl/__init__.py,sha256=a9OB0XDXEUnOYCDzHxN6YiQ58IrTOubzTfFXVmghz7M,667
 kacl/__main__.py,sha256=cpulIGoFUJNN5ZW9oUoNN1PnBvrOyJ24xwtpf_yRwgQ,91
 kacl/changes.py,sha256=Speu1KLMNQVn0U2BMaO8ta4IEaQLTQtpW0IhN0JjGdY,704
 kacl/config.py,sha256=c2QiP-BriJJwzrw36oigJWKe6t4o6yhmN_nPSL6bcRk,4242
-kacl/document.py,sha256=oNnxlXWEh4yfqK4dK8xhzjWrUPHbUizEj_PQhP73poQ,28763
+kacl/document.py,sha256=jyltUjNWp67t54DMkBudOd3btX2awLJgGKDPvbyoMOo,30733
 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=RshCxLhh5YJa6tzl8f5dnLOYF3Kbl-EDD4m21hIJDPw,22176
+kacl/kacl_cli.py,sha256=kUDssIf5SH6ppQxil8ESplUw6ejyj6srW6nOfXqLD0Y,23688
 kacl/link_provider.py,sha256=tgvMYhJe2ErH1m_qXMlQEacq9Cg_KGp_-sF03sVFP6E,1866
 kacl/parser.py,sha256=EUtRjgaW0beWVqiYaRJ9Rcf6jbuGoTgWzVBdOdUHnv8,2587
 kacl/serializer.py,sha256=PdR2FFCh9rbBhkxXwUYD0fSjQqTG_Mb6mYws3lNAWQ8,3090
@@ -14,9 +14,9 @@ kacl/utils.py,sha256=4iWIJVNtv22v0IGXDjuEATPMQsJBr5Ycy9Q2zV2jkHE,2835
 kacl/validation.py,sha256=b9r_5CyY6Cmi9BePh47IgZ3j64zdVsoB_fFvucieNbw,2125
 kacl/version.py,sha256=IDYCWIIXzxdYyMptUAidMgf0SXJqoETFVJ8NVyKgA9A,9526
 kacl/config/kacl-default.yml,sha256=cXHl_w04SW0HA7OyJMMuaC6DTeXlhI2Sfsx7lygTPf4,1513
-python_kacl-0.7.0.dist-info/licenses/LICENSE,sha256=TRSJOIt7LZuMeZXFleJVL_LHczSxqi70HEiTLT-kI8Q,1075
-python_kacl-0.7.0.dist-info/METADATA,sha256=H827aGS3Up34fHQcdUChKDqg1zv50U9u7stimIN_jY4,37949
-python_kacl-0.7.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
-python_kacl-0.7.0.dist-info/entry_points.txt,sha256=rXqqJKfm6Y7fYfioq_7ay2VWOOM9C-hts1IsoGTtojM,76
-python_kacl-0.7.0.dist-info/top_level.txt,sha256=BcmQgo67JyGnVZ3Jc0Ag8hKMGVOqXc8ex01zW4Njw5M,5
-python_kacl-0.7.0.dist-info/RECORD,,
+python_kacl-0.7.2.dist-info/licenses/LICENSE,sha256=TRSJOIt7LZuMeZXFleJVL_LHczSxqi70HEiTLT-kI8Q,1075
+python_kacl-0.7.2.dist-info/METADATA,sha256=Mocj5ub2iwUjpPJOlbullX5IJ4_MvmxABHoDlNbFsuw,42453
+python_kacl-0.7.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_kacl-0.7.2.dist-info/entry_points.txt,sha256=rXqqJKfm6Y7fYfioq_7ay2VWOOM9C-hts1IsoGTtojM,76
+python_kacl-0.7.2.dist-info/top_level.txt,sha256=BcmQgo67JyGnVZ3Jc0Ag8hKMGVOqXc8ex01zW4Njw5M,5
+python_kacl-0.7.2.dist-info/RECORD,,

{python_kacl-0.7.0.dist-info → python_kacl-0.7.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (82.0.0)
+Generator: setuptools (82.0.1)
 Root-Is-Purelib: true
 Tag: py3-none-any