How to contribute#

First steps#

If you find a possible bug or missing functionality, please make sure first that this is indeed the case by,

  1. checking the online documentation,

  2. checking the Issues page for related open or closed issues and/or Pull Requests.

If it turns out there is indeed a problem or a lack of functionality, please open an issue first.

Developer toolkit#

To start contributing you’ll need a few tools, some more optional than others:

  • Make and CMake

  • a C/C++ compiler, we recommend gcc (the GNU Compiler Collection),

  • a Python virtual environment, try mambaforge and create a development environment using the environment.yml file provided with the repository,

  • an editor ot IDE, try Visual Studio Code with at Python and C++ support.

How to add your contribution#

  1. fork the project’s repository

  2. switch to a new branch git switch -c branch_name with branch_name something like feature-my_feature or fix-my_fix

  3. follow git commit best practices

  4. git push your changes

  5. open a Pull Request (PR)

  6. Describe your PR properly, and if related to other issues link them

Tests#

The test suite for the C++ library sits in the tests directory at the root of the repository. You can use ctest after the building step to launch the tests.

Tests for the Python package are based on pytest and should be placed under the src/pybindings/xcdf/tests directory.

Important

To develop the Python tests, please make sure to install the package with the tests extra. See Python3 bindings.

Documentation#

C++ library#

The documentation for the C++ library part of the package is based on Exhale and Doxygen, you can start from here.

For the Python bindings this part you can use Sphinx. Please refer also to the instructions provided by pybind11.

Important

The documentation related to the C++ library is quite behind modern standards, so any help is greatly appreciated. Its development will also help better documentation of the Python bindings.

Local build#

To compile the documentation locally,

  • cd docs

  • make html

  • open build/html/index.html with your favourite browser

If you see unexpected warnings or errors, and especially if you notice unexpected build material laying around, issue a make clean and try again.

If you modify a docstring and you do not see any change after re-building the documentation, it is advised to re-install the package (editable installs won’t work either, see Editable installs).