From 44233fc7d1a0b29ff93929aee8f369da8acb80aa Mon Sep 17 00:00:00 2001 From: Luong NGUYEN Date: Fri, 9 Jan 2026 09:10:24 +0100 Subject: [PATCH] docs: Add comprehensive CONTRIBUTING.md guidelines and update README contributing section --- CONTRIBUTING.md | 336 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 22 +++- 2 files changed, 352 insertions(+), 6 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..44b93ec --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,336 @@ +# Contributing to Claude How To + +Thank you for your interest in contributing to this project! This guide will help you understand how to contribute effectively. + +## About This Project + +Claude How To is a visual, example-driven guide to Claude Code. We provide: +- **Mermaid diagrams** explaining how features work +- **Production-ready templates** you can use immediately +- **Real-world examples** with context and best practices +- **Progressive learning paths** from beginner to advanced + +## Types of Contributions + +### 1. New Examples or Templates +Add examples for existing features (slash commands, skills, hooks, etc.): +- Copy-paste ready code +- Clear explanations of how it works +- Use cases and benefits +- Troubleshooting tips + +### 2. Documentation Improvements +- Clarify confusing sections +- Fix typos and grammar +- Add missing information +- Improve code examples + +### 3. Feature Guides +Create guides for new Claude Code features: +- Step-by-step tutorials +- Architecture diagrams +- Common patterns and anti-patterns +- Real-world workflows + +### 4. Bug Reports +Report issues you encounter: +- Describe what you expected +- Describe what actually happened +- Include steps to reproduce +- Add relevant Claude Code version and OS + +### 5. Feedback and Suggestions +Help improve the guide: +- Suggest better explanations +- Point out gaps in coverage +- Recommend new sections or reorganization + +## Getting Started + +### 1. Fork and Clone +```bash +git clone https://github.com/luongnv89/claude-howto.git +cd claude-howto +``` + +### 2. Create a Branch +Use a descriptive branch name: +```bash +git checkout -b add/feature-name +git checkout -b fix/issue-description +git checkout -b docs/improvement-area +``` + +### 3. Set Up Your Environment +```bash +# Create virtual environment +python3 -m venv .venv +source .venv/bin/activate + +# Install pre-commit hooks (optional but recommended) +pip install pre-commit +pre-commit install + +# Run pre-commit checks manually +pre-commit run --all-files +``` + +## Directory Structure + +``` +├── 01-slash-commands/ # User-invoked shortcuts +├── 02-memory/ # Persistent context examples +├── 03-skills/ # Reusable capabilities +├── 04-subagents/ # Specialized AI assistants +├── 05-mcp/ # Model Context Protocol examples +├── 06-hooks/ # Event-driven automation +├── 07-plugins/ # Bundled features +├── 08-checkpoints/ # Session snapshots +├── 09-advanced-features/ # Planning, thinking, backgrounds +├── 10-cli/ # CLI reference +├── scripts/ # Build and utility scripts +└── README.md # Main guide +``` + +## How to Contribute Examples + +### Adding a Slash Command +1. Create a `.md` file in `01-slash-commands/` +2. Include: + - Clear description of what it does + - Use cases + - Installation instructions + - Usage examples + - Customization tips +3. Update `01-slash-commands/README.md` + +### Adding a Skill +1. Create a directory in `03-skills/` +2. Include: + - `SKILL.md` - Main documentation + - `scripts/` - Helper scripts if needed + - `templates/` - Prompt templates + - Example usage in README +3. Update `03-skills/README.md` + +### Adding a Subagent +1. Create a `.md` file in `04-subagents/` +2. Include: + - Agent purpose and capabilities + - System prompt structure + - Example use cases + - Integration examples +3. Update `04-subagents/README.md` + +### Adding MCP Configuration +1. Create a `.json` file in `05-mcp/` +2. Include: + - Configuration explanation + - Required environment variables + - Setup instructions + - Usage examples +3. Update `05-mcp/README.md` + +### Adding a Hook +1. Create a `.sh` file in `06-hooks/` +2. Include: + - Shebang and description + - Clear comments explaining logic + - Error handling + - Security considerations +3. Update `06-hooks/README.md` + +## Writing Guidelines + +### Markdown Style +- Use clear headings (H2 for sections, H3 for subsections) +- Keep paragraphs short and focused +- Use bullet points for lists +- Include code blocks with language specification +- Add blank lines between sections + +### Code Examples +- Make examples copy-paste ready +- Comment non-obvious logic +- Include both simple and advanced versions +- Show real-world use cases +- Highlight potential issues + +### Documentation +- Explain the "why" not just the "what" +- Include prerequisites +- Add troubleshooting sections +- Link to related topics +- Keep it beginner-friendly + +### JSON/YAML +- Use proper indentation (2 or 4 spaces consistently) +- Add comments explaining configuration +- Include validation examples + +### Diagrams +- Use Mermaid when possible +- Keep diagrams simple and readable +- Include descriptions below diagrams +- Link to relevant sections + +## Commit Guidelines + +Follow conventional commit format: +``` +type(scope): description + +[optional body] +``` + +Types: +- `feat`: New feature or example +- `fix`: Bug fix or correction +- `docs`: Documentation changes +- `refactor`: Code restructuring +- `style`: Formatting changes +- `test`: Test additions or changes +- `chore`: Build, dependencies, etc. + +Examples: +``` +feat(slash-commands): Add API documentation generator +docs(memory): Improve personal preferences example +fix(README): Correct table of contents link +docs(skills): Add comprehensive code review skill +``` + +## Before Submitting + +### Checklist +- [ ] Code follows project style and conventions +- [ ] New examples include clear documentation +- [ ] README files are updated (both local and root) +- [ ] No sensitive information (API keys, credentials) +- [ ] Examples are tested and working +- [ ] Links are verified and correct +- [ ] Files have proper permissions (scripts are executable) +- [ ] Commit message is clear and descriptive + +### Local Testing +```bash +# Check file formatting +pre-commit run --all-files + +# Verify links work (if applicable) +# Test examples manually with Claude Code + +# Review your changes +git diff + +# Test the EPUB generation (if docs changed) +uv run scripts/build_epub.py +``` + +## Pull Request Process + +1. **Create PR with clear description**: + - What does this add/fix? + - Why is it needed? + - Related issues (if any) + +2. **Include relevant details**: + - New feature? Include use cases + - Documentation? Explain improvements + - Examples? Show before/after + +3. **Link to issues**: + - Use `Closes #123` to auto-close related issues + +4. **Be patient with reviews**: + - Maintainers may suggest improvements + - Iterate based on feedback + - Final decision rests with maintainers + +## Code Review Process + +Reviewers will check: +- **Accuracy**: Does it work as described? +- **Quality**: Is it production-ready? +- **Consistency**: Does it follow project patterns? +- **Documentation**: Is it clear and complete? +- **Security**: Are there any vulnerabilities? + +## Reporting Issues + +### Bug Reports +Include: +- Claude Code version +- Operating system +- Steps to reproduce +- Expected behavior +- Actual behavior +- Screenshots if applicable + +### Feature Requests +Include: +- Use case or problem being solved +- Proposed solution +- Alternatives you've considered +- Additional context + +### Documentation Issues +Include: +- What's confusing or missing +- Suggested improvements +- Examples or references + +## Project Policies + +### Sensitive Information +- Never commit API keys, tokens, or credentials +- Use placeholder values in examples +- Include `.env.example` for configuration files +- Document required environment variables + +### Code Quality +- Keep examples focused and readable +- Avoid over-engineering solutions +- Include comments for non-obvious logic +- Test thoroughly before submitting + +### Intellectual Property +- Original content owned by author +- Project uses educational license +- Respect existing copyrights +- Provide attribution where needed + +## Getting Help + +- **Questions**: Open a discussion in GitHub Issues +- **General Help**: Check existing documentation +- **Development Help**: Review similar examples +- **Code Review**: Tag maintainers in PRs + +## Recognition + +Contributors are recognized in: +- README.md Contributors section +- GitHub contributors page +- Commit history + +## Code of Conduct + +Be respectful and inclusive: +- Welcome feedback gracefully +- Help others learn and grow +- Avoid harassment or discrimination +- Report issues to maintainers + +## License + +By contributing to this project, you agree that your contributions will be licensed under the same license as the project (Educational license). + +## Questions? + +- Check the [README](README.md) +- Review [LEARNING-ROADMAP.md](LEARNING-ROADMAP.md) +- Look at existing examples +- Open an issue for discussion + +Thank you for contributing! 🙏 diff --git a/README.md b/README.md index dd6f924..61ec243 100644 --- a/README.md +++ b/README.md @@ -758,13 +758,23 @@ Claude: ## Contributing -Found an issue or want to contribute an example? +Found an issue or want to contribute an example? We'd love your help! -1. Create an issue describing the example -2. Follow existing structure and patterns -3. Include comprehensive README -4. Test thoroughly -5. Submit pull request +**Please read [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines on:** +- Types of contributions (examples, docs, features, bugs, feedback) +- How to set up your development environment +- Directory structure and how to add content +- Writing guidelines and best practices +- Commit and PR process +- Code of conduct + +Quick start: +1. Fork and clone the repository +2. Create a descriptive branch (`add/feature-name`, `fix/bug`, `docs/improvement`) +3. Make your changes following the guidelines +4. Submit a pull request with a clear description + +**Need help?** Open an issue or discussion, and we'll guide you through the process. ---