Skip to content

The development workflow

fredjaya edited this page Dec 8, 2023 · 13 revisions

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.

Overview

devcycle

TODO: Explanation on the repo structure and branches

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>

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.

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 and considerations when addressing specific types of issues:

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 (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:

Submitting a PR

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.

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!