docs: Add comprehensive PR prefix and automation documentation
- Update CONTRIBUTING.md with detailed PR prefix system explanation - Add automation workflow documentation to docs/contributing/workflows.md - Create new user-friendly contributing guide at docs/user-guides/contributing-guide.md - Include Mermaid diagrams for workflow visualization - Document Docker testing combinations and image tagging strategy - Add best practices and common mistakes to avoid This provides clear guidance for contributors on using the automated versioning and Docker build system effectively. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Patryk Ciechanski
@@ -127,7 +127,52 @@ The GitHub Actions workflow:
|
||||
3. **Make your changes**
|
||||
4. **Add/update tests**
|
||||
5. **Run tests locally**: Ensure unit tests pass
|
||||
6. **Submit PR**: Include description of changes
|
||||
6. **Choose appropriate PR title prefix** (see below)
|
||||
7. **Submit PR**: Include description of changes
|
||||
|
||||
### PR Title Prefixes and Automation
|
||||
|
||||
The project uses automated versioning and Docker builds based on PR title prefixes:
|
||||
|
||||
#### Version Bumping Prefixes (trigger version bump + Docker build):
|
||||
- `feat: <description>` - New features → **MINOR** version bump (1.X.0)
|
||||
- `fix: <description>` - Bug fixes → **PATCH** version bump (1.0.X)
|
||||
- `breaking: <description>` - Breaking changes → **MAJOR** version bump (X.0.0)
|
||||
- `perf: <description>` - Performance improvements → **PATCH** version bump
|
||||
- `refactor: <description>` - Code refactoring → **PATCH** version bump
|
||||
|
||||
#### Non-Version Prefixes (no version bump):
|
||||
- `docs: <description>` - Documentation only
|
||||
- `chore: <description>` - Maintenance tasks
|
||||
- `test: <description>` - Test additions/changes
|
||||
- `ci: <description>` - CI/CD changes
|
||||
- `style: <description>` - Code style changes
|
||||
|
||||
#### Docker Build Options:
|
||||
For contributors who want to test Docker builds without version bumps:
|
||||
- `docker: <description>` - Force Docker build only
|
||||
- `docs+docker: <description>` - Documentation + Docker build
|
||||
- `chore+docker: <description>` - Maintenance + Docker build
|
||||
- `test+docker: <description>` - Tests + Docker build
|
||||
- `ci+docker: <description>` - CI changes + Docker build
|
||||
- `style+docker: <description>` - Style changes + Docker build
|
||||
|
||||
#### What Happens When PR is Merged:
|
||||
|
||||
**For version bumping prefixes:**
|
||||
1. Version in `config.py` is automatically updated
|
||||
2. Git tag is created (e.g., `v1.2.0`)
|
||||
3. GitHub release is published
|
||||
4. Docker image is built and pushed to GHCR with version tag
|
||||
|
||||
**For Docker build prefixes:**
|
||||
1. Docker image is built and pushed to GHCR
|
||||
2. Image tagged with `pr-{number}` and `main-{commit-sha}`
|
||||
3. No version bump or release created
|
||||
|
||||
**For standard non-version prefixes:**
|
||||
1. Changes are merged without automation
|
||||
2. No version bump, Docker build, or release
|
||||
|
||||
### Code Standards
|
||||
|
||||
|
||||
@@ -94,6 +94,7 @@ This project follows the **[CLAUDE.md Collaboration Framework](../CLAUDE.md)** w
|
||||
### Project Information
|
||||
- **[Main README](../README.md)** - Project overview and quick start
|
||||
- **[Contributing Guidelines](../CONTRIBUTING.md)** - How to contribute to the project
|
||||
- **[Quick Contributing Guide](user-guides/contributing-guide.md)** - Simple guide for new contributors
|
||||
- **[License](../LICENSE)** - MIT License details
|
||||
- **[Collaboration Framework](../CLAUDE.md)** - Development collaboration patterns
|
||||
|
||||
|
||||
@@ -4,6 +4,91 @@
|
||||
|
||||
This document outlines the development workflows and processes for the Gemini MCP Server project, following the collaboration patterns defined in CLAUDE.md and integrating with the Memory Bank system for context preservation.
|
||||
|
||||
## Pull Request Automation & Versioning
|
||||
|
||||
### Automated Workflows
|
||||
|
||||
The project implements automated versioning and Docker builds based on PR title prefixes, enabling seamless releases and testing.
|
||||
|
||||
#### PR Title Prefix System
|
||||
|
||||
**Version Bumping Prefixes** (creates releases):
|
||||
- `feat:` → Minor version bump (1.X.0) + Docker build + GitHub release
|
||||
- `fix:` → Patch version bump (1.0.X) + Docker build + GitHub release
|
||||
- `breaking:` → Major version bump (X.0.0) + Docker build + GitHub release
|
||||
- `perf:` → Patch version bump + Docker build + GitHub release
|
||||
- `refactor:` → Patch version bump + Docker build + GitHub release
|
||||
|
||||
**Non-Version Prefixes** (no releases):
|
||||
- `docs:` → Documentation changes only
|
||||
- `chore:` → Maintenance tasks
|
||||
- `test:` → Test updates
|
||||
- `ci:` → CI/CD pipeline changes
|
||||
- `style:` → Code formatting/style
|
||||
|
||||
**Docker Build Combinations** (Docker without versioning):
|
||||
- `docker:` → Force Docker build only
|
||||
- `docs+docker:` → Documentation + Docker build
|
||||
- `chore+docker:` → Maintenance + Docker build
|
||||
- `test+docker:` → Test changes + Docker build
|
||||
- `ci+docker:` → CI changes + Docker build
|
||||
- `style+docker:` → Style changes + Docker build
|
||||
|
||||
#### Workflow Execution Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[PR Created] --> B[docker-test.yml]
|
||||
B --> C[test.yml]
|
||||
A --> C
|
||||
|
||||
D[PR Merged] --> E[auto-version.yml]
|
||||
E --> F{PR Title Analysis}
|
||||
|
||||
F -->|feat:, fix:, etc.| G[Version Bump]
|
||||
F -->|docker:, docs+docker:, etc.| H[Docker Build Flag]
|
||||
F -->|docs:, chore:, etc.| I[No Action]
|
||||
|
||||
G --> J[Create Git Tag]
|
||||
J --> K[build_and_publish_docker.yml]
|
||||
|
||||
H --> L[Repository Dispatch]
|
||||
L --> K
|
||||
|
||||
K --> M[Build & Push to GHCR]
|
||||
|
||||
G --> N[Create GitHub Release]
|
||||
```
|
||||
|
||||
#### Docker Image Tagging Strategy
|
||||
|
||||
**For Version Releases:**
|
||||
- `v1.2.3` - Semantic version tag
|
||||
- `latest` - Latest stable release
|
||||
|
||||
**For Docker-only Builds:**
|
||||
- `pr-{number}` - PR-specific tag (e.g., `pr-42`)
|
||||
- `main-{commit-sha}` - Commit-specific tag (e.g., `main-abc1234`)
|
||||
|
||||
#### Implementation Details
|
||||
|
||||
**Auto-version Workflow** (`.github/workflows/auto-version.yml`):
|
||||
1. Analyzes PR title for semantic prefix
|
||||
2. Updates `config.py` with new version
|
||||
3. Creates git tag and GitHub release
|
||||
4. Triggers Docker build via tag creation or repository dispatch
|
||||
|
||||
**Docker Build Workflow** (`.github/workflows/build_and_publish_docker.yml`):
|
||||
1. Triggered by git tags or repository dispatch
|
||||
2. Builds multi-platform Docker images
|
||||
3. Pushes to GitHub Container Registry (GHCR)
|
||||
4. Handles different tagging strategies based on trigger
|
||||
|
||||
**Docker Test Workflow** (`.github/workflows/docker-test.yml`):
|
||||
1. Runs on all PRs
|
||||
2. Validates Docker build without publishing
|
||||
3. Provides early feedback on containerization issues
|
||||
|
||||
## Core Development Workflow
|
||||
|
||||
### 1. Feature Development Process
|
||||
|
||||
181
docs/user-guides/contributing-guide.md
Normal file
181
docs/user-guides/contributing-guide.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# Contributing Guide for Users
|
||||
|
||||
## Quick Start for Contributors
|
||||
|
||||
This guide helps new contributors understand how to contribute to the Gemini MCP Server project effectively.
|
||||
|
||||
## Pull Request Guidelines
|
||||
|
||||
### Understanding PR Title Automation
|
||||
|
||||
The project uses automated workflows based on your PR title. Choose the right prefix to get the appropriate automation:
|
||||
|
||||
#### 🚀 **For New Features & Bug Fixes** (creates releases):
|
||||
```
|
||||
feat: Add new chat streaming functionality
|
||||
fix: Resolve memory leak in conversation history
|
||||
breaking: Remove deprecated tool parameters
|
||||
perf: Optimize token usage calculation
|
||||
refactor: Simplify error handling logic
|
||||
```
|
||||
|
||||
**What happens:** Version bump + GitHub release + Docker image published
|
||||
|
||||
#### 📝 **For Documentation & Maintenance** (no releases):
|
||||
```
|
||||
docs: Update installation instructions
|
||||
chore: Update dependencies
|
||||
test: Add integration tests for analyze tool
|
||||
ci: Improve workflow error handling
|
||||
style: Fix code formatting issues
|
||||
```
|
||||
|
||||
**What happens:** Changes merged, no automation triggered
|
||||
|
||||
#### 🐳 **For Testing Docker Changes** (Docker without releases):
|
||||
```
|
||||
docker: Test new Dockerfile optimization
|
||||
docs+docker: Update Docker guide and test image
|
||||
chore+docker: Update base image and test
|
||||
test+docker: Add Docker integration tests
|
||||
ci+docker: Update Docker workflow and test
|
||||
style+docker: Fix Dockerfile formatting and test
|
||||
```
|
||||
|
||||
**What happens:** Docker image built and published (tagged with PR number)
|
||||
|
||||
### Choosing the Right Prefix
|
||||
|
||||
**Ask yourself:**
|
||||
1. **Does this add/change functionality?** → Use `feat:` or `fix:`
|
||||
2. **Is this breaking existing behavior?** → Use `breaking:`
|
||||
3. **Is this just documentation/maintenance?** → Use `docs:`, `chore:`, etc.
|
||||
4. **Do I need to test Docker changes?** → Add `+docker` to any non-version prefix
|
||||
|
||||
### Examples by Change Type
|
||||
|
||||
#### Adding a New Tool
|
||||
```
|
||||
feat: Add sentiment analysis tool for code comments
|
||||
```
|
||||
|
||||
#### Fixing a Bug
|
||||
```
|
||||
fix: Correct timeout handling in thinkdeep tool
|
||||
```
|
||||
|
||||
#### Updating Documentation
|
||||
```
|
||||
docs: Add troubleshooting guide for Windows installation
|
||||
```
|
||||
|
||||
#### Testing Docker Changes
|
||||
```
|
||||
docs+docker: Update Docker configuration and test deployment
|
||||
```
|
||||
|
||||
#### Major Breaking Changes
|
||||
```
|
||||
breaking: Change MCP protocol response format for better compatibility
|
||||
```
|
||||
|
||||
## Docker Testing for Contributors
|
||||
|
||||
### When to Use Docker Build Combinations
|
||||
|
||||
**Use `+docker` suffix when:**
|
||||
- You've modified Dockerfile, docker-compose.yml, or Docker-related configs
|
||||
- You want to test the containerized version of your changes
|
||||
- You're updating Docker documentation and want to verify it works
|
||||
- You're making CI/CD changes that affect Docker builds
|
||||
|
||||
**Don't use `+docker` when:**
|
||||
- Your changes don't affect containerization
|
||||
- You're only updating code documentation
|
||||
- You're making simple code style changes
|
||||
|
||||
### How Docker Testing Works
|
||||
|
||||
1. **PR Creation:** Docker build test runs automatically (no publishing)
|
||||
2. **PR Merge with `+docker`:** Docker image built and pushed to GHCR
|
||||
3. **Image Tags:** Your image will be tagged as:
|
||||
- `pr-{number}` (e.g., `pr-42`)
|
||||
- `main-{commit-sha}` (e.g., `main-abc1234`)
|
||||
|
||||
### Testing Your Docker Image
|
||||
|
||||
After your PR is merged with a `+docker` prefix:
|
||||
|
||||
```bash
|
||||
# Pull your test image
|
||||
docker pull ghcr.io/patrykiti/gemini-mcp-server:pr-42
|
||||
|
||||
# Or use the commit-based tag
|
||||
docker pull ghcr.io/patrykiti/gemini-mcp-server:main-abc1234
|
||||
|
||||
# Test it locally
|
||||
docker run -it --rm ghcr.io/patrykiti/gemini-mcp-server:pr-42
|
||||
```
|
||||
|
||||
## Workflow Summary
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A[Choose PR Title] --> B{Type of Change?}
|
||||
|
||||
B -->|New Feature/Bug Fix| C[feat:/fix: prefix]
|
||||
B -->|Documentation Only| D[docs: prefix]
|
||||
B -->|Need Docker Test| E[prefix+docker:]
|
||||
|
||||
C --> F[Version Bump + Release + Docker]
|
||||
D --> G[Merge Only]
|
||||
E --> H[Docker Build Only]
|
||||
|
||||
F --> I[Published Release]
|
||||
G --> J[Updated Docs]
|
||||
H --> K[Test Docker Image]
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Writing Good PR Titles
|
||||
- **Be specific:** `feat: Add rate limiting to chat tool` not `feat: Update chat`
|
||||
- **Use imperative mood:** `fix: Resolve timeout issue` not `fixes timeout issue`
|
||||
- **Keep it concise:** Aim for 50 characters or less
|
||||
- **Include scope when helpful:** `feat(precommit): Add Python syntax validation`
|
||||
|
||||
### Common Mistakes to Avoid
|
||||
- ❌ `Update README` → ✅ `docs: Update installation requirements`
|
||||
- ❌ `Fix bug` → ✅ `fix: Resolve memory leak in conversation threading`
|
||||
- ❌ `feat: Add feature` → ✅ `feat: Add multi-language support for code analysis`
|
||||
- ❌ `docs: Update Docker and test it` → ✅ `docs+docker: Update container setup guide`
|
||||
|
||||
### Testing Your Changes
|
||||
|
||||
Before submitting a PR:
|
||||
|
||||
1. **Run local tests:**
|
||||
```bash
|
||||
python -m pytest tests/ --ignore=tests/test_live_integration.py -v
|
||||
black --check .
|
||||
ruff check .
|
||||
```
|
||||
|
||||
2. **Test Docker locally (if applicable):**
|
||||
```bash
|
||||
docker build -t test-image .
|
||||
docker run -it --rm test-image
|
||||
```
|
||||
|
||||
3. **Verify documentation builds:**
|
||||
- Check that any new documentation renders correctly
|
||||
- Ensure links work and examples are accurate
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Stuck on prefix choice?** Look at recent merged PRs for examples
|
||||
- **Docker build failing?** Check the docker-test workflow results in your PR
|
||||
- **Questions about automation?** Open a discussion or ask in your PR comments
|
||||
- **Need API access for testing?** Live integration tests are optional for contributors
|
||||
|
||||
Remember: The automation is designed to help maintain consistency and quality. When in doubt, choose the most conservative prefix and ask for guidance in your PR!
|
||||
Reference in New Issue
Block a user