CONTRIBUTING.md

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:

1. Fork the Nektar++ repository in nektar/nektar into your username's space.
2. 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.
3. Make sure you've gone through the checklist below.
4. 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 the Draft tag in the title, for instance Draft: Update session reader. This will prevent your code from being accidentally merged.
5. 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, and MR2, that branches off MR1. Stacked Merge Requests would look like this:

  master <- MR1 <- MR2

  In the above scenario, changes in MR1 are first reviewed, before changes in MR2. After code review, MR2 is first merged into MR1's branch, which is then merged into master.

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

1. 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 latest master

   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.