From 4c4401c7ac8ee4507bf3b781de926ad6f1a02639 Mon Sep 17 00:00:00 2001 From: Luigi Pertoldi Date: Thu, 19 Dec 2024 18:10:22 +0100 Subject: [PATCH] Update developer's guide --- .github/CONTRIBUTING.md | 48 +++++++++++++++++++++++++++-------------- 1 file changed, 32 insertions(+), 16 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 829e214f..fc7dae0c 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -1,5 +1,25 @@ # Developer's guide +```{admonition} TL;DR / check list +Before opening a PR: + +- make sure to follow our code style conventions +- run pre-commit and fix all the issues +- add documentation, either as code docstrings or as manual pages +- if unsure about the docs format, build the documentation and check the result +- add tests for your new feature +- run tests and check if they all pass +- if adding a new macro command, update the macro command reference page +- prepare a coherent and tidy commit history (with e.g. `git rebase -i`) + +After the CI has run: + +- fix all reported problems, if any +- navigate to the ReadTheDocs documentation build (linked in the GitHub + actions report for the PR) and check that the docs are properly rendered +- download and check the test outputs from the GitHub actions interface +``` + The following rules and conventions have been established for the package development and are enforced throughout the entire code base. Merge requests that do not comply to the following directives will be rejected. @@ -67,10 +87,11 @@ $ make $ ctest ``` -:::{note} -Some tests are known to be flaky, especially with older Geant4 version -branches. -::: +If tests produce output files with an extension that contains an `.output` +sub-extension, they will be automatically uploaded to GitHub as part of a +tarball. This can be downloaded and inspected from the GitHub actions run page: +navigate to "Actions", select the CI run of interest, scroll to the bottom of +the page. Cheatsheet: ```console @@ -79,11 +100,6 @@ $ ctest -L vis # run only tests with label "vis" $ ctest -R basics-mt/print-volumes.mac # run only this test ``` -`vis` tests are currently not run in CI, since there is no graphical -environment available. Moreover, they won't be marked as "failed" (but rather -"skipped") if they fail due to the same reason. In case you want to run them -locally, make sure there is support for graphics. - If you want to open a fanci UI to check the output of `vis` tests, you may achieve it by: @@ -104,10 +120,16 @@ following: GitHub/LEGEND wiki pages should be written. - Pull request authors are required to provide sufficient documentation for every proposed change or addition. +- Documentation for classes/methods etc. should be provided in the same source + file, as Doxygen-formatted comments (see e.g. [this + guide](https://www.doxygen.nl/manual/docblocks.html)). They will be + automatically added to the API documentation section on ReadTheDocs. - General guides, comprehensive tutorials or other high-level documentation (e.g. referring to how separate parts of the code interact between each other) must be provided as separate pages in `docs/` and linked in the - table of contents. + table of contents. These documentation source files must formatted in + reStructuredText (reST). A reference format specification is available on the + [Sphinx reST usage guide](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html). To generate documentation locally, run @@ -121,12 +143,6 @@ You'll need a Doxygen installation and Python software dependencies specified in `docs/environment.yml`. The generated documentation can be viewed by pointing your browser to `docs/_build/index.html`. -### Writing documentation - -Documentation source files must formatted in reStructuredText (reST). A -reference format specification is available on the [Sphinx reST usage -guide](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html). - ### Automatic command reference generation If you change the Geant macro command-based interface in a pull request, please