docs+docker: Complete documentation infrastructure with Docker automation testing (#2)

* fix: Remove invalid colon in bash else statement - Fix bash syntax error in auto-version workflow - Remove Python-style colon from else statement - Resolves exit code 127 in version bump determination 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: Add Docker build combinations for non-versioning prefixes - Add support for prefix+docker combinations (docs+docker:, chore+docker:, etc.) - Enable Docker build for non-versioning changes when requested - Add repository_dispatch trigger for Docker workflow - Update Docker tagging for PR-based builds (pr-X, main-sha) - Update PR template with new prefix options This allows contributors to force Docker builds for documentation, maintenance, and other non-versioning changes when needed. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> * 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> --------- Co-authored-by: Patryk Ciechanski <patryk.ciechanski@inetum.com> Co-authored-by: Claude <noreply@anthropic.com>
2025-06-12 09:57:44 +02:00
parent bd58f3e532
commit 3c9127678c
7 changed files with 372 additions and 7 deletions
--- a/docs/user-guides/contributing-guide.md
+++ b/docs/user-guides/contributing-guide.md
@@ -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!