From 12c0a0fd71cac71bc1ece11d9a75dc181e7ca5b7 Mon Sep 17 00:00:00 2001 From: David Moxey Date: Thu, 25 Feb 2016 21:38:18 +0000 Subject: [PATCH] Add contribution guide, clang-format file and update gitignore --- .clang-format | 15 ++++++ .gitignore | 1 + CONTRIBUTING.md | 136 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 152 insertions(+) create mode 100644 .clang-format create mode 100644 CONTRIBUTING.md diff --git a/.clang-format b/.clang-format new file mode 100644 index 000000000..13e4629de --- /dev/null +++ b/.clang-format @@ -0,0 +1,15 @@ +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 diff --git a/.gitignore b/.gitignore index 48e01d4c3..a9724a77b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ .* !.gitignore +!.clang-format # Ignore builds and ThirdParty directories build builds diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..3ce2dab7f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,136 @@ +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. -- GitLab