-
Thibault Lestang authored
Update contributing guidelines following reformatting See merge request nektar/nektar!1363
Thibault Lestang authoredUpdate contributing guidelines following reformatting See merge request nektar/nektar!1363
Contributing to Nektar++
Contents
This is a reasonably complete guide to help if you're interested in contributing to Nektar++, either in reporting bugs or, hopefully, trying to fix them! It's split up into a number of sections:
- Issues and bug reports
- How to contribute
- Submission checklist
- Git cheatsheet
- Testing and GitLab CI
- Documentation
- Formatting guidelines
Issues and bug reports
Think you've found a bug or issue with Nektar++? We're very keen to hear about it!
- In the first instance, you should raise an issue on the issue tracker -- be sure to do a quick search and see if anyone has reported the same thing first.
- Alternatively you can join the mailing list for more advice.
It's really helpful if you can include a small session file that reproduces the error, and can give a good description of the problem you're having.
How to contribute
If you've got a patch or feature, please consider contributing it back to the project. It's a pretty simple process:
- Fork the Nektar++ repository in
nektar/nektar
into your username's space. - Create a branch with the naming convention:
-
feature/myawesomebranch
: a new feature that wasn't in Nektar++ already. -
fix/mygreatfix
: fixes an issue that isn't tracked in the issue tracker. -
ticket/123-myfantasticpatch
: fixes an issue that is tracked in the issue tracker (please include the issue number somewhere!) -
tidy/mybrillianttidying
: cosmetic fixes to bring existing files up to the Nektar++ code guidelines.
-
- Make sure you've gone through the checklist below.
- Submit a request to merge into
master
(Merge Request). If you just want to see the diff and are not quite ready to merge, use theDraft
tag in the title, for instanceDraft: Update session reader
. This will prevent your code from being accidentally merged. - Respond to any comments in the code review.
Reviewing Merge Requests can be a arduous and time-consuming process for reviewers. To allow for efficient code reviews, we ask that you take particular care of the following points:
-
Submit small Merge Requests. Whenever you can, split your work into multiple self-contained, stacked Merge Requests. Say for instance that you split your work into two branches
MR1
, andMR2
, that branches offMR1
. Stacked Merge Requests would look like this:master <- MR1 <- MR2
In the above scenario, changes in
MR1
are first reviewed, before changes inMR2
. After code review,MR2
is first merged intoMR1
's branch, which is then merged intomaster
. -
Provide a detailed description of your changes by filling the Merge Request template. Please keep the structure of the template as-is: fill the section with "Non applicable" if needed. Don't be afraid of "stating the obvious": the more information you provide, the easier (and quicker) the code review is.
-
Give your submission a descriptive title. Avoid generic titles like "Update module X" or "Fix bug in module Y".
An example of a Merge Request is available here.
Keeping your branch up to date
Regularly updating your branch with the latest changes on the base
branch (usually master
) is essential to avoid large conflicts when
merging your work into the main development line. There are two ways
of updating your branch:
- If you haven't pushed your branch to the upstream remote
(
nektar/nektar.git
), or if you are sure nobody based work on your changes, rebase your changes on the latestmaster
git checkout feature/mybranch git pull --rebase master
This will rewrite the history of your local branch in order for your
changes to appear on top of the latest changes in master. This leads
to a clean, linear history. See Git Branching - Rebasing
2. If you pushed your changes and there is a high chance that somebody
based work on top of your -- yet unmerged -- changes, don't
rebase. Merge the latest master
state into your branch instead:
git checkout feature/mybranch
git fetch origin
git merge origin/master
This will create a merge commit joining your branch's history and
the master
branch's history. The merge approach do not rewrite
your branch's history, at the expanse of making it more complex.