The development workflow
Adopting a structured development workflow ensures that contributions are
consistent with existing cogent3 code and standards. It also streamlines
the review process, allowing us to incorporate your valuable contributions
faster!
This how-to guide will go through the contribution process, covering how to select an issue to tackle, through to submitting your contributions for review.
You should have already set up your development environment.
TODO: Explanation on the repo structure and branches
For a first time contributor, we recommend you select an issue labelled as a good first issue.
Once you've picked the issue, comment on it letting us know you'd like to tackle it. This is let everyone know this issue is being addressed.
To make it easier to track the changes being made, you should work on one issue per branch.
On your forked cogent3 repo create a new feature branch and include the
issue number:
$ git checkout -b feature/issue-<ISSUE_NUMBER>Check that you are on the correct branch:
$ git branch
develop
* feature/issue-<ISSUE_NUMBER>As you work on your contribution, it is essential to regularly follow the
best practices described in Development practices for cogent3. This ensures
your code aligns with cogent3 standards.
When working on the issue, refer to the specific instructions outlined in the original issue post.
Importantly, please raise any questions regarding clarity by commenting on the issue. Don't be afraid to ask for detailed guidance for your first contribution - we want you to have a good experence so you will keep helping! 😁
Here are some instructions and considerations when addressing specific types of issues:
All commit messages must be succinct and informative. All commit messages must start with a capitalised acronym according to the numpy style guide (see table below), followed by a colon, then the commit message.
In the commit that addresses the issue, the commit message should include which issue number it fixes. This ensures that the issue is closed automatically when the PR is accepted.
Some exemplar commit messages:
DOC: added display of sequence features to gallery, fixes #1500
DOC: add more how-tos on features, fixes #1511
List of acronyms
| Prefix | For |
|---|---|
| API: | an (incompatible) API change |
| BENCH: | changes to the benchmark suite |
| BLD: | change related to making a build |
| BUG: | bug fix |
| DEP: | deprecate something, or remove a deprecated object |
| DEV: | development tool or utility |
| DOC: | documentation |
| ENH: | enhancement |
| MAINT: | maintenance commit (refactoring, typos, etc.) |
| REV: | revert an earlier commit |
| STY: | style fix (whitespace, PEP8) |
| TST: | addition or modification of tests |
| REL: | related to a release |
For more information and examples, see:
Before submitting a pull request (PR), please ensure the following:
- The test suite passes locally
- The code is formatted by the linters
- The fork is up-to-date with the parent repo
Instructions for all three requirements are described in Development practices for cogent3.
Your contribution will be reviewed by a member of the core dev team, and we may ask for some changes before accepting it. It's rare for a contribution to be accepted without some edits. This is a constructive process and we hope you will find our remarks useful.
Thanks for participating!