Patch Update v1.3.4

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -18,9 +18,9 @@ body:
           options:
               - label: I have read the [README.md](../README.md)
                 required: true
-              - label: I have searched for existing issues that might be related to this bug
+              - label: I am using the [latest version of Agent Docstrings](https://github.com/Artemonim/AgentDocstrings/releases/latest)
                 required: true
-              - label: I am using the latest version of Agent Docstrings
+              - label: I have searched for existing issues that might be related to this bug
                 required: true
 
     - type: dropdown

.github/ISSUE_TEMPLATE/config.yml

@@ -3,6 +3,9 @@ contact_links:
     - name: 📖 Documentation
       url: https://github.com/Artemonim/AgentDocstrings/blob/master/README.md
       about: Read the project documentation and setup instructions
+    - name: 📝 Contribution Guide
+      url: https://github.com/Artemonim/AgentDocstrings/blob/master/CONTRIBUTING.md
+      about: Learn how to contribute to the project
     - name: 💬 Discussions
       url: https://github.com/Artemonim/AgentDocstrings/discussions
       about: Ask questions and discuss ideas with the community

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -18,9 +18,9 @@ body:
           options:
               - label: I have read the [README.md](../README.md)
                 required: true
-              - label: I am using the latest version of Agent Docstrings
+              - label: I am using the [latest version of Agent Docstrings](https://github.com/Artemonim/AgentDocstrings/releases/latest)
                 required: true
-              - label: I have searched for existing issues to see if this feature has been requested before
+              - label: I have searched for existing open and closed issues to see if this feature has been requested before
                 required: true
               - label: This feature request is not a bug report (use Bug Report template for bugs)
                 required: true

.github/ISSUE_TEMPLATE/question.yml

@@ -16,9 +16,11 @@ body:
           label: Pre-submission Checklist
           description: Please confirm you have completed these steps
           options:
+              - label: I have read the [README.md](../README.md) and relevant documentation
+                required: true
               - label: I have searched existing issues and discussions for similar questions
                 required: true
-              - label: I have read the [README.md](../README.md) and relevant documentation
+              - label: I have searched for existing open and closed issues to see if this feature has been requested before
                 required: true
               - label: This is not a bug report (use Bug Report template for bugs)
                 required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,7 +1,6 @@
 <!--
 Thank you for contributing to AgentDocstringsGenerator!
 
-Please provide a clear and concise description of your changes.
 If your PR is a work in progress, please mark it as a draft.
 -->
 
@@ -20,34 +19,13 @@ Please check the box that best describes the nature of your change.
 -   [ ] 🎨 **Style**: Changes that do not affect the meaning of the code (white-space, formatting, etc.).
 -   [ ] ⏪ **Revert**: Reverts a previous commit.
 
----
-
-## Related Issue
-
-<!--
-If this PR addresses a specific issue, please link it here.
-For example: `Fixes #123` or `Closes #123`.
-If there is no related issue, please state that.
--->
-
--   ***
-
-## Description
-
-<!--
-Provide a clear and concise summary of the changes.
-Explain the "what" and "why" of your contribution.
--->
-
--
-
 ## Checklist
 
 <!--
 Go over all the following points, and put an `x` in all the boxes that apply.
 -->
 
--   [ ] My code follows the style guidelines of this project.
--   [ ] I have performed a self-review of my own code.
+-   [ ] My changes follows the [Contribution Guide](CONTRIBUTING.md).
+-   [ ] I have updated `CHANGELOG.md` under the `[NextRelease]` section.
 -   [ ] New unit tests have been added to cover the changes.
--   [ ] Manual testing has been performed
+-   [ ] Manual testing has been performed to verify the changes.

.github/workflows/ci.yml

@@ -4,18 +4,18 @@ on:
     # Run on pull requests into dev or master.
     pull_request:
         branches: [master, dev]
-    # After a PR is merged, the merge commit is pushed to master; we still want tests + coverage once on the resulting commit.
+    # Push to dev also triggers tests to ensure dev branch is always stable
     push:
-        branches: [master]
+        branches: [dev]
 
 jobs:
     test:
         # * Runs unit-test matrix:
-        #   - Always on pull_request (dev or master)
-        #   - On push to master (after merge)
+        #   - On pull_request (to dev or master)
+        #   - On push to dev
         if: |
             github.event_name == 'pull_request' ||
-            (github.event_name == 'push' && github.ref == 'refs/heads/master')
+            (github.event_name == 'push' && github.ref == 'refs/heads/dev')
         name: Test on Python ${{ matrix.python-version }} (beta=${{ matrix.beta }})
         runs-on: ubuntu-latest
         strategy:
@@ -25,7 +25,7 @@ jobs:
         steps:
             - name: Checkout repository
               uses: actions/checkout@v4
-              # For pull_request we check out the PR commit; for push we stay on the pushed ref (master).
+              # For pull_request we check out the PR commit; for push we stay on the pushed ref (dev).
               with:
                   ref: ${{ github.event.pull_request.head.sha }}
 
@@ -34,6 +34,14 @@ jobs:
               with:
                   go-version: "1.22"
 
+            - name: Cache Go modules
+              uses: actions/cache@v4
+              with:
+                  path: ~/go/pkg/mod
+                  key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+                  restore-keys: |
+                      ${{ runner.os }}-go-
+
             - name: Build Go parsers
               run: pwsh -File ./build_goparser.ps1
               shell: bash
@@ -43,6 +51,14 @@ jobs:
               with:
                   python-version: ${{ matrix.python-version }}
 
+            - name: Cache pip
+              uses: actions/cache@v4
+              with:
+                  path: ~/.cache/pip
+                  key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+                  restore-keys: |
+                      ${{ runner.os }}-pip-
+
             - name: Install dependencies
               run: |
                   python -m pip install --upgrade pip
@@ -67,9 +83,7 @@ jobs:
 
     report:
         # * Only for master: either in PR to master (so reviewers see comment) or after merge push to master.
-        if: |
-            (github.event_name == 'pull_request' && github.base_ref == 'master') ||
-            (github.event_name == 'push' && github.ref == 'refs/heads/master')
+        if: github.event_name == 'pull_request' && github.base_ref == 'master'
         name: Report Coverage
         runs-on: ubuntu-latest
         needs: test
@@ -104,9 +118,24 @@ jobs:
 
             - name: Verify that version was not bumped
               run: |
-                  if ! git diff --quiet origin/dev HEAD -- pyproject.toml; then
-                      echo "::error::Version in pyproject.toml was changed in a PR to dev."
+                  echo "Checking for version changes in pyproject.toml..."
+                  DEV_PYPROJECT_VERSION=$(git show origin/dev:pyproject.toml | grep '^version = ' | awk -F'"' '{print $2}')
+                  HEAD_PYPROJECT_VERSION=$(grep '^version = ' pyproject.toml | awk -F'"' '{print $2}')
+
+                  if [ "$DEV_PYPROJECT_VERSION" != "$HEAD_PYPROJECT_VERSION" ]; then
+                      echo "::error::Version in pyproject.toml was changed in a PR to dev. (dev: $DEV_PYPROJECT_VERSION, HEAD: $HEAD_PYPROJECT_VERSION)"
                       echo "Version bumping should only happen in a release PR to master."
                       exit 1
                   fi
                   echo "Version check passed for pyproject.toml"
+
+                  echo "Checking for version changes in agent_docstrings/__init__.py..."
+                  DEV_INIT_VERSION=$(git show origin/dev:agent_docstrings/__init__.py | grep '^__version__ = ' | awk -F'"' '{print $2}')
+                  HEAD_INIT_VERSION=$(grep '^__version__ = ' agent_docstrings/__init__.py | awk -F'"' '{print $2}')
+
+                  if [ "$DEV_INIT_VERSION" != "$HEAD_INIT_VERSION" ]; then
+                      echo "::error::Version in agent_docstrings/__init__.py was changed in a PR to dev. (dev: $DEV_INIT_VERSION, HEAD: $HEAD_INIT_VERSION)"
+                      echo "Version bumping should only happen in a release PR to master."
+                      exit 1
+                  fi
+                  echo "Version check passed for agent_docstrings/__init__.py"

.github/workflows/release-automation.yml

@@ -0,0 +1,56 @@
+name: Release Automation
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  create_release:
+    # We only run it for merge commits from branches release/*
+    if: startsWith(github.event.head_commit.message, 'Merge pull request') && contains(github.event.head_commit.message, 'from release/')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # to create tags and releases
+      pull-requests: write # to create PR
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          # I need a complete history to read the tags and create a PR
+          fetch-depth: 0
+
+      - name: Get Version
+        id: get_version
+        run: |
+          # Извлекаем версию из pyproject.toml
+          version=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+          echo "version=${version}" >> $GITHUB_OUTPUT
+
+      - name: Extract Changelog Notes
+        id: changelog
+        uses: mindsers/changelog-reader-action@v2
+        with:
+          version: ${{ steps.get_version.outputs.version }}
+          path: ./CHANGELOG.md
+
+      - name: Create GitHub Release
+        id: create_release
+        uses: actions/create-release@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          tag_name: v${{ steps.get_version.outputs.version }}
+          release_name: v${{ steps.get_version.outputs.version }}
+          body: ${{ steps.changelog.outputs.changes }}
+          draft: false
+          prerelease: false
+
+      - name: Create back-merge PR to dev
+        uses: repo-sync/pull-request@v2
+        with:
+          source_branch: "master"
+          destination_branch: "dev"
+          pr_title: "Post-Release: Merge master back into dev"
+          pr_body: "Automated PR to sync master back into dev after release v${{ steps.get_version.outputs.version }}."
+          github_token: ${{ secrets.GITHUB_TOKEN }} 

CHANGELOG.md

@@ -16,6 +16,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [NextRelease]
 
+### Header
+
+-   **subtitle**: describtion
+
+## [1.3.4]
+
+### Fixed
+
+-   **Deterministic Processing**: Fixed a critical bug that caused line numbers in the table of contents to change on every run. This was due to inconsistent newline handling after removing an existing agent docstring. The process is now fully idempotent.
+-   **Robust Docstring Removal**: Improved the detection logic to correctly find and remove all agent-generated docstrings, even when located in the middle of a file or when multiple (erroneous) docstrings were present. This prevents docstring duplication on repeated runs.
+-   **Manual Docstring Preservation**: Ensured that manual docstrings are no longer reformatted or modified unless they are being merged with an agent-generated table of contents.
+-   **Version-Only Change Skipping**: Fixed a bug where files were being unnecessarily modified when only the version number in the auto-generated header differed, while the actual content structure remained unchanged. The tool now performs normalized content comparison that ignores version differences, preventing unnecessary file modifications after Agent Docstrings version updates.
+
+### Documentation
+
+-   **Contribution Guide**: Added a new `CONTRIBUTING.md` file with detailed guidelines for development workflow and the release process.
+-   **README Update**: Updated `README.md` to link to the new contribution guide and reflect the automated release process.
+
+### CI/CD
+
+-   **Release Automation**: Added a new `release-automation.yml` workflow that automatically creates Git tags, GitHub Releases, and back-merge PRs when release branches are merged to master.
+-   **CI Optimization**: Optimized the main CI pipeline by removing redundant test runs on master branch pushes and adding caching for pip dependencies and Go modules to speed up workflow execution.
+-   **Workflow Efficiency**: Changed CI triggers to run on pushes to `dev` instead of `master`, eliminating duplicate test runs while maintaining comprehensive coverage.
+-   **Version Check Precision**: Improved the version bump detection in CI to specifically check version changes in `pyproject.toml` and `agent_docstrings/__init__.py`, preventing false positives from other file modifications.
+
 ## [1.3.3]
 
 ### Fixed
@@ -154,36 +179,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   **Programmatic API**: Import and use in other Python projects
 -   **Safe operation**: Only modifies auto-generated docstring blocks, preserves existing documentation
 -   **Incremental updates**: Only processes files when changes are detected
-
-### Technical Features
-
--   Uses `from __future__ import annotations` for forward compatibility
--   Compatible with `typing.Union` and `typing.Tuple` for Python 3.8/3.9
--   No external dependencies - built on Python standard library only
--   Comprehensive test suite with pytest
--   Full type checking support with mypy
--   Code formatting with black
--   Proper packaging for PyPI distribution
-
-### Configuration
-
--   `.agent-docstrings-ignore`: Specify files and patterns to exclude
--   `.agent-docstrings-include`: Specify files and patterns to include (whitelist mode)
--   Automatic integration with existing `.gitignore` files
--   Support for glob patterns in configuration files
-
-### Documentation
-
--   Comprehensive README with usage examples
--   Integration guides for pre-commit hooks and CI/CD
--   Development setup instructions
--   API documentation for programmatic usage
-
-## Version History
-
--   **1.0.1** - Parser and docstring handling improvements
--   **1.0.0** - Initial stable release with multi-language support and filtering system
--   **0.4.0** - (internal)
--   **0.3.0** - (internal)
--   **0.2.0** - (internal)
--   **0.1.0** - Initial development version (internal)