You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
swarms/CONTRIBUTING.md

105 lines
4.8 KiB

1 year ago
# Contributing to Swarms 🛠️
2 years ago
1 year ago
Thank you for your interest in contributing to Swarms!
2 years ago
1 year ago
We are actively improving this library to reduce the amount of work you need to do to solve common computer vision problems.
2 years ago
1 year ago
## Contribution Guidelines
2 years ago
1 year ago
We welcome contributions to:
2 years ago
1 year ago
1. Add a new feature to the library (guidance below).
2. Improve our documentation and add examples to make it clear how to leverage the swarms library.
3. Report bugs and issues in the project.
4. Submit a request for a new feature.
5. Improve our test coverage.
2 years ago
1 year ago
### Contributing Features ✨
2 years ago
1 year ago
Swarms is designed to provide modular building blocks to build scalable swarms of autonomous agents!
2 years ago
1 year ago
Before you contribute a new feature, consider submitting an Issue to discuss the feature so the community can weigh in and assist.
2 years ago
1 year ago
## How to Contribute Changes
2 years ago
1 year ago
First, fork this repository to your own GitHub account. Click "fork" in the top corner of the `swarms` repository to get started:
2 years ago
1 year ago
Then, run `git clone` to download the project code to your computer.
2 years ago
1 year ago
Move to a new branch using the `git checkout` command:
2 years ago
```bash
1 year ago
git checkout -b <your_branch_name>
2 years ago
```
1 year ago
The name you choose for your branch should describe the change you want to make (i.e. `line-counter-docs`).
2 years ago
1 year ago
Make any changes you want to the project code, then run the following commands to commit your changes:
2 years ago
```bash
1 year ago
git add .
git commit -m "Your commit message"
git push -u origin main
2 years ago
```
1 year ago
## 🎨 Code quality
2 years ago
1 year ago
### Pre-commit tool
2 years ago
1 year ago
This project utilizes the [pre-commit](https://pre-commit.com/) tool to maintain code quality and consistency. Before submitting a pull request or making any commits, it is important to run the pre-commit tool to ensure that your changes meet the project's guidelines.
2 years ago
1 year ago
Furthermore, we have integrated a pre-commit GitHub Action into our workflow. This means that with every pull request opened, the pre-commit checks will be automatically enforced, streamlining the code review process and ensuring that all contributions adhere to our quality standards.
2 years ago
1 year ago
To run the pre-commit tool, follow these steps:
2 years ago
1 year ago
1. Install pre-commit by running the following command: `poetry install`. It will not only install pre-commit but also install all the deps and dev-deps of project
2 years ago
1 year ago
2. Once pre-commit is installed, navigate to the project's root directory.
2 years ago
1 year ago
3. Run the command `pre-commit run --all-files`. This will execute the pre-commit hooks configured for this project against the modified files. If any issues are found, the pre-commit tool will provide feedback on how to resolve them. Make the necessary changes and re-run the pre-commit command until all issues are resolved.
2 years ago
1 year ago
4. You can also install pre-commit as a git hook by execute `pre-commit install`. Every time you made `git commit` pre-commit run automatically for you.
2 years ago
1 year ago
### Docstrings
2 years ago
1 year ago
All new functions and classes in `swarms` should include docstrings. This is a prerequisite for any new functions and classes to be added to the library.
2 years ago
1 year ago
`swarms` adheres to the [Google Python docstring style](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods). Please refer to the style guide while writing docstrings for your contribution.
2 years ago
1 year ago
### Type checking
2 years ago
1 year ago
Then, go back to your fork of the `swarms` repository, click "Pull Requests", and click "New Pull Request".
2 years ago
1 year ago
Make sure the `base` branch is `develop` before submitting your PR.
2 years ago
1 year ago
On the next page, review your changes then click "Create pull request":
2 years ago
1 year ago
Next, write a description for your pull request, and click "Create pull request" again to submit it for review:
2 years ago
1 year ago
When creating new functions, please ensure you have the following:
2 years ago
1 year ago
1. Docstrings for the function and all parameters.
2. Unit tests for the function.
3. Examples in the documentation for the function.
4. Created an entry in our docs to autogenerate the documentation for the function.
5. Please share a Google Colab with minimal code to test new feature or reproduce PR whenever it is possible. Please ensure that Google Colab can be accessed without any issue.
2 years ago
1 year ago
All pull requests will be reviewed by the maintainers of the project. We will provide feedback and ask for changes if necessary.
2 years ago
1 year ago
PRs must pass all tests and linting requirements before they can be merged.
2 years ago
1 year ago
## 📝 documentation
2 years ago
1 year ago
The `swarms` documentation is stored in a folder called `docs`. The project documentation is built using `mkdocs`.
2 years ago
1 year ago
To run the documentation, install the project requirements with `poetry install dev`. Then, run `mkdocs serve` to start the documentation server.
2 years ago
1 year ago
You can learn more about mkdocs on the [mkdocs website](https://www.mkdocs.org/).
2 years ago
1 year ago
## 🧪 tests
2 years ago
1 year ago
[`pytests`](https://docs.pytest.org/en/7.1.x/) is used to run our tests.
2 years ago
1 year ago
## 📄 license
2 years ago
1 year ago
By contributing, you agree that your contributions will be licensed under an [MIT license](https://github.com/kyegomez/swarms/blob/develop/LICENSE.md).