225 lines
6.1 KiB
Markdown
225 lines
6.1 KiB
Markdown
# Contributing to Claude Cookbooks
|
|
|
|
Thank you for your interest in contributing to the Claude Cookbooks! This guide will help you get started with development and ensure your contributions meet our quality standards.
|
|
|
|
## Development Setup
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.11 or higher
|
|
- [uv](https://docs.astral.sh/uv/) package manager (recommended) or pip
|
|
|
|
### Quick Start
|
|
|
|
1. **Install uv** (recommended package manager):
|
|
```bash
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
```
|
|
|
|
Or with Homebrew:
|
|
```bash
|
|
brew install uv
|
|
```
|
|
|
|
2. **Clone the repository**:
|
|
```bash
|
|
git clone https://github.com/anthropics/anthropic-cookbook.git
|
|
cd anthropic-cookbook
|
|
```
|
|
|
|
3. **Set up the development environment**:
|
|
```bash
|
|
# Create virtual environment and install dependencies
|
|
uv sync --all-extras
|
|
|
|
# Or with pip:
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
4. **Install pre-commit hooks**:
|
|
```bash
|
|
uv run pre-commit install
|
|
# Or: pre-commit install
|
|
```
|
|
|
|
5. **Set up your API key**:
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env and add your Claude API key
|
|
```
|
|
|
|
## Quality Standards
|
|
|
|
This repository uses automated tools to maintain code quality:
|
|
|
|
### The Notebook Validation Stack
|
|
|
|
- **[nbconvert](https://nbconvert.readthedocs.io/)**: Notebook execution for testing
|
|
- **[ruff](https://docs.astral.sh/ruff/)**: Fast Python linter and formatter with native Jupyter support
|
|
- **Claude AI Review**: Intelligent code review using Claude
|
|
|
|
**Note**: Notebook outputs are intentionally kept in this repository as they demonstrate expected results for users.
|
|
|
|
### Claude Code Slash Commands
|
|
|
|
This repository includes slash commands that work in both Claude Code (for local development) and GitHub Actions CI. These commands are automatically available when you work in this repository with Claude Code.
|
|
|
|
**Available Commands**:
|
|
- `/link-review` - Validate links in markdown and notebooks
|
|
- `/model-check` - Verify Claude model usage is current
|
|
- `/notebook-review` - Comprehensive notebook quality check
|
|
|
|
**Usage in Claude Code**:
|
|
```bash
|
|
# Run the same validations that CI will run
|
|
/notebook-review skills/my-notebook.ipynb
|
|
/model-check
|
|
/link-review README.md
|
|
```
|
|
|
|
These commands use the exact same validation logic as our CI pipeline, helping you catch issues before pushing. The command definitions are stored in `.claude/commands/` for both local and CI use.
|
|
|
|
### Before Committing
|
|
|
|
1. **Run quality checks**:
|
|
```bash
|
|
uv run ruff check skills/ --fix
|
|
uv run ruff format skills/
|
|
|
|
uv run python scripts/validate_notebooks.py
|
|
```
|
|
|
|
3. **Test notebook execution** (optional, requires API key):
|
|
```bash
|
|
uv run jupyter nbconvert --to notebook \
|
|
--execute skills/classification/guide.ipynb \
|
|
--ExecutePreprocessor.kernel_name=python3 \
|
|
--output test_output.ipynb
|
|
```
|
|
|
|
### Pre-commit Hooks
|
|
|
|
Pre-commit hooks will automatically run before each commit to ensure code quality:
|
|
|
|
- Format code with ruff
|
|
- Validate notebook structure
|
|
|
|
If a hook fails, fix the issues and try committing again.
|
|
|
|
## Contribution Guidelines
|
|
|
|
### Notebook Best Practices
|
|
|
|
1. **Use environment variables for API keys**:
|
|
```python
|
|
import os
|
|
api_key = os.environ.get("ANTHROPIC_API_KEY")
|
|
```
|
|
|
|
2. **Use current Claude models**:
|
|
- Use model aliases for better maintainability when available
|
|
- Latest Haiku model: `claude-haiku-4-5-20251001` (Haiku 4.5)
|
|
- Check current models at: https://docs.claude.com/en/docs/about-claude/models/overview
|
|
- Claude will automatically validate model usage in PR reviews
|
|
|
|
3. **Keep notebooks focused**:
|
|
- One concept per notebook
|
|
- Clear explanations and comments
|
|
- Include expected outputs as markdown cells
|
|
|
|
4. **Test your notebooks**:
|
|
- Ensure they run from top to bottom without errors
|
|
- Use minimal tokens for example API calls
|
|
- Include error handling
|
|
|
|
### Git Workflow
|
|
|
|
1. **Create a feature branch**:
|
|
```bash
|
|
git checkout -b <your-name>/<feature-description>
|
|
# Example: git checkout -b alice/add-rag-example
|
|
```
|
|
|
|
2. **Use conventional commits**:
|
|
```bash
|
|
# Format: <type>(<scope>): <subject>
|
|
|
|
# Types:
|
|
feat # New feature
|
|
fix # Bug fix
|
|
docs # Documentation
|
|
style # Formatting
|
|
refactor # Code restructuring
|
|
test # Tests
|
|
chore # Maintenance
|
|
ci # CI/CD changes
|
|
|
|
# Examples:
|
|
git commit -m "feat(skills): add text-to-sql notebook"
|
|
git commit -m "fix(api): use environment variable for API key"
|
|
git commit -m "docs(readme): update installation instructions"
|
|
```
|
|
|
|
3. **Keep commits atomic**:
|
|
- One logical change per commit
|
|
- Write clear, descriptive messages
|
|
- Reference issues when applicable
|
|
|
|
4. **Push and create PR**:
|
|
```bash
|
|
git push -u origin your-branch-name
|
|
gh pr create # Or use GitHub web interface
|
|
```
|
|
|
|
### Pull Request Guidelines
|
|
|
|
1. **PR Title**: Use conventional commit format
|
|
2. **Description**: Include:
|
|
- What changes you made
|
|
- Why you made them
|
|
- How to test them
|
|
- Related issue numbers
|
|
3. **Keep PRs focused**: One feature/fix per PR
|
|
4. **Respond to feedback**: Address review comments promptly
|
|
|
|
## Testing
|
|
|
|
### Local Testing
|
|
|
|
Run the validation suite:
|
|
|
|
```bash
|
|
# Check all notebooks
|
|
uv run python scripts/validate_notebooks.py
|
|
|
|
# Run pre-commit on all files
|
|
uv run pre-commit run --all-files
|
|
```
|
|
|
|
### CI/CD
|
|
|
|
Our GitHub Actions workflows will automatically:
|
|
|
|
- Validate notebook structure
|
|
- Lint code with ruff
|
|
- Test notebook execution (for maintainers)
|
|
- Check links
|
|
- Claude reviews code and model usage
|
|
|
|
External contributors will have limited API testing to conserve resources.
|
|
|
|
## Getting Help
|
|
|
|
- **Issues**: [GitHub Issues](https://github.com/anthropics/anthropic-cookbook/issues)
|
|
- **Discussions**: [GitHub Discussions](https://github.com/anthropics/anthropic-cookbook/discussions)
|
|
- **Discord**: [Anthropic Discord](https://www.anthropic.com/discord)
|
|
|
|
## Security
|
|
|
|
- Never commit API keys or secrets
|
|
- Use environment variables for sensitive data
|
|
- Report security issues privately to security@anthropic.com
|
|
|
|
## License
|
|
|
|
By contributing, you agree that your contributions will be licensed under the same license as the project (MIT License). |