Contributing to Catch3

Contents
Where to start
Building and testing
Two parts, two sets of rules
Tests
Documentation
Code of Conduct

Progmasoft maintains Catch3. Issues and pull requests are welcome on Progmasoft/catch3; pull requests go to the devel branch. Report security problems privately, as described in SECURITY.md, not in a public issue.

Where to start

Open an issue before a large change, so that the direction can be agreed first. A pull request should do one thing, say why in its description and come with the tests that show it works.

Building and testing

Bazel is the main build. With Bazelisk:

bazelisk test //tests/...

On Windows, point Bazel at Git's bash first: BAZEL_SH="C:\Program Files\Git\usr\bin\bash.exe".

CMake builds every test, including the extra tests that check compile-time configurations. Their scripts need Python 3 with defusedxml (python3-defusedxml on Debian, Ubuntu and Fedora, or requirements-tests.txt):

cmake --preset basic-tests -GNinja -DCATCH3_BUILD_EXTRA_TESTS=ON -DCATCH3_BUILD_EXAMPLES=ON
cmake --build build
ctest --test-dir build -j

Meson, Xmake and Premake builds exist as well and are checked in CI.

Before you push, run the repository checks:

bazelisk run //tools:check

It checks licenses, convenience headers, header guards, file names, that every place states the same version, and that the single-file distribution is up to date. A change to anything under src/ regenerates that distribution:

bazelisk run //tools:amalgamate

The tools in tools/ are C++17 and run through Bazel, with arguments after --:

ToolDoes
//tools:amalgamatewrites the single-file distribution; -- --check only compares it
//tools:checkruns the repository checks
//tools:third_party-- --check compares third_party/ with the archives MODULE.bazel pins, -- --update writes it
//tools:versionprints the version; -- <version> (MAJOR.MINOR.PATCH) or -- --next (the next patch release) moves every place that states it, and the distribution
//tools:release_notesprints a section of the release notes, of -- <version> or the current one
//tools:repo_inforeports the checkout and the tools on PATH; -- --json writes it as JSON

Two parts, two sets of rules

src/catch2 is the compatibility engine taken from Catch2. Its public API is what Catch3 promises to keep: code that compiles against Catch2's headers must keep compiling. It stays under the Boost Software License 1.0, keeps the Catch2 Authors header and follows the style of the surrounding Catch2 code. Code that includes its headers needs C++17 or later.

src/Progmasoft holds what Progmasoft adds: the runner, the results model, property testing and snapshots. It is licensed LGPL-3.0-or-later, follows the Progmasoft Core C++ Coding Guidelines, is C++17, reports recoverable errors with Expected rather than exceptions, and is formatted with the .clang-format beside it.

//tools:check checks that every source file carries the header of its part.

Tests

tests/SelfTest tests the compatibility engine; tests/ExtraTests tests compile-time configurations and the runner's behaviour around them; tests/Progmasoft tests the Progmasoft code, and the runner's integration tests there start a fixture binary whose tests misbehave on purpose. A bug fix comes with a test that fails without it.

Documentation

User documentation lives in docs/. A new page is linked from the documentation index, and a page with sections gets a table of contents. A user-visible change gets a line in the release notes.

Code of Conduct

Everyone who takes part follows the Code of Conduct.

Diese Seite auf GitHubLizenzen der Dokumentation