1<a id="top"></a> 2# Contributing to Catch 3 4So you want to contribute something to Catch? That's great! Whether it's a bug fix, a new feature, support for 5additional compilers - or just a fix to the documentation - all contributions are very welcome and very much appreciated. 6Of course so are bug reports and other comments and questions. 7 8If you are contributing to the code base there are a few simple guidelines to keep in mind. This also includes notes to 9help you find your way around. As this is liable to drift out of date please raise an issue or, better still, a pull 10request for this file, if you notice that. 11 12## Branches 13 14Ongoing development is currently on _master_. At some point an integration branch will be set-up and PRs should target 15 that - but for now it's all against master. You may see feature branches come and go from time to time, too. 16 17## Directory structure 18 19_Users_ of Catch primarily use the single header version. _Maintainers_ should work with the full source (which is still, 20primarily, in headers). This can be found in the `include` folder. There are a set of test files, currently under 21`projects/SelfTest`. The test app can be built via CMake from the `CMakeLists.txt` file in the root, or you can generate 22project files for Visual Studio, XCode, and others (instructions in the `projects` folder). If you have access to CLion, 23it can work with the CMake file directly. 24 25As well as the runtime test files you'll also see a `SurrogateCpps` directory under `projects/SelfTest`. 26This contains a set of .cpp files that each `#include` a single header. 27While these files are not essential to compilation they help to keep the implementation headers self-contained. 28At time of writing this set is not complete but has reasonable coverage. 29If you add additional headers please try to remember to add a surrogate cpp for it. 30 31The other directories are `scripts` which contains a set of python scripts to help in testing Catch as well as 32generating the single include, and `docs`, which contains the documentation as a set of markdown files. 33 34__When submitting a pull request please do not include changes to the single include, or to the version number file 35as these are managed by the scripts!__ 36 37 38## Testing your changes 39 40Obviously all changes to Catch's code should be tested. If you added new 41functionality, you should add tests covering and showcasing it. Even if you have 42only made changes to Catch internals (i.e. you implemented some performance 43improvements), you should still test your changes. 44 45This means 2 things 46 47* Compiling Catch's SelfTest project: 48``` 49$ cd Catch2 50$ cmake -Bdebug-build -H. -DCMAKE_BUILD_TYPE=Debug 51$ cmake --build debug-build 52``` 53because code that does not compile is evidently incorrect. Obviously, 54you are not expected to have access to all the compilers and platforms 55supported by Catch2, but you should at least smoke test your changes 56on your platform. Our CI pipeline will check your PR against most of 57the supported platforms, but it takes an hour to finish -- compiling 58locally takes just a few minutes. 59 60 61* Running the tests via CTest: 62``` 63$ cd debug-build 64$ ctest -j 2 --output-on-failure 65``` 66If you added new tests, approval tests are very likely to fail. If they 67do not, it means that your changes weren't run as part of them. This 68_might_ be intentional, but usually is not. 69 70The approval tests compare current output of the SelfTest binary in various 71configurations against known good outputs. The reason it fails is, 72_usually_, that you've added new tests but have not yet approved the changes 73they introduce. This is done with the `scripts/approve.py` script, but 74before you do so, you need to check that the introduced changes are indeed 75intentional. 76 77 78 79 *this document is still in-progress...* 80 81--- 82 83[Home](Readme.md#top) 84