Commit 12c0a0fd authored by Dave Moxey's avatar Dave Moxey Committed by Spencer Sherwin

Add contribution guide, clang-format file and update gitignore

parent 4a5839b9
BasedOnStyle: LLVM
AlignAfterOpenBracket: true
AlignConsecutiveAssignments: true
IndentWidth: 4
BreakBeforeBraces: Allman
AllowShortBlocksOnASingleLine: false
AllowShortFunctionsOnASingleLine: None
AllowShortCaseLabelsOnASingleLine: false
AllowShortIfStatementsOnASingleLine: false
AllowShortLoopsOnASingleLine: false
IndentCaseLabels: true
Standard: Cpp03
AccessModifierOffset: -4
BinPackParameters: false
BinPackArguments: false
.*
!.gitignore
!.clang-format
# Ignore builds and ThirdParty directories
build
builds
......
Contributing to Nektar++
========================
## 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](https://gitlab.nektar.info/nektar/nektar/issues)** -- be
sure to do a quick search and see if anyone has reported the same thing first.
- Alternatively you can
**[join the mailing list](https://mailman.ic.ac.uk/mailman/listinfo/nektar-users)**
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 merge request to merge into `master`. If you just want to see the
diff and are not quite ready to merge, use the `[WIP]` tag in the title to
prevent your code from being accidentally merged.
5. Put a comment in the MR saying that it's ready to be merged.
6. Respond to any comments in the code review.
## Submission checklist
- Did you add regression tests (for fixes) or unit tests and/or normal tests for
new features?
- Have you run your branch through buildbot and do all the tests pass?
- Is there documentation in the user guide and/or developer guide?
- Are there any massive files you might have added in the commit history? We try
to keep test files as small as possible.
- Is the code formatted correctly? **Pro tip:** see below to download and
install `clang-format` to make life very easy!
## Testing and Buildbot
Your new features or fixes should include tests that cover the code you've
added. There are numerous examples within the various `Tests` directory lying
within the source trees, and there is an example of writing `.tst` files for our
`Tester` executable in the `tests/Examples/regex_example.tst` directory. Once
you've written your tests, add them to the `CMakeLists.txt` file in whatever
directory you are working in.
You should also test your branch on the
[Nektar++ buildbot](http://buildbot.nektar.info/), which will compile and test
the code against a number of Linux, Mac and Windows operating systems, both 32-
and 64-bit. If your tests don't pass, we can't merge the code into master.
## Documentation
Nektar++ has a fairly comprehensive user guide and a developer guide that is
presently very incomplete. If you are writing user-exposed features, you should
add some documentation to the user guide on how to use them. Any code should
also be well-commented in both Doxygen and in normal C++ comments to explain it.
## Code review and merging
All merge requests will be reviewed by one of the senior developers. We try to
stick to the following process:
- Senior developer will be assigned, MR will be assigned a milestone to target a
release.
- If the branch is deemed to be minor and passes the checklist above, senior
developer will handle the request by themselves.
- Otherwise, senior developer will ask one or more other developers to review the code.
- Submission checklist will be checked by the reviewers
- Where appropriate, reviewers will comment on regions of code that need further
development and/or improvement.
- Once feedback received from the branch author (if necessary) and reviewers are
happy, the branch will be merged.
## Formatting guidelines
Nektar++ uses C++, a language notorious for being easy to make obtuse and
difficult to follow code. To hopefully alleviate this problem, there are a
number of fairly simple formatting guidelines you should follow. We are
reasonably relaxed about code formatting, but if you can follow the guidelines
below this would be fantastic.
### Basic rules
- All code should be wrapped to 80 characters.
- Indentation should be 4 spaces with **no tabs**. Namespaces should not be
indented to give more room in the 80 character width.
- Please comment your code with Doxygen and inline comments wherever possible --
but don't use trailing inline comments to save the 80 character limit!
- All code blocks (even one-line blocks) should use braces, and braces should be
on new lines; for instance
```c++
if (someCondition) {
myAwesomeFunction();
}
```
- **Don't use preprocessor directives and macros unless there is no viable
alternative.** The exception to this is header guards inside your `.h` files.
- Use one `.cpp` and `.h` file per C++ class, and try to keep `inline` header
code to a minimum (unless performance is a major factor).
- Put spaces around binary operators and constants.
- Put spaces after `if`, `while`, etc., but not after function names (see the
example above).
### Variables and naming
- Please use sensible names!
- Use camelCase to define your variable and function names,
e.g. `myAwesomeVariable`. Any `typedef`s, function, `class` and `struct` names
should begin with capital letters, variable names should be lower case.
- Inside classes, member variables should be prefixed with `m_`,
e.g. `m_myAwesomeVariable`.
- Global constants used throughout the library should be prefixed with `k`
(e.g. `kGeometricTolerance`), and enumerations should be prefixed with `e`
(e.g. `eGeometry`).
- Use all uppercase letters with underscores between words for pre-processor
definitions and macros.
### Using `clang-format`
Code formatting is reasonably boring, so Nektar++ comes with a `.clang-format`
file to allow for automatic code formatting. Installing it is easy on most
package managers. Nektar++ relies on options that are used in version 3.7 or
later.
There are a number of instructions on how to use `clang-format` inside a number
of text editors on the
[CLang website](http://clang.llvm.org/docs/ClangFormat.html). However at a
minimum, you should consider downloading the
[``git-clang-format``](https://llvm.org/svn/llvm-project/cfe/trunk/tools/clang-format/git-clang-format)
script into one of your `$PATH` locations. You can then run the command
git clang-format
before you do a `git commit`, and `clang-format` will automatically format your
diff according to the guidelines.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment