|
| 1 | +# How to Contribute |
| 2 | + |
| 3 | +First, thank you! |
| 4 | + |
| 5 | +Writing esoteric scientific software can be it's own reward, but it's not for the faint of heart. |
| 6 | + |
| 7 | +If you want a general overview as to why this software package exists, please look at my talk [Causal Dynamical Triangulations with CGAL][slides], or the [Wiki]. |
| 8 | + |
| 9 | +Second, here are some simple guidelines that will make it easier on me to process and accept your contributions. |
| 10 | + |
| 11 | +1. Fork the repository. |
| 12 | +2. Familiarize yourself with [Catch] and in particular, the [Gherkin] syntax. |
| 13 | +3. Write a unit test for your proposed contribution. Unit tests go in the `test` directory and are named \{YourContribution\}Test.cpp, so that they can be automatically built. |
| 14 | +All proposed features of your contribution should have a corresponding test in \{YourContribution\}Test.cpp. |
| 15 | +Consult the [Catch Test cases and sections] if you are unsure, or consult existing tests for examples. |
| 16 | +4. I highly recommend writing your tests first, before your contribution, as this helps to think about how the rest of the program will use your functions and/or classes. |
| 17 | +[Test-Driven Development] (and [BDD]) has saved me quite a lot from various mistakes. |
| 18 | +5. Project source files go into the `src` directory; header files go into `include`. |
| 19 | +This makes integration into tests and the main program easy and modular, and follows convention. |
| 20 | +6. Don't forget documentation! It's helpful if you state explicitly what your functions and classes do. |
| 21 | +I use [Doxygen] to automatically build documentation, so using `/// @brief` and `/// @param` is helpful and easy. |
| 22 | +Consult existing code for examples. |
| 23 | +7. Commit your changes with a clear, [well-written commit message]. |
| 24 | +*I am guilty of not always writing the clearest commit messages in this project, and will do better. |
| 25 | +For the longest time, however, no one but me actually read them. |
| 26 | +When I contribute to other projects, I definitely try to have useful, clear commit messages and you should, too.* |
| 27 | +8. Run `clang-format` using the project's [.clang-format]. |
| 28 | +9. Open a pull request against the develop branch of the main repository (which is the default). |
| 29 | +[Travis-CI] will test it against combinations of Linux (Ubuntu 14.04), MacOS, clang, and gcc, so ensure that your code compiles on both platforms with both compilers. |
| 30 | +10. All pull requests must pass [Travis-CI] and [AppVeyor] to be accepted. |
| 31 | +In particular, look at results from git whitespace checks (`git diff --check HEAD^`), [ClangFormat], [ClangTidy], [Valgrind], [Coverity], and [Codecov] . |
| 32 | +11. I will get to your change as soon as I can. |
| 33 | +Feel free to ping me on [Gitter] with any questions. |
| 34 | +You will receive proper credit for your contributions both in the code and any resulting scientific papers using the output of `git log --format='%aN | sort -u`. |
| 35 | + |
| 36 | +# Style Guide |
| 37 | + |
| 38 | +This project generally follows [Stroustrup formatting with Allman brackets][1], enforced by [ClangFormat]. |
| 39 | +The [C++ Core Guidelines][cpp-core] are checked using [ClangTidy]. |
| 40 | +Running [clang-tidy.sh] changes the code (using `-fix`), so compare results and run unit tests before you commit. |
| 41 | +Especially since some of ClangTidy's fixes break the codebase (the script runs just the tests that don't). |
| 42 | + |
| 43 | +Most editors/IDEs have plugins for `clang-format` and `clang-tidy`. |
| 44 | + |
| 45 | +[Wiki]: https://github.com/acgetchell/CDT-plusplus/wiki |
| 46 | +[Test-Driven Development]: http://alexott.net/en/cpp/CppTestingIntro.html |
| 47 | +[Doxygen]: http://doxygen.org |
| 48 | +[well-written commit message]: https://chris.beams.io/posts/git-commit/ |
| 49 | +[Travis-CI]: https://travis-ci.org/acgetchell/CDT-plusplus |
| 50 | +[1]: https://isocpp.org/wiki/faq/coding-standards |
| 51 | +[2]: http://llvm.org/releases/4.0.0/tools/clang/docs/ClangFormatStyleOptions.html |
| 52 | +[ClangFormat]: https://github.com/acgetchell/CDT-plusplus/blob/master/.clang-format |
| 53 | +[slides]: http://slides.com/acgetchell/causal-dynamical-triangulations-3 |
| 54 | +[Valgrind]: http://valgrind.org/docs/manual/quick-start.html#quick-start.mcrun |
| 55 | +[cpp-core]: https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md |
| 56 | +[clang-tidy.sh]: https://github.com/acgetchell/CDT-plusplus/blob/master/clang-tidy.sh |
| 57 | +[AppVeyor]: https://ci.appveyor.com/project/acgetchell/cdt-plusplus |
| 58 | +[Catch]: https://github.com/catchorg/Catch2/blob/master/docs/Readme.md |
| 59 | +[Gherkin]: https://www.tutorialspoint.com/behavior_driven_development/behavior_driven_development_gherkin.htm |
| 60 | +[BDD]: https://en.wikipedia.org/wiki/Behavior-driven_development |
| 61 | +[Catch Test cases and sections]: https://github.com/catchorg/Catch2/blob/master/docs/test-cases-and-sections.md |
| 62 | +[Codecov]: https://codecov.io/support |
| 63 | +[Gitter]: https://gitter.im/acgetchell/CDT-plusplus |
| 64 | +[ClangTidy]: http://clang.llvm.org/extra/clang-tidy/index.html |
| 65 | +[Coverity]: https://scan.coverity.com/projects/acgetchell-cdt-plusplus |
0 commit comments