Welcome! We are thrilled you are interested in contributing to Covasim. This document will help you get started.
Please see the guidelines below to provide feedback or contribute to Covasim code. Note that we make no representations that the code works as intended or that we will provide support, address issues that are found, or accept pull requests.
Contributions to this project are released to the public under the project's open source license.
Note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
Review the documentation before you begin. Additionally, this content is also included in the following README files:
- Project README: Setup and project overview.
- Covasim README: Simulation parameters. application. docker setup.
- Tests README: Running tests locally.
This is a fast-moving project with many opportunities to contribute across the project. We welcome the following types of contributions:
Issues:
- Bug reports.
- Feature requests.
Pull requests:
- Tests reproducing an issue.
- Bug fixes.
- Code to resolve open approved issues.
- Documentation improvements in the docs folder.
All external communication about these contribution efforts is currently occurring on GitHub.
If you notice unexpected behavior or a limitation in Covasim, follow the steps below before requesting a new feature or reporting a bug.
- First, review the Covasim documentation to see if there is already functionality that supports what you want to do. In particular, check :doc:`parameters` or this README to see if the behavior you observed might be expected and if configuration options are available to provide you with the desired behavior.
- Search the existing issues to see if there is already one that contains your feedback. If there is, add a thumbs up reaction to convey your interest in the issue being addressed. This helps the team gauge interest without the noise of comments, which trigger notifications to all watchers. Comments should be used only if you have new and useful information to share.
When opening an issue to request a new feature, do the following:
- Provide a clear and descriptive title for the issue.
- Include as many details as possible in the body. Fully explain your use case, the problems you're hitting, and the solutions you'd like to see to address those problems.
When opening an issue to report a bug, explain the problem and include additional details to help us reproduce the problem:
- Describe the specific steps that led to the problem you encountered with as many details as possible. Don't just say what you did, but explain how you did it.
- Provide specific examples to demonstrate the steps, such as links to files or projects, code snippets, or screen shots. Please use Markdown code blocks for code snippets.
- Describe the behavior you observed after following the steps and point out exactly what the problem with that behavior is, including explaining what you expected to see instead and why.
To contribute directly to Covasim code, do the following:
Fork and clone the Covasim repository.
Install Covasim on your machine. See the project README.
Create a new branch:
git checkout -b my-branch-name
Make your code changes, including a descriptive commit message.
Push to your fork and submit a pull request.
Although we make no guarantees that a submitted pull request will be accepted, PRs that meet the following criteria are more likely to be merged:
- Up-to-date with master with no merge conflicts
- Self-contained
- Fix a demonstrable limitation of bug
- Follow the current code style
- If the PR introduces a new feature, it has complete Google style docstrings and comments, and a test demonstrating its functionality
- Otherwise, sample code demonstrating old and new behavior (this can be in the PR comment on GitHub, not necessarily committed in the repo)
If you have additional questions or comments, contact covasim@idmod.org.