chore: enhance documentation and CI/CD processes

Artemonim · Artemonim · commit 68c6ace03df6 · 2025-07-07T23:10:03.000+03:00
### Added
- Introduced a `CONTRIBUTING.md` file with comprehensive guidelines for contributing to the project.
- Updated `README.md` to link to the new contribution guide and clarify the automated release process.
- Implemented a new `release-automation.yml` workflow for automatic Git tagging, GitHub Releases, and back-merging PRs upon merging release branches into master.
- Optimized the CI pipeline by removing redundant test runs on master branch pushes and adding caching for pip dependencies and Go modules.

### Changed
- Adjusted CI triggers to run on pushes to `dev` instead of `master`, improving workflow efficiency.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.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
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,6 +16,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [NextRelease]
 
+### 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.
+
 ## [1.3.3]
 
 ### Fixed
@@ -155,35 +166,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 -   **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)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,116 @@
+# Contributing to AgentDocstringsGenerator
+
+First off, thank you for considering contributing to AgentDocstringsGenerator! It's people like you that make this such a great tool.
+
+This document provides guidelines for contributing to the project. Please feel free to propose changes to this document in a pull request.
+
+## Table of Contents
+
+-   [How Can I Contribute?](#how-can-i-contribute)
+    -   [Reporting Bugs](#reporting-bugs)
+    -   [Suggesting Enhancements](#suggesting-enhancements)
+    -   [Pull Requests](#pull-requests)
+-   [Development Workflow](#development-workflow)
+    -   [Branching Model](#branching-model)
+    -   [Development Steps](#development-steps)
+    -   [Updating the Changelog](#updating-the-changelog)
+-   [Release Process (for maintainers)](#release-process-for-maintainers)
+-   [Styleguides](#styleguides)
+
+## How Can I Contribute?
+
+We value community contributions and appreciate your help. Please be respectful in all your interactions.
+
+### Reporting Bugs
+
+If you find a bug, please ensure it hasn't already been reported by searching on GitHub under [Issues](https://github.com/Artemonim/AgentDocstrings/issues). If you can't find an open issue addressing the problem, please open a new one. Include a clear title, a detailed description, and a code sample or test case that demonstrates the issue.
+
+### Suggesting Enhancements
+
+If you have an idea for an enhancement, please open an issue to discuss it first. This allows us to coordinate our efforts and ensure the proposed changes align with the project's goals.
+
+### Pull Requests
+
+We welcome pull requests. Please follow these steps to have your contribution considered:
+
+1. Follow the [Development Workflow](#development-workflow).
+2. Ensure that your code adheres to the [Styleguides](#styleguides).
+3. Make sure all tests pass.
+4. Fill out the pull request template provided.
+
+## Development Workflow
+
+This project uses a GitFlow-like branching model.
+
+### Branching Model
+
+-   **`master`**: This branch contains the latest stable release. Direct pushes are not allowed.
+-   **`dev`**: This is the main development branch. All feature branches should be created from `dev`, and all pull requests should be submitted to `dev`.
+-   **`feature/*`**: For new features. Branched from `dev`. Example: `feature/new-parser`.
+-   **`fix/*`**: For bug fixes. Branched from `dev`. Example: `fix/off-by-one-error`.
+-   **`release/*`**: For preparing new releases. Branched from `dev`. Merged into `master`.
+
+### Development Steps
+
+1.  **Fork** the repository on GitHub.
+2.  **Clone** your fork locally: `git clone https://github.com/YOUR_USERNAME/AgentDocstrings.git`
+3.  **Set up the environment**:
+    ```bash
+    cd AgentDocstrings
+    pip install -e .[dev]
+    ```
+4.  **Create a new branch** from `dev`:
+    ```bash
+    git checkout dev
+    git pull origin dev
+    git checkout -b feature/your-amazing-feature
+    ```
+5.  **Make your changes**. Write clean, readable code.
+6.  **Add or update tests** for your changes in the `tests/` directory.
+7.  **Run tests** to ensure everything is working correctly: `python -m pytest`
+8.  **Update the Changelog** `NextRelease` section.
+9.  **Commit** your changes. Use a clear and descriptive commit message.
+10. **Push** your branch to your fork on GitHub: `git push origin feature/your-amazing-feature`
+11. **Open a Pull Request** to the `dev` branch of the main repository.
+
+### Updating the Changelog
+
+For every change that affects the user, you must add an entry to the `CHANGELOG.md` file under the `[NextRelease]` section. Follow the format of existing entries.
+
+Example:
+
+```markdown
+## [NextRelease]
+
+### TypeOfChange
+
+-   **Your Awesome Feature**: A brief description of what you've added.
+```
+
+## Release Process (for maintainers)
+
+The release process is partially automated.
+
+1.  Create a release branch from `dev`: `git checkout -b release/x.y.z` (e.g., `release/1.4.0`).
+2.  Update the version using `bump-my-version`:
+    ```bash
+    # For a patch, minor, or major release
+    bump-my-version patch/minor/major
+    ```
+    This command will update the version in `pyproject.toml` and update the `CHANGELOG.md`, replacing `[NextRelease]` with the new version tag.
+3.  Commit the version bump: `git commit -am "chore: release v.x.y.z"`
+4.  Push the release branch: `git push origin release/x.y.z`
+5.  Open a Pull Request from the `release/x.y.z` branch to `master`.
+6.  Once the PR is merged into `master`, the `release-automation` workflow will automatically:
+    -   Create a Git tag (e.g., `v1.4.0`).
+    -   Create a GitHub Release with the notes from `CHANGELOG.md`.
+    -   Create a Pull Request to merge `master` back into `dev`.
+7.  The `release.yml` workflow will then automatically publish the package to PyPI upon the creation of the GitHub Release.
+
+## Styleguides
+
+Please follow the coding style of the project to maintain consistency.
+
+-   **Python**: [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html), formatted with `black`.
+-   **Comments**: Use [Better Comments](https://marketplace.visualstudio.com/items?itemName=aaron-bond.better-comments) style.
+-   **Docstrings**: Use Google Style Docstrings.
diff --git a/README.md b/README.md
@@ -319,7 +319,7 @@ This project uses [bump-my-version](https://github.com/callowayproject/bump-my-v
 
 The tool is configured in `pyproject.toml` to automatically update the version string in `agent_docstrings/__init__.py`, `pyproject.toml`, and `CHANGELOG.md`.
 
-**Note**: Per project configuration, this tool only modifies the files. You will need to commit and tag the changes manually after bumping the version.
+**Note**: Running `bump-my-version`, you need to create a release branch and a pull request to `master`. The process of tagging, creating a GitHub Release, and publishing to PyPI is automated. For full details, see the [Contribution Guide](CONTRIBUTING.md).
 
 ## Support the Project
 
@@ -337,11 +337,15 @@ Thank you for your support!
 
 ## Contributing
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+We welcome contributions! Please see our [**Contribution Guide**](CONTRIBUTING.md) for detailed instructions on how to get started, our development workflow, and coding standards.
+
+In short:
+
+1. Fork the repo and create your branch from `dev`.
+2. Add your feature or fix.
+3. Add/update tests.
+4. Update `CHANGELOG.md`.
+5. Submit a pull request to `dev`.
 
 ## License
 
diff --git a/pyproject.toml b/pyproject.toml
@@ -164,5 +164,5 @@ replace = '__version__ = "{new_version}"'
 
 [[tool.bumpversion.files]]
 filename = "CHANGELOG.md"
-search = "## [{current_version}]"
-replace = "## [{new_version}]\n\n### Header\n\n-   **subtitle**: describtion\n\n## [{current_version}]" 
+search = "## [NextRelease]"
+replace = "## [NextRelease]\n\n### Header\n\n-   **subtitle**: describtion\n\n## [{new_version}]" 
