Contributor Guide

Contributor Guide

Recommended Workflow Elements

pre-commit git hooks

It is recommended to use the pre-commit hook manager to enforce coding conventions and perform static code analysis infrastructure. Simply install pre-commit as described here. Then run pre-commit install in the Libint source directory. File .pre-commit-config.yaml describes the hook configuration used by Libint; feel free to PR additional hooks.

Each time you try to commit a changeset in a repo in which pre-commit hooks have been installed each hook will be executed on each file added or changed in the changeset. Some hooks are designed to simply prevent nonconformant source code, documentation, infrastructure files, etc. from being committed, whereas other hooks will change the files to make them conformant. In either case, the commit will fail if any changes are needed. You will need to update the changeset (by amending the commit with the changes performed by the hooks and/or any changes you performed manually) and try again.

N.B. Changes in files performed by the pre-commit hooks are not instantly "seen" by the IDE, so it is recommended to manually run git status after a failed commit.

The most important use case for pre-commit hooks is to invoke clang-format automatically on each file added or changed in a commit.

pre-commit git hook: clang-format

This hook runs clang-format to enforce the Libint code formatting conventions specified in the style file .clang-format located at the top of Libint repository. Any time a C/C++ file is changed clang-format will be run on it; if any changes are necessary it will mutate the file in-place and the commit will fail. You will need to commit again (you may also need to fix any other errors identified by pre-commit).

Sometimes you way want to protect parts of code from being re-formatted by clang-format, due to readability or correctness concerns. This can be done by adding // clang-format off immediately before the lines you want to protect and // clang-format on after the lines that you want to protect, e.g.:

int formatted_code;
// clang-format off
    void    unformatted_code  ;
// clang-format on
void formatted_code_again;

Refer to the clang-format documentation for more info.

Note that most of the code in Libint has not been re-formatted to conform to the style file .clang-format yet. The plan is to reformat Libint code around January 1, 2024. Until then the use of clang-format should be limited to new files only.