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|How to set up your development environment]].

Select an issue to work on

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.

Create a new feature branch

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>

Hack away!

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 to address specific types of issues:

• Deprecating code
• Writing documentation

Adhering to development practices

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.

Writing the commit message

All commit messages must be succinct and informative. All commit messages must start with a capitalised acronym according to the numpy style guide.

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:

• Writing NumPy commit messages

Submitting a PR

TODO: Add links to the below

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

The review process

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!