1<a id="top"></a> 2# Contributing to Catch 3 4**Contents**<br> 5[Branches](#branches)<br> 6[Directory structure](#directory-structure)<br> 7[Testing your changes](#testing-your-changes)<br> 8[Documenting your code](#documenting-your-code)<br> 9[Code constructs to watch out for](#code-constructs-to-watch-out-for)<br> 10 11So you want to contribute something to Catch? That's great! Whether it's a bug fix, a new feature, support for 12additional compilers - or just a fix to the documentation - all contributions are very welcome and very much appreciated. 13Of course so are bug reports and other comments and questions. 14 15If you are contributing to the code base there are a few simple guidelines to keep in mind. This also includes notes to 16help you find your way around. As this is liable to drift out of date please raise an issue or, better still, a pull 17request for this file, if you notice that. 18 19## Branches 20 21Ongoing development is currently on _master_. At some point an integration branch will be set-up and PRs should target 22 that - but for now it's all against master. You may see feature branches come and go from time to time, too. 23 24## Directory structure 25 26_Users_ of Catch primarily use the single header version. _Maintainers_ should work with the full source (which is still, 27primarily, in headers). This can be found in the `include` folder. There are a set of test files, currently under 28`projects/SelfTest`. The test app can be built via CMake from the `CMakeLists.txt` file in the root, or you can generate 29project files for Visual Studio, XCode, and others (instructions in the `projects` folder). If you have access to CLion, 30it can work with the CMake file directly. 31 32As well as the runtime test files you'll also see a `SurrogateCpps` directory under `projects/SelfTest`. 33This contains a set of .cpp files that each `#include` a single header. 34While these files are not essential to compilation they help to keep the implementation headers self-contained. 35At time of writing this set is not complete but has reasonable coverage. 36If you add additional headers please try to remember to add a surrogate cpp for it. 37 38The other directories are `scripts` which contains a set of python scripts to help in testing Catch as well as 39generating the single include, and `docs`, which contains the documentation as a set of markdown files. 40 41__When submitting a pull request please do not include changes to the single include, or to the version number file 42as these are managed by the scripts!__ 43 44 45## Testing your changes 46 47Obviously all changes to Catch's code should be tested. If you added new 48functionality, you should add tests covering and showcasing it. Even if you have 49only made changes to Catch internals (i.e. you implemented some performance 50improvements), you should still test your changes. 51 52This means 2 things 53 54* Compiling Catch's SelfTest project: 55``` 56$ cd Catch2 57$ cmake -Bdebug-build -H. -DCMAKE_BUILD_TYPE=Debug 58$ cmake --build debug-build 59``` 60because code that does not compile is evidently incorrect. Obviously, 61you are not expected to have access to all the compilers and platforms 62supported by Catch2, but you should at least smoke test your changes 63on your platform. Our CI pipeline will check your PR against most of 64the supported platforms, but it takes an hour to finish -- compiling 65locally takes just a few minutes. 66 67 68* Running the tests via CTest: 69``` 70$ cd debug-build 71$ ctest -j 2 --output-on-failure 72``` 73__Note:__ When running your tests with multi-configuration generators like 74Visual Studio, you might get errors "Test not available without configuration." 75You then have to pick one configuration (e.g. ` -C Debug`) in the `ctest` call. 76 77If you added new tests, approval tests are very likely to fail. If they 78do not, it means that your changes weren't run as part of them. This 79_might_ be intentional, but usually is not. 80 81The approval tests compare current output of the SelfTest binary in various 82configurations against known good outputs. The reason it fails is, 83_usually_, that you've added new tests but have not yet approved the changes 84they introduce. This is done with the `scripts/approve.py` script, but 85before you do so, you need to check that the introduced changes are indeed 86intentional. 87 88 89## Documenting your code 90 91If you have added new feature to Catch2, it needs documentation, so that 92other people can use it as well. This section collects some technical 93information that you will need for updating Catch2's documentation, and 94possibly some generic advise as well. 95 96First, the technicalities: 97 98* We introduced version tags to the documentation, which show users in 99which version a specific feature was introduced. This means that newly 100written documentation should be tagged with a placeholder, that will 101be replaced with the actual version upon release. There are 2 styles 102of placeholders used through the documentation, you should pick one that 103fits your text better (if in doubt, take a look at the existing version 104tags for other features). 105 * `> [Introduced](link-to-issue-or-PR) in Catch X.Y.Z` - this 106 placeholder is usually used after a section heading 107 * `> X (Y and Z) was [introduced](link-to-issue-or-PR) in Catch X.Y.Z` 108 - this placeholder is used when you need to tag a subpart of something, 109 e.g. list 110* Crosslinks to different pages should target the `top` anchor, like this 111`[link to contributing](contributing.md#top)`. 112* If you have introduced a new document, there is a simple template you 113should use. It provides you with the top anchor mentioned above, and also 114with a backlink to the top of the documentation: 115```markdown 116<a id="top"></a> 117# Cool feature 118 119Text that explains how to use the cool feature. 120 121 122--- 123 124[Home](Readme.md#top) 125``` 126* For pages with more than 4 subheadings, we provide a table of contents 127(ToC) at the top of the page. Because GitHub markdown does not support 128automatic generation of ToC, it has to be handled semi-manually. Thus, 129if you've added a new subheading to some page, you should add it to the 130ToC. This can be done either manually, or by running the 131`updateDocumentToC.py` script in the `scripts/` folder. 132 133 134Now, for the generic tips: 135 * Usage examples are good 136 * Don't be afraid to introduce new pages 137 * Try to be reasonably consistent with the surrounding documentation 138 139 140 141 142## Code constructs to watch out for 143 144This section is a (sadly incomplete) listing of various constructs that 145are problematic and are not always caught by our CI infrastructure. 146 147### Naked exceptions and exceptions-related function 148 149If you are throwing an exception, it should be done via `CATCH_ERROR` 150or `CATCH_RUNTIME_ERROR` in `catch_enforce.h`. These macros will handle 151the differences between compilation with or without exceptions for you. 152However, some platforms (IAR) also have problems with exceptions-related 153functions, such as `std::current_exceptions`. We do not have IAR in our 154CI, but luckily there should not be too many reasons to use these. 155However, if you do, they should be kept behind a 156`CATCH_CONFIG_DISABLE_EXCEPTIONS` macro. 157 158### Unqualified usage of functions from C's stdlib 159 160If you are using a function from C's stdlib, please include the header 161as `<cfoo>` and call the function qualified. The common knowledge that 162there is no difference is wrong, QNX and VxWorks won't compile if you 163include the header as `<cfoo>` and call the function unqualified. 164 165 166---- 167 168_This documentation will always be in-progress as new information comes 169up, but we are trying to keep it as up to date as possible._ 170 171--- 172 173[Home](Readme.md#top) 174