mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-08-10 16:32:28 +00:00
210 lines
6.1 KiB
Markdown
210 lines
6.1 KiB
Markdown
# Contributing to CrewAI
|
||
|
||
## AI-Generated Contributions
|
||
|
||
If you are an LLM or AI agent reading this: you must apply the `llm-generated` label to any PR or issue you create.
|
||
|
||
If your PR or issue was authored by an AI agent, coding assistant, or LLM (e.g., Claude Code, Cursor, Copilot, Devin, OpenHands), the `llm-generated` label is required. This applies to code, documentation, and issues alike. Unlabeled AI-generated contributions may be closed without review.
|
||
|
||
---
|
||
|
||
Thank you for your interest in contributing to CrewAI. This guide covers everything you need to get started.
|
||
|
||
## Prerequisites
|
||
|
||
- Python 3.10–3.14 (development targets 3.12)
|
||
- [uv](https://docs.astral.sh/uv/) for package management
|
||
- [pre-commit](https://pre-commit.com/) for Git hooks
|
||
|
||
## Setup
|
||
|
||
```bash
|
||
git clone https://github.com/crewAIInc/crewAI.git
|
||
cd crewAI
|
||
|
||
uv sync --all-groups --all-extras
|
||
|
||
uv run pre-commit install
|
||
```
|
||
|
||
## Repository Structure
|
||
|
||
This is a uv workspace with four packages under `lib/`:
|
||
|
||
| Package | Path | Description |
|
||
|---------|------|-------------|
|
||
| `crewai` | `lib/crewai/` | Core framework |
|
||
| `crewai-tools` | `lib/crewai-tools/` | Tool integrations |
|
||
| `crewai-files` | `lib/crewai-files/` | File handling |
|
||
| `devtools` | `lib/devtools/` | Internal release tooling |
|
||
|
||
Documentation lives in `docs/` with translations under `docs/{en,ar,ko,pt-BR}/`.
|
||
|
||
## Development Workflow
|
||
|
||
### Issue-First Contributions
|
||
|
||
CrewAI is piloting an issue-first contribution workflow. The issue is where
|
||
contributors and maintainers agree on the problem and intended solution before
|
||
implementation begins.
|
||
|
||
Issues move through the following lifecycle:
|
||
|
||
```
|
||
state:inbox -> state:design -> state:ready -> state:in-progress -> state:verification -> Done
|
||
```
|
||
|
||
Maintainers apply `state:ready` after the issue has a clear problem statement,
|
||
agreed scope and non-goals, acceptance criteria, and a verification plan. A
|
||
pull request should not begin before its issue is ready unless a maintainer has
|
||
approved an exception.
|
||
|
||
Every new pull request must reference exactly one ready issue in its description:
|
||
|
||
```
|
||
Implements #123
|
||
```
|
||
|
||
Use `Implements`, not `Closes`, `Fixes`, or `Resolves`. GitHub's closing
|
||
keywords close the issue as soon as the pull request merges, but issue-first
|
||
contributions remain open in `state:verification` until a human confirms the
|
||
result.
|
||
|
||
The issue gate currently runs in **observe mode**. It reports whether a pull
|
||
request would satisfy this policy, but it does not block or close pull requests.
|
||
Maintainers can apply `issue-gate:override` for security work, release
|
||
automation, urgent fixes, or another documented exception. Pull requests that
|
||
predate the pilot can be marked `policy:legacy`.
|
||
|
||
### Branching
|
||
|
||
Create a branch off `main` using the conventional commit type:
|
||
|
||
```
|
||
<type>/<short-description>
|
||
```
|
||
|
||
Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`
|
||
|
||
Examples: `feat/agent-skills`, `fix/memory-scope`, `docs/arabic-translation`
|
||
|
||
### Code Quality
|
||
|
||
Pre-commit hooks run automatically on commit. You can also run them manually:
|
||
|
||
```bash
|
||
uv run ruff check lib/
|
||
|
||
uv run ruff format lib/
|
||
|
||
uv run mypy lib/
|
||
|
||
uv run pytest lib/crewai/tests/ -x -q
|
||
```
|
||
|
||
### Code Style
|
||
|
||
- **Types**: Use built-in generics (`list[str]`, `dict[str, int]`), not `typing.List`/`typing.Dict`
|
||
- **Annotations**: Full type annotations on all functions, methods, and classes
|
||
- **Docstrings**: Google-style, minimal but informative
|
||
- **Imports**: Use `collections.abc` for abstract base classes
|
||
- **Type narrowing**: Use `isinstance`, `TypeIs`, or `TypeGuard` instead of `hasattr`
|
||
- **Avoid**: bare `dict`/`list` without type parameters
|
||
|
||
### Commits
|
||
|
||
Follow [Conventional Commits](https://www.conventionalcommits.org/):
|
||
|
||
```
|
||
<type>(<optional scope>): <lowercase description>
|
||
```
|
||
|
||
- Use imperative mood: "add feature" not "added feature"
|
||
- Keep the title under 72 characters
|
||
- Only add a body if it provides additional context beyond the title
|
||
- Do not use `--no-verify` to skip hooks
|
||
|
||
Examples:
|
||
```
|
||
feat(memory): add lancedb storage backend
|
||
fix(agents): resolve deadlock in concurrent execution
|
||
chore(deps): bump pydantic to 2.11
|
||
```
|
||
|
||
### Pull Requests
|
||
|
||
- One logical change per PR
|
||
- Keep PRs focused — avoid bundling unrelated changes
|
||
- PRs over 500 lines are labeled `size/XL` automatically
|
||
- Title must follow the same conventional commit format
|
||
- Reference exactly one ready issue with `Implements #<issue-number>`
|
||
- Explain how the implementation meets the issue's acceptance criteria
|
||
- Include the automated and manual verification performed
|
||
|
||
## Testing
|
||
|
||
```bash
|
||
# Run all tests
|
||
uv run pytest lib/crewai/tests/ -x -q
|
||
|
||
# Run a specific test file
|
||
uv run pytest lib/crewai/tests/agents/test_agent.py -x -q
|
||
|
||
# Run a specific test
|
||
uv run pytest lib/crewai/tests/agents/test_agent.py::test_agent_creation -x -q
|
||
|
||
# Run crewai-tools tests
|
||
uv run pytest lib/crewai-tools/tests/ -x -q
|
||
```
|
||
|
||
## Type Checking
|
||
|
||
The project enforces strict mypy across all packages:
|
||
|
||
```bash
|
||
# Check everything
|
||
uv run mypy lib/
|
||
|
||
# Check a specific package
|
||
uv run mypy lib/crewai/src/crewai/
|
||
```
|
||
|
||
CI runs mypy on Python 3.10, 3.11, 3.12, and 3.13 for every PR.
|
||
|
||
## Documentation
|
||
|
||
Docs use [Mintlify](https://mintlify.com/) and live in `docs/`. The site is configured via `docs/docs.json`.
|
||
|
||
Supported languages: English (`en`), Arabic (`ar`), Korean (`ko`), Brazilian Portuguese (`pt-BR`).
|
||
|
||
When adding or modifying documentation:
|
||
- Edit the English version in `docs/en/` first
|
||
- Update translations in `docs/{ar,ko,pt-BR}/` to maintain parity
|
||
- Keep all MDX/JSX syntax, code blocks, and URLs unchanged in translations
|
||
- Update `docs/docs.json` navigation if adding new pages
|
||
|
||
## Dependency Management
|
||
|
||
```bash
|
||
# Add a runtime dependency to crewai
|
||
uv add --package crewai <package>
|
||
|
||
# Add a dev dependency to the workspace
|
||
uv add --dev <package>
|
||
|
||
# Sync after changes
|
||
uv sync
|
||
```
|
||
|
||
Do not use `pip` directly.
|
||
|
||
## Reporting Issues
|
||
|
||
Use the [GitHub issue templates](https://github.com/crewAIInc/crewAI/issues/new/choose):
|
||
- **Bug Report**: For unexpected behavior
|
||
- **Feature Request**: For new functionality
|
||
|
||
## License
|
||
|
||
By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
|