Skip to content

Latest commit

 

History

History
251 lines (166 loc) · 12.5 KB

CONTRIBUTING.md

File metadata and controls

251 lines (166 loc) · 12.5 KB
Raw

🐫 Welcome to CAMEL! 🐫

Thank you for your interest in contributing to the CAMEL project! 🎉 We're excited to have your support. As an open-source initiative in a rapidly evolving and open-ended field, we wholeheartedly welcome contributions of all kinds. Whether you want to introduce new features, enhance the infrastructure, improve documentation, asking issues, add more examples, implement state-of-the-art research ideas, or fix bugs, we appreciate your enthusiasm and efforts. 🙌 You are welcome to join our slack for more efficient communication. 💬

Join Our Community 🌍

Schedule an Introduction Call 📞

  • English speakers: here
  • Chinese speakers: here

Developer Meeting Time & Link 💻

  • English speakers: Mondays at 5 PM GMT+1. Join via Zoom: Meeting Link
  • Chinese Speakers: Mondays at 9 PM UTC+8. Join via Zoom: Meeting Link

Our Communication Channels 💬

Guidelines 📝

Contributing to the Code 👨‍💻👩‍💻

If you're eager to contribute to this project, that's fantastic! We're thrilled to have your support.

Make sure to mention any related issues and tag the relevant maintainers too. 💪

Before your pull request can be merged, it must pass the formatting, linting, and testing checks. You can find instructions on running these checks locally under the Common Actions section below. 🔍

Ensuring excellent documentation and thorough testing is absolutely crucial. Here are some guidelines to follow based on the type of contribution you're making:

  • If you fix a bug:

    • Add a relevant unit test when possible. These can be found in the test directory.

  • If you make an improvement:

    • Update any affected example console scripts in the examples directory, Gradio demos in the apps directory, and documentation in the docs directory.
    • Update unit tests when relevant.

  • If you add a feature:

    • Include unit tests in the test directory.
    • Add a demo script in the examples directory.

  • If you review the code:

    • Ensure responsible code review principles and cautious code approval.
    • Try to review not only the modified code snippets but also consider the overall impact and optimization of the PR from a global and system perspective.
    • More information about code review in Github is here

We're a small team focused on building great things. If you have something in mind that you'd like to add or modify, opening a pull request is the ideal way to catch our attention. 🚀

Board Item Create Workflow 🛠️

At CAMEL, we manage our project through a structured workflow that ensures efficiency and clarity in our development process. Our workflow includes stages for issue creation and pull requests (PRs), sprint planning, and reviews.

Issue Item Stage:

Our issues page on GitHub is regularly updated with bugs, improvements, and feature requests. We have a handy set of labels to help you sort through and find issues that interest you. Feel free to use these labels to keep things organized.

When you start working on an issue, please assign it to yourself so that others know it's being taken care of.

When creating a new issue, it's best to keep it focused on a specific bug, improvement, or feature. If two issues are related or blocking each other, it's better to link them instead of merging them into one.

We do our best to keep these issues up to date, but considering the fast-paced nature of this field, some may become outdated. If you come across any such issues, please give us a heads-up so we can address them promptly. 👀

Here’s how to engage with our issues effectively:

  • Go to GitHub Issues, create a new issue, choose the category, and fill in the required information.
  • Ensure the issue has a proper title and update the Assignees, Labels, Projects (select Backlog status), Development, and Milestones.
  • Discuss the issue during team meetings, then move it to the Analysis Done column.
  • At the beginning of each sprint, share the analyzed issue and move it to the Sprint Planned column if you are going to work on this issue in the sprint.

Pull Request Item Stage:

  • Go to GitHub Pulls, create a new PR, choose the branch, and fill in the information, linking the related issue.
  • Ensure the PR has a proper title and update the Reviewers (convert to draft), Assignees, Labels, Projects (select Developing status), Development, and Milestones.
  • If the PR is related to a roadmap, link the roadmap to the PR.
  • Move the PR item through the stages: Developing, Stuck, Reviewing (click ready for review), Merged. The linked issue will close automatically when the PR is merged.

Labeling PRs:

  • feat: For new features (e.g., feat: Add new AI model)
  • fix: For bug fixes (e.g., fix: Resolve memory leak issue)
  • docs: For documentation updates (e.g., docs: Update contribution guidelines)
  • style: For code style changes (e.g., style: Refactor code formatting)
  • refactor: For code refactoring (e.g., refactor: Optimize data processing)
  • test: For adding or updating tests (e.g., test: Add unit tests for new feature)
  • chore: For maintenance tasks (e.g., chore: Update dependencies)

Sprint Planning & Review 🎯

Definition

Sprint planning defines what can be delivered in the sprint and how it will be achieved. Sprint review allows stakeholders to review and provide feedback on recent work.

Practice

  • Sprint Duration: Two weeks for development, one week for review.
  • Sprint Planning & Review: Conducted biweekly during the dev meeting (around 30 minutes).
  • Planning: Founder highlights the sprint goal and key points; developers pick items for the sprint.
  • Review: Feedback on delivered features and identification of improvement areas.

Getting Help 🆘

Our aim is to make the developer setup as straightforward as possible. If you encounter any challenges during the setup process, don't hesitate to reach out to a maintainer. We're here to assist you and ensure that the experience is smooth not just for you but also for future contributors. 😊

In line with this, we do have specific guidelines for code linting, formatting, and documentation in the codebase. If you find these requirements difficult or even just bothersome to work with, please feel free to get in touch with a maintainer. We don't want these guidelines to hinder the integration of good code into the codebase, so we're more than happy to provide support and find a solution that works for you. 🤝

Quick Start 🚀

To get started with CAMEL, follow these steps:

# Clone github repo
git clone https://github.com/camel-ai/camel.git

# Change directory into project directory
cd camel

# Activate camel virtual environment
poetry shell

# Install camel from source
# It takes about 75s to resolve dependencies and 10s to install them, depending on your hardware and network
poetry install --with dev,docs

# Or if you want to use all other extra packages
poetry install --with dev,docs -E all  # (Suggested for developers)

# The following command installs a pre-commit hook into the local git repo,
# so every commit gets auto-formatted and linted.
pre-commit install

# Run camel's pre-commit before push
pre-commit run --all-files

# Run camel's unit tests
pytest test

# Exit the virtual environment
exit

These commands will install all the necessary dependencies for running the package, examples, linting, formatting, tests, and coverage.

To verify that everything is set up correctly, run pytest . This will ensure that all tests pass successfully. ✅

Common Actions 🔄

Update dependencies

Whenever you add, update, or delete any dependencies in pyproject.toml, please run poetry lock to synchronize the dependencies with the lock file.

Linting & Formatting ✨

poetry run ruff check .
poetry run ruff format .

For extra validation of type hints:

mypy --namespace-packages -p camel
mypy --namespace-packages -p test
mypy --namespace-packages -p examples
mypy --namespace-packages -p apps

Coverage 📊

Code coverage measures the extent to which unit tests cover the code, helping identify both robust and less robust areas of the codebase.

To generate a report showing the current code coverage, execute one of the following commands.

To include all source files into coverage:

coverage erase
coverage run --source=. -m pytest .
coverage html
# Open htmlcov/index.html

To include only tested files:

pytest --cov --cov-report=html

The coverage report will be generated at htmlcov/index.html.

Tests 🧪

Unit tests cover modular logic that doesn't require calls to outside APIs. Currently, the test setup requires an OpenAI API key to test the framework, making them resemble integration tests.

To run all tests including those that use OpenAI API, use the following command:

pytest .

To quickly run only local isolated unit and integration tests:

pytest --fast-test-mode .

If you're developing with VSCode, make sure to create a .env file in the repository root and include your OpenAI API key:

OPENAI_API_KEY=sk-XXXXXXXX
OPENAI_API_BASE_URL=https://XXXXXXXX (Should you utilize an OpenAI proxy service, kindly specify this)

Documentation 📚

Contribute to Documentation 📝

The documentation is primarily generated automatically by Sphinx using the code.

We kindly request that you provide comprehensive documentation for all classes and methods to ensure high-quality documentation coverage.

Build Documentation Locally 🛠️

To build the documentation locally, follow these steps:

cd docs
make html

More guidelines about building and hosting documentations locally can be found here.

Versioning and Release 🚀

As of now, CAMEL is actively in development and just published preview version to PyPI.

CAMEL follows the semver versioning standard. As pre-1.0 software, even patch releases may contain non-backwards-compatible changes. Currently, the major version is 0, and the minor version is incremented. Releases are made once the maintainers feel that a significant body of changes has accumulated.

License 📜

The source code of the CAMEL project is licensed under Apache 2.0. Your contributed code will be also licensed under Apache 2.0 by default. To add license to you code, you can manually copy-paste it from license_template.txt to the head of your files or run the update_license.py script to automate the process:

python licenses/update_license.py . licenses/license_template.txt

This script will add licenses to all the *.py files or update the licenses if the existing licenses are not the same as license_template.txt.

Giving Credit 🎉

If your contribution has been included in a release, we'd love to give you credit on Twitter, but only if you're comfortable with it!

If you have a Twitter account that you would like us to mention, please let us know either in the pull request or through another communication method. We want to make sure you receive proper recognition for your valuable contributions. 😄