diff options
Diffstat (limited to 'docs/contributing.md')
| -rw-r--r-- | docs/contributing.md | 64 |
1 files changed, 64 insertions, 0 deletions
diff --git a/docs/contributing.md b/docs/contributing.md index b95edf86..5429bf9d 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,6 +1,13 @@ <a id="top"></a> # Contributing to Catch +**Contents**<br> +[Branches](#branches)<br> +[Directory structure](#directory-structure)<br> +[Testing your changes](#testing-your-changes)<br> +[Documenting your code](#documenting-your-code)<br> +[Code constructs to watch out for](#code-constructs-to-watch-out-for)<br> + So you want to contribute something to Catch? That's great! Whether it's a bug fix, a new feature, support for additional compilers - or just a fix to the documentation - all contributions are very welcome and very much appreciated. Of course so are bug reports and other comments and questions. @@ -63,6 +70,10 @@ locally takes just a few minutes. $ cd debug-build $ ctest -j 2 --output-on-failure ``` +__Note:__ When running your tests with multi-configuration generators like +Visual Studio, you might get errors "Test not available without configuration." +You then have to pick one configuration (e.g. ` -C Debug`) in the `ctest` call. + If you added new tests, approval tests are very likely to fail. If they do not, it means that your changes weren't run as part of them. This _might_ be intentional, but usually is not. @@ -75,6 +86,59 @@ before you do so, you need to check that the introduced changes are indeed intentional. +## Documenting your code + +If you have added new feature to Catch2, it needs documentation, so that +other people can use it as well. This section collects some technical +information that you will need for updating Catch2's documentation, and +possibly some generic advise as well. + +First, the technicalities: + +* We introduced version tags to the documentation, which show users in +which version a specific feature was introduced. This means that newly +written documentation should be tagged with a placeholder, that will +be replaced with the actual version upon release. There are 2 styles +of placeholders used through the documentation, you should pick one that +fits your text better (if in doubt, take a look at the existing version +tags for other features). + * `> [Introduced](link-to-issue-or-PR) in Catch X.Y.Z` - this + placeholder is usually used after a section heading + * `> X (Y and Z) was [introduced](link-to-issue-or-PR) in Catch X.Y.Z` + - this placeholder is used when you need to tag a subpart of something, + e.g. list +* Crosslinks to different pages should target the `top` anchor, like this +`[link to contributing](contributing.md#top)`. +* If you have introduced a new document, there is a simple template you +should use. It provides you with the top anchor mentioned above, and also +with a backlink to the top of the documentation: +```markdown +<a id="top"></a> +# Cool feature + +Text that explains how to use the cool feature. + + +--- + +[Home](Readme.md#top) +``` +* For pages with more than 4 subheadings, we provide a table of contents +(ToC) at the top of the page. Because GitHub markdown does not support +automatic generation of ToC, it has to be handled semi-manually. Thus, +if you've added a new subheading to some page, you should add it to the +ToC. This can be done either manually, or by running the +`updateDocumentToC.py` script in the `scripts/` folder. + + +Now, for the generic tips: + * Usage examples are good + * Don't be afraid to introduce new pages + * Try to be reasonably consistent with the surrounding documentation + + + + ## Code constructs to watch out for This section is a (sadly incomplete) listing of various constructs that |