mirror of
https://github.com/catchorg/Catch2.git
synced 2024-11-04 21:29:54 +01:00
Rewrite the contributing documentation
This commit is contained in:
parent
018dc0b74f
commit
dc7a20fc74
@ -1,118 +1,119 @@
|
||||
<a id="top"></a>
|
||||
# Contributing to Catch
|
||||
# Contributing to Catch2
|
||||
|
||||
**Contents**<br>
|
||||
[Branches](#branches)<br>
|
||||
[Directory structure](#directory-structure)<br>
|
||||
[Using Git(Hub)](#using-github)<br>
|
||||
[Testing your changes](#testing-your-changes)<br>
|
||||
[Documenting your code](#documenting-your-code)<br>
|
||||
[Examples](#examples)<br>
|
||||
[Code constructs to watch out for](#code-constructs-to-watch-out-for)<br>
|
||||
[Writing documentation](#writing-documentation)<br>
|
||||
[Writing code](#writing-code)<br>
|
||||
[CoC](#coc)<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.
|
||||
So you want to contribute something to Catch2? 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, other comments, and
|
||||
questions, but generally it is a better idea to ask questions in our
|
||||
[Discord](https://discord.gg/4CWS9zD), than in the issue tracker.
|
||||
|
||||
If you are contributing to the code base there are a few simple guidelines to keep in mind. This also includes notes to
|
||||
help you find your way around. As this is liable to drift out of date please raise an issue or, better still, a pull
|
||||
request for this file, if you notice that.
|
||||
|
||||
## Branches
|
||||
This page covers some guidelines and helpful tips for contributing
|
||||
to the codebase itself.
|
||||
|
||||
Ongoing development is currently on _master_. At some point an integration branch will be set-up and PRs should target
|
||||
that - but for now it's all against master. You may see feature branches come and go from time to time, too.
|
||||
## Using Git(Hub)
|
||||
|
||||
## Directory structure
|
||||
Ongoing development happens in the `master` branch for Catch2 v2, and in
|
||||
`dev-v3` for the next major version, v3.
|
||||
|
||||
_Users_ of Catch primarily use the single header version. _Maintainers_ should work with the full source (which is still,
|
||||
primarily, in headers). This can be found in the `include` folder. There are a set of test files, currently under
|
||||
`projects/SelfTest`. The test app can be built via CMake from the `CMakeLists.txt` file in the root, or you can generate
|
||||
project files for Visual Studio, XCode, and others (instructions in the `projects` folder). If you have access to CLion,
|
||||
it can work with the CMake file directly.
|
||||
Commits should be small and atomic. A commit is atomic when, after it is
|
||||
applied, the codebase, tests and all, still works as expected. Small
|
||||
commits are also prefered, as they make later operations with git history,
|
||||
whether it is bisecting, reverting, or something else, easier.
|
||||
|
||||
As well as the runtime test files you'll also see a `SurrogateCpps` directory under `projects/SelfTest`.
|
||||
This contains a set of .cpp files that each `#include` a single header.
|
||||
While these files are not essential to compilation they help to keep the implementation headers self-contained.
|
||||
At time of writing this set is not complete but has reasonable coverage.
|
||||
If you add additional headers please try to remember to add a surrogate cpp for it.
|
||||
_When submitting a pull request please do not include changes to the
|
||||
single include. This means do not include them in your git commits!_
|
||||
|
||||
The other directories are `scripts` which contains a set of python scripts to help in testing Catch as well as
|
||||
generating the single include, and `docs`, which contains the documentation as a set of markdown files.
|
||||
|
||||
__When submitting a pull request please do not include changes to the single include, or to the version number file
|
||||
as these are managed by the scripts!__
|
||||
When addressing review comments in a MR, please do not rebase/squash the
|
||||
commits immediately. Doing so makes it harder to review the new changes,
|
||||
slowing down the process of merging a MR. Instead, when addressing review
|
||||
comments, you should append new commits to the branch and only squash
|
||||
them into other commits when the MR is ready to be merged. We recommend
|
||||
creating new commits with `git commit --fixup` (or `--squash`) and then
|
||||
later squashing them with `git rebase --autosquash` to make things easier.
|
||||
|
||||
|
||||
|
||||
## Testing your changes
|
||||
|
||||
Obviously all changes to Catch's code should be tested. If you added new
|
||||
functionality, you should add tests covering and showcasing it. Even if you have
|
||||
only made changes to Catch internals (i.e. you implemented some performance
|
||||
improvements), you should still test your changes.
|
||||
_Note: Running Catch2's tests requires Python3_
|
||||
|
||||
This means 2 things
|
||||
|
||||
* Compiling Catch's SelfTest project:
|
||||
Catch2 has multiple layers of tests that are then run as part of our CI.
|
||||
The most obvious one are the unit tests compiled into the `SelfTest`
|
||||
binary. These are then used in "Approval tests", which run (almost) all
|
||||
tests from `SelfTest` through a specific reporter and then compare the
|
||||
generated output with a known good output ("Baseline"). By default, new
|
||||
tests should be placed here.
|
||||
|
||||
However, not all tests can be written as plain unit tests. For example,
|
||||
checking that Catch2 orders tests randomly when asked to, and that this
|
||||
random ordering is subset-invariant, is better done as an integration
|
||||
test using an external check script. Catch2 integration tests are written
|
||||
using CTest, either as a direct command invocation + pass/fail regex,
|
||||
or by delegating the check to a Python script.
|
||||
|
||||
There are also two more kinds of tests, examples and "ExtraTests".
|
||||
Examples serve as a compilation test on the single-header distribution,
|
||||
and present a small and self-contained snippets of using Catch2 for
|
||||
writing tests. ExtraTests then are tests that either take a long time
|
||||
to run, or require separate compilation, e.g. because of testing compile
|
||||
time configuration options, and take a long time because of that.
|
||||
|
||||
Both of these are compiled against the single-header distribution of
|
||||
Catch2, and thus might require you to regenerate it manually. This is
|
||||
done by calling the `generateSingleHeader.py` script in `scripts`.
|
||||
|
||||
Examples and ExtraTests are not compiled by default. To compile them,
|
||||
add `-DCATCH_BUILD_EXAMPLES=ON` and `-DCATCH_BUILD_EXTRA_TESTS=ON` to
|
||||
the invocation of CMake configuration step.
|
||||
|
||||
Bringing this all together, the steps below should configure, build,
|
||||
and run all tests in the `Debug` compilation.
|
||||
|
||||
1. Regenerate the single header distribution
|
||||
```
|
||||
$ cd Catch2
|
||||
$ cmake -Bdebug-build -H. -DCMAKE_BUILD_TYPE=Debug
|
||||
$ ./scripts/generateSingleHeader.py
|
||||
```
|
||||
2. Configure the full test build
|
||||
```
|
||||
$ cmake -Bdebug-build -H. -DCMAKE_BUILD_TYPE=Debug -DCATCH_BUILD_EXAMPLES=ON -DCATCH_BUILD_EXTRA_TESTS=ON
|
||||
```
|
||||
3. Run the actual build
|
||||
```
|
||||
$ cmake --build debug-build
|
||||
```
|
||||
because code that does not compile is evidently incorrect. Obviously,
|
||||
you are not expected to have access to all the compilers and platforms
|
||||
supported by Catch2, but you should at least smoke test your changes
|
||||
on your platform. Our CI pipeline will check your PR against most of
|
||||
the supported platforms, but it takes an hour to finish -- compiling
|
||||
locally takes just a few minutes.
|
||||
|
||||
|
||||
* Running the tests via CTest:
|
||||
4. Run the tests using CTest
|
||||
```
|
||||
$ cd debug-build
|
||||
$ ctest -j 2 --output-on-failure
|
||||
$ ctest -j 4 --output-on-failure -C Debug
|
||||
```
|
||||
__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.
|
||||
|
||||
The approval tests compare current output of the SelfTest binary in various
|
||||
configurations against known good outputs. The reason it fails is,
|
||||
_usually_, that you've added new tests but have not yet approved the changes
|
||||
they introduce. This is done with the `scripts/approve.py` script, but
|
||||
before you do so, you need to check that the introduced changes are indeed
|
||||
intentional.
|
||||
|
||||
|
||||
## Documenting your code
|
||||
## Writing documentation
|
||||
|
||||
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.
|
||||
|
||||
### Technicalities
|
||||
|
||||
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:
|
||||
should use. It provides you with the top anchor mentioned to link to
|
||||
(more below), and also with a backlink to the top of the documentation:
|
||||
```markdown
|
||||
<a id="top"></a>
|
||||
# Cool feature
|
||||
@ -125,6 +126,22 @@ Text that explains how to use the cool feature.
|
||||
[Home](Readme.md#top)
|
||||
```
|
||||
|
||||
* Crosslinks to different pages should target the `top` anchor, like this
|
||||
`[link to contributing](contributing.md#top)`.
|
||||
|
||||
* 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. a list
|
||||
|
||||
* 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,
|
||||
@ -132,44 +149,54 @@ 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.
|
||||
|
||||
### Contents
|
||||
|
||||
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
|
||||
Now, for some content tips:
|
||||
|
||||
## Examples
|
||||
* Usage examples are good. However, having large code snippets inline
|
||||
can make the documentation less readable, and so the inline snippets
|
||||
should be kept reasonably short. To provide more complex compilable
|
||||
examples, consider adding new .cpp file to `examples/`.
|
||||
|
||||
The examples/ directory contains some example tests which should compile and
|
||||
run to show how to use Catch2. The code being tested should be trivial as the
|
||||
purpose of the examples is to show how the tests work.
|
||||
* Don't be afraid to introduce new pages. The current documentation
|
||||
tends towards long pages, but a lot of that is caused by legacy, and
|
||||
we know that some of the pages are overly big and unfocused.
|
||||
|
||||
The examples in the `examples/` directory are not built by default. To compile
|
||||
them add `-DCATCH_BUILD_EXAMPLES=ON` to your cmake command line. There will
|
||||
then be an `examples/` directory in your build directory, containing the
|
||||
resulting test programs.
|
||||
* When adding information to an existing page, please try to keep your
|
||||
formatting, style and changes consistent with the rest of the page.
|
||||
|
||||
In general each file in `examples/` compiles to a stand-alone test program for
|
||||
clarity.
|
||||
* Any documentation has multiple different audiences, that desire
|
||||
different information from the text. The 3 basic user-types to try and
|
||||
cover are:
|
||||
* A beginner to Catch2, who requires closer guidance for the usage of Catch2.
|
||||
* Advanced user of Catch2, who want to customize their usage.
|
||||
* Experts, looking for full reference of Catch2's capabilities.
|
||||
|
||||
The examples are compiled against the local copy of the _single header_ version
|
||||
of catch. If you are building from git then this might not be up to date with
|
||||
changes in the _full source_ version. Before trying to build the examples, go
|
||||
to the top level of the source tree, and run the python script to prepare the
|
||||
single header version (this requires Python3 to be installed):
|
||||
|
||||
```
|
||||
./scripts/generateSingleHeader.py
|
||||
```
|
||||
__When submitting a pull request please do not include changes to the single
|
||||
include. This means do not include them in your git commits!__
|
||||
## Writing code
|
||||
|
||||
## Code constructs to watch out for
|
||||
If want to contribute code, this section contains some simple rules
|
||||
and tips on things like code formatting, code constructions to avoid,
|
||||
and so on.
|
||||
|
||||
|
||||
### Formatting
|
||||
|
||||
To make code formatting simpler for the contributors, Catch2 provides
|
||||
its own config for `clang-format`. However, because it is currently
|
||||
impossible to replicate existing Catch2's formatting in clang-format,
|
||||
using it to reformat a whole file would cause massive diffs. To keep
|
||||
the size of your diffs reasonable, you should only use clang-format
|
||||
on the newly changed code.
|
||||
|
||||
|
||||
### Code constructs to watch out for
|
||||
|
||||
This section is a (sadly incomplete) listing of various constructs that
|
||||
are problematic and are not always caught by our CI infrastructure.
|
||||
|
||||
### Naked exceptions and exceptions-related function
|
||||
|
||||
#### Naked exceptions and exceptions-related function
|
||||
|
||||
If you are throwing an exception, it should be done via `CATCH_ERROR`
|
||||
or `CATCH_RUNTIME_ERROR` in `catch_enforce.h`. These macros will handle
|
||||
@ -180,7 +207,8 @@ CI, but luckily there should not be too many reasons to use these.
|
||||
However, if you do, they should be kept behind a
|
||||
`CATCH_CONFIG_DISABLE_EXCEPTIONS` macro.
|
||||
|
||||
### Unqualified usage of functions from C's stdlib
|
||||
|
||||
#### Unqualified usage of functions from C's stdlib
|
||||
|
||||
If you are using a function from C's stdlib, please include the header
|
||||
as `<cfoo>` and call the function qualified. The common knowledge that
|
||||
@ -188,7 +216,12 @@ there is no difference is wrong, QNX and VxWorks won't compile if you
|
||||
include the header as `<cfoo>` and call the function unqualified.
|
||||
|
||||
|
||||
----
|
||||
## CoC
|
||||
|
||||
This project has a [CoC](../CODE_OF_CONDUCT.md). Please adhere to it
|
||||
while contributing to Catch2.
|
||||
|
||||
-----------
|
||||
|
||||
_This documentation will always be in-progress as new information comes
|
||||
up, but we are trying to keep it as up to date as possible._
|
||||
|
Loading…
Reference in New Issue
Block a user