ljwx-children/CONTRIBUTING.md

Contributing to Gold Template

First off, thank you for considering contributing to Gold Template! 🎉

This document provides guidelines for contributing to this project. Following these guidelines helps maintain quality and makes the contribution process smooth for everyone.

---

📜 Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors, regardless of experience level, background, or identity.

Our Standards

Positive behaviors include:

• Using welcoming and inclusive language
• Being respectful of differing viewpoints and experiences
• Gracefully accepting constructive criticism
• Focusing on what is best for the community
• Showing empathy towards other community members

Unacceptable behaviors include:

• Trolling, insulting/derogatory comments, and personal attacks
• Public or private harassment
• Publishing others' private information without permission
• Other conduct which could reasonably be considered inappropriate

---

🚀 How Can I Contribute?

1. Reporting Bugs

Before submitting a bug report:

• Check the existing issues to avoid duplicates
• Collect information about the bug:
  • Template version (check TEMPLATE-READY-SUMMARY.md)
  • OS and version (macOS, Linux, Windows)
  • Python version (python3 --version)
  • GitHub CLI version (gh --version)
  • Steps to reproduce
  • Expected vs actual behavior
  • Error messages and logs

Submit a bug report:

# Use the bug report template
gh issue create --template bug_report.md

Include:

• Clear, descriptive title
• Detailed reproduction steps
• Expected behavior
• Actual behavior
• Environment details
• Screenshots (if applicable)
• Relevant logs

2. Suggesting Enhancements

Before submitting an enhancement:

• Check if it's already suggested in issues
• Consider if it fits the template's scope and philosophy
• Think about how it benefits the broader community

Submit an enhancement:

# Use the feature request template
gh issue create --template feature_request.md

Include:

• Clear use case and motivation
• Detailed description of the proposed change
• Possible implementation approach
• Alternatives considered
• Impact on existing features

3. Contributing Code

First-Time Contributors

Good first issues:

• Look for issues labeled good first issue
• Documentation improvements
• Adding examples
• Fixing typos
• Adding tests

Example:

# Find beginner-friendly issues
gh issue list --label "good first issue"

Development Process

Step 1: Fork and Clone

# Fork the repository on GitHub
gh repo fork BrunoGaoSZ/gold-template --clone

# Navigate to the directory
cd gold-template

# Add upstream remote
git remote add upstream https://github.com/BrunoGaoSZ/gold-template.git

Step 2: Create a Branch

# Update your fork
git fetch upstream
git checkout main
git merge upstream/main

# Create a feature branch
git checkout -b feature/your-feature-name

# Or for a bug fix
git checkout -b bugfix/issue-123-description

Step 3: Make Your Changes

Follow the coding standards:

# Install dependencies
pip install -r requirements.txt

# Make your changes
# ...

# Format code
black backend/ tests/ .claude/

# Lint code
flake8 backend/ tests/ .claude/

# Type check
mypy backend/

# Run tests
pytest tests/ --cov=backend --cov-report=html

# Security scan
bandit -r backend/

Step 4: Commit Your Changes

Follow the commit message convention:

git add .

git commit -m "feat(component): add new feature

- Detailed description of what changed
- Why the change was needed
- Any breaking changes or migration notes

Closes #123

🤖 Generated with Claude Code
Co-Authored-By: Your Name <[email protected]>"

Commit Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• style: Code style (formatting, no logic change)
• refactor: Code refactoring
• test: Adding or updating tests
• chore: Build process or auxiliary tools

Step 5: Push and Create PR

# Push your branch
git push origin feature/your-feature-name

# Create a pull request
gh pr create --fill

PR Requirements:

• Code follows style guidelines (black, flake8, mypy)
• Tests added/updated (maintain >80% coverage)
• Documentation updated (if applicable)
• Commit messages follow convention
• No breaking changes (or clearly documented)
• CI/CD passes (all checks green)
• Blueprint compliance (if applicable)

Code Review Process

1. Automated Checks - CI/CD runs tests, linting, security scans
2. Maintainer Review - Code review by project maintainers
3. Feedback Iteration - Address review comments
4. Approval & Merge - Merged after approval

Response Time:

• Initial review: Within 3-5 business days
• Follow-up reviews: Within 2 business days

---

🎯 Contribution Areas

High-Impact Contributions

1. SDLC Console Enhancements

   • New GitHub Projects views
   • Additional custom fields
   • Workflow automations
   • Dashboard improvements

2. Claude Code Skills

   • New skills development
   • Existing skills improvements
   • Integration examples
   • Documentation

3. Infrastructure as Code

   • Additional cloud providers (GCP, Azure)
   • New Terraform modules
   • Kubernetes enhancements
   • Argo CD workflows

4. Observability

   • New Grafana dashboards
   • Prometheus metrics
   • Loki log queries
   • Tempo trace examples

5. Documentation

   • Translation to other languages
   • Video tutorials
   • Blog posts
   • Use case examples

6. Testing

   • Unit tests
   • Integration tests
   • E2E tests
   • Performance tests

7. CI/CD

   • New security tools
   • Performance optimizations
   • Additional platforms (GitLab CI, CircleCI)
   • Deployment strategies

Examples of Past Contributions

✅ "Add GCP Terraform modules for multi-cloud support" (#42)
✅ "Create /deployment-analyzer skill for pre-deploy checks" (#38)
✅ "Add English translation for all documentation" (#35)
✅ "Implement chaos engineering tests with Chaos Mesh" (#31)
✅ "Create video tutorial series (10 episodes)" (#28)

---

📋 Style Guides

Python Style Guide

Follow PEP 8 with these specifics:

# Use Black for formatting (line length: 88)
black backend/ tests/

# Type hints for all functions
def process_data(input_data: dict[str, Any]) -> list[str]:
    """Process input data and return results.

    Args:
        input_data: Dictionary containing data to process

    Returns:
        List of processed strings

    Raises:
        ValueError: If input_data is empty
    """
    if not input_data:
        raise ValueError("input_data cannot be empty")

    return [str(v) for v in input_data.values()]

# Use async for I/O-bound operations
async def fetch_user(user_id: int) -> User:
    """Fetch user from database asynchronously."""
    async with get_session() as session:
        result = await session.execute(
            select(User).where(User.id == user_id)
        )
        return result.scalar_one_or_none()

# Use context managers for resources
async with get_session() as session:
    async with session.begin():
        # Database operations
        pass

Bash Script Style Guide

#!/bin/bash
#
# Script description
# Usage: ./script.sh [options]

set -e  # Exit on error
set -u  # Exit on undefined variable
set -o pipefail  # Fail on pipe errors

# Colors for output
readonly RED='\033[0;31m'
readonly GREEN='\033[0;32m'
readonly YELLOW='\033[1;33m'
readonly NC='\033[0m'  # No Color

# Functions
log_info() {
    echo -e "${GREEN}✓${NC} $1"
}

log_error() {
    echo -e "${RED}✗${NC} $1" >&2
}

# Main logic
main() {
    log_info "Starting script..."
    # ...
}

# Run main
main "$@"

Documentation Style Guide

Markdown:

• Use GitHub-flavored markdown
• Include code examples with language tags
• Add table of contents for long documents
• Use emojis sparingly for visual hierarchy
• Link to relevant sections/files

API Documentation:

• Use docstrings for all public functions/classes
• Include examples in docstrings
• Keep FastAPI endpoint documentation up-to-date

Example:

# Feature Name

## Overview

Brief description of the feature.

## Quick Start

```bash
# Example command
./script.sh --option value

Detailed Guide

Prerequisites

• Requirement 1
• Requirement 2

Step 1: Setup

Detailed instructions...

Step 2: Configuration

Configuration details...

Examples

Example 1: Basic Usage

# Python code example
result = process_data({"key": "value"})

Example 2: Advanced Usage

# Advanced example
async with AsyncClient() as client:
    result = await client.fetch()

Troubleshooting

Common Issue 1

Problem: Description Solution: How to fix

See Also

• Related Doc 1
• Related Doc 2

---

## 🧪 Testing Guidelines

### Test Coverage Requirements

- **Overall:** >80% coverage
- **Critical paths:** >95% coverage (models, API endpoints)
- **New code:** 100% coverage

### Test Structure

```python
# tests/unit/test_feature.py
import pytest
from backend.feature import process_data

class TestProcessData:
    """Test suite for process_data function."""

    def test_process_data_success(self):
        """Test successful data processing."""
        # Arrange
        input_data = {"key": "value"}

        # Act
        result = process_data(input_data)

        # Assert
        assert result == ["value"]

    def test_process_data_empty_input(self):
        """Test that empty input raises ValueError."""
        # Arrange
        input_data = {}

        # Act & Assert
        with pytest.raises(ValueError, match="cannot be empty"):
            process_data(input_data)

    @pytest.mark.parametrize("input_data,expected", [
        ({"a": 1}, ["1"]),
        ({"a": 1, "b": 2}, ["1", "2"]),
    ])
    def test_process_data_parametrized(self, input_data, expected):
        """Test process_data with various inputs."""
        result = process_data(input_data)
        assert result == expected

Running Tests

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=backend --cov-report=html

# Run specific test
pytest tests/unit/test_feature.py::TestProcessData::test_process_data_success -v

# Run tests in parallel
pytest tests/ -n auto

---

🔒 Security Guidelines

Reporting Security Vulnerabilities

DO NOT open a public issue for security vulnerabilities.

Instead, email: [email protected]

Include:

• Description of the vulnerability
• Steps to reproduce
• Potential impact
• Suggested fix (if any)

Response Time: Within 48 hours

Security Best Practices

# ✅ DO: Use parameterized queries
stmt = select(User).where(User.username == username)
result = await session.execute(stmt)

# ❌ DON'T: String concatenation (SQL injection risk)
query = f"SELECT * FROM users WHERE username = '{username}'"

# ✅ DO: Use environment variables for secrets
SECRET_KEY = os.getenv("SECRET_KEY")

# ❌ DON'T: Hardcode secrets
SECRET_KEY = "hardcoded-secret-key"  # NEVER DO THIS

# ✅ DO: Validate and sanitize input
from pydantic import BaseModel, validator

class UserInput(BaseModel):
    username: str

    @validator("username")
    def validate_username(cls, v):
        if not v.isalnum():
            raise ValueError("Username must be alphanumeric")
        return v

---

📚 Documentation Requirements

When to Update Documentation

Update documentation when:

• Adding new features
• Changing existing behavior
• Fixing bugs that affect usage
• Adding new configuration options
• Creating new Claude Code skills

Documentation Checklist

• Update relevant .md files in docs/
• Update README.md (if user-facing change)
• Update API docs (if endpoint changed)
• Add examples
• Update CHANGELOG.md
• Update CLAUDE.md (if affects Claude Code workflow)

---

🎯 PR Review Checklist

Before requesting review, ensure:

Code Quality:

• Black formatting applied
• Flake8 passes
• MyPy passes
• No security warnings (Bandit)

Testing:

• All tests pass
• New tests added for new features
• Coverage >80% (overall), 100% (new code)

Documentation:

• Code documented (docstrings)
• User-facing changes documented
• Examples added
• CHANGELOG.md updated

Git:

• Commits follow convention
• Branch up-to-date with main
• No merge conflicts

CI/CD:

• All GitHub Actions checks pass
• Security scans pass
• Performance tests pass

---

🙏 Recognition

All contributors will be:

• Added to CONTRIBUTORS.md
• Mentioned in release notes
• Thanked in the community

Types of Contributions:

• 💻 Code
• 📖 Documentation
• 🎨 Design
• 🐛 Bug reports
• 💡 Ideas
• 🌍 Translation
• 📹 Tutorials

---

📬 Communication

GitHub Discussions

Use GitHub Discussions for:

• Questions about usage
• Feature ideas and brainstorming
• Showcasing projects built with the template
• General discussions

GitHub Issues

Use GitHub Issues for:

• Bug reports
• Feature requests
• Documentation improvements
• Performance issues

Pull Requests

Use Pull Requests for:

• Code contributions
• Documentation updates
• Bug fixes

---

🎓 Learning Resources

New to Contributing?

• First Contributions
• How to Contribute to Open Source
• GitHub Flow

Project-Specific:

• FastAPI Documentation
• SQLAlchemy 2.0 Tutorial
• Kubernetes Documentation
• Claude Code Guide

---

📄 License

By contributing to Gold Template, you agree that your contributions will be licensed under the MIT License.

---

❓ Questions?

If you have questions:

1. Check existing documentation
2. Search GitHub Issues
3. Ask in GitHub Discussions
4. Contact maintainers

---

Thank you for contributing to Gold Template! 🙌

Template Version: 1.0.0 Last Updated: 2025-12-31