Update documentation and CI workflow

.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

@@ -23,6 +23,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   **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
@@ -161,36 +173,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)