Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
docs: add CONTRIBUTING.md
Greyson LaLonde185b69b83bc5
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.mdnew file mode 100644index 000000000..38ca22ad4--- /dev/null+++ b/.github/CONTRIBUTING.md@@ -0,0 +1,173 @@+# 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++### 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+- Link related issues where applicable++## 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).