Code contributions¶

We have adopted a fully public fork and pull request workflow, where every proposed changeset has to go through a code review and approval process.

The code changes are developed on a branch of the fork. When completed, the developer submits the changes for review through the web interface: a pull request (PR) is opened, requesting that the changes from the source branch on the fork be merged into a target branch in the canonical repository. Once the PR is open, the new code is automatically tested. Core developers of PCMSolver will then review the contribution and discuss additional changes to be made. Eventually, if all the tests are passing and a developer approves the suggested contribution, the changes are merged into the target branch. The target branch is (usually) the master branch, that is, the main development branch.

Note

All PRs goes to the master branch

The creator of the PR is responsible for keeping the code up to date with master, so the code in the PR reflects what will be the code in the master branch after merging.

Branching Model¶

We are using the stable mainline branching model for Git. In the main repository on github there are two types of branches:

one main developing branch, called master
release branches

A new release branch is created from the master branch for a new release, with the format release/vMAJOR.MINOR. A release branch will never be merged back to the master branch and will only receive bug fixes, thus no new features. These bug fixes would be cherry picked from the master branch, to ensure that the master branch always contains all bug fixes. In case a bug fix is only relevant for a given release, the bug should be fixed with a PR directly to the corresponding release branch. In case a bug fix is easy to perform on a release branch but challenging to perform on the master branch, the fix can be directed to a release branch. Then an issue have to be created to make sure it will also be fixed on the master branch.

Feature branches are not created on the main repository, but on forks. These are based on the master branch from the main repository and merged into the master branch through pull requests.

Changelog¶

We follow the guidelines of Keep a CHANGELOG On all but the release branches, there is an Unreleased section under which new additions should be listed. To simplify perusal of the CHANGELOG.md, use the following subsections:

Added for new features.
Changed for changes in existing functionality.
Deprecated for once-stable features removed in upcoming releases.
Removed for deprecated features removed in this release.
Fixed for any bug fixes.
Security to invite users to upgrade in case of vulnerabilities.

Updating Eigen Distribution¶

The C++ linear algebra library Eigen comes bundled with the module. To update the distributed version one has to:

download the desired version of the library to a scratch location. Eigen’s website is: http://eigen.tuxfamily.org/
unpack the downloaded archive;
go into the newly created directory and create a build directory;
go into the newly created build directory and type the following (remember to substitute @PROJECT_SOURCE_DIR@ with the actual path)
```
cmake .. -DCMAKE_INSTALL_PREFIX=@PROJECT_SOURCE_DIR@/external/eigen3
```

Remember to commit and push your modifications.

Git Pre-Commit Hooks¶

Git pre-commit hooks are used to keep track of code style and license header in source files. Code style is checked using clang-format for C/C++ and yapf for Python.

Warning

You need to install ``clang-format`` (v3.9 recommended) and ``yapf`` (v0.20 recommended) to run the code style validation hook!

License headers are checked using the license_maintainer.py script and the header templates for the different languages used in this project. The Python script checks the .gitattributes file to determine which license headers need to be maintained and in which files:

src/pedra/pedra_dlapack.F90 !licensefile
src/solver/*.hpp licensefile=.githooks/LICENSE-C++

The first line specifies that the file in src/pedra/pedra_dlapack.F90 should not be touched, while the second line states that all .hpp files in src/solver should get an header from the template in .githooks/LICENSE-C++ Location of files in .gitattributes are always specified with respect to the project root directory.

The hooks are located in the .githooks subdirectory and have to be installed by hand whenever you clone the repository anew:

cd .git/hooks
cp --symbolic-link ../../.githooks/* .

Installed hooks will always be executed. Use git commit --no-verify to bypass explicitly the hooks.