Thank you for getting involved in NetKet. It is only thanks to the involvement of a large community of developers that open-source software like NetKet can thrive. Please take the time to read the following guidelines, to ensure that your contributions are in line with the general goals of this project and its requirements.
Before sending your pull requests, make sure you followed this list.
- Read contributing guidelines.
- Read Code of Conduct.
- Check if your changes are consistent with the guidelines.
- Check if your changes are consistent with the C++ and Python code style and run the code formatters clang-format and/or Black as needed.
- Run Unit Tests.
If you have improvements to NetKet, or want to get involved in one of our Challenges send us your pull requests! For those just getting started, Github has a howto.
NetKet team members will be assigned to review your pull requests. Once the pull requests are approved and pass continuous integration checks, we will merge the pull requests.
If you want to contribute but you're not sure where to start, take a look at the issues with the "help wanted" label. These are issues that we believe are particularly well suited for outside contributions. If you decide to start on an issue, leave a comment so that other people know that you're working on it. If you want to help out, but not alone, use the issue comment thread to coordinate.
Before sending your pull request for review, make sure your changes are consistent with the guidelines and follow the NetKet coding style.
- Include unit tests when you contribute new features, as they help to a) prove that your code works correctly, and b) guard against future breaking changes to lower the maintenance cost.
- Bug fixes also generally require unit tests, because the presence of bugs usually indicates insufficient test coverage.
- When you contribute a new feature to NetKet, the maintenance burden is (by default) transferred to the NetKet team. This means that benefit of the contribution must be compared against the cost of maintaining the feature.
Include a license at the top of new files.
NetKet C++ generally follows the Google C++ Style Guide, with a few differences.
Main differences with respect to Google standards include:
- Header files should end in
.hpp(not in.has per this) - Use of non-const reference arguments is allowed (exception to this)
- The use of exceptions is permitted but should be limited to invalid user input, IO errors, and similar cases. The arguments against using exceptions from the Google guide are specific to Google's situation and do not apply to netket. See also NR.3 and E.2 and following from the C++ Core Guidelines.
The Google C++ Style Guide also includes useful guidelines to format the code.
Those can be conveniently enforced by means of automatic reformatting tools.
We strongly recommend that you use clang-tidy to check your C/C++ changes.
To install clang-tidy on ubuntu, do:
apt-get install -y clang-tidyon MacOS you can use brew
brew install clang-formatYou can check a C/C++ file by doing:
clang-format --style=google <my_cc_file> > /tmp/my_cc_file.cc
diff <my_cc_file> /tmp/my_cc_file.ccMost likely, your favorite code editor supports a plugin for clang-format.
Those are typically very handy, since they allow to format the code in real time,
at any point you save your code, and without recurring to the command line.
Our editor of choice, atom, has a nice plugin see here
which can be configured with Google style.
To do so, after having installed the plugin, go to
Atom -> Preferences... -> Packages -> clang-format -> Settings and type google in the Style field.
Python code should follow PEP 8.
For consistency, we use the Black code formatter, which you can install in your Python environment using pip install black.
If you edit Python code, you should run Black on the affected files.
On the command line, this can be done via
# to reformat a specific file
black Path/To/The/file.py
# to reformat all files below the specified directories
black Test/ Examples/before creating a pull request. There are other options of running Black: For example, an Atom package is available and Black is integrated into the VS Code Python extension.
You can run sanity checks compiling with the option NETKET_Sanitizer=ON in CMake:
mkdir build
cd build
cmake .. -DNETKET_Sanitizer=ON
make
make testThis will compile NetKet with Clang sanitizer, and unit tests will report any issue found.
Contributions implementing new features must include associated unit tests.
Unit tests in NetKet are based on Catch 2 and are located in the directory Test.
In the most typical case, your contribution will be an extension of one of the many existing prototype classes (for example, deriving from AbstractMachine, AbstractGraph classes etc). In this case, you typically only need to add
a corresponding input file for testing.
For an example, take a look at how the input cases for testing classes derived from AbstractMachine are structured, in file Test/Machine/machine_input_tests.hpp. If you were to add a new Machine, you would need to include in this file a json object which allows NetKet to construct your machine in a few test cases. All the units tests conceived for the Machine class would be then automatically executed on your new class.
Unit tests are automatically compiled when you install NetKet through CMake. To execute unit tests, just do
make testin the CMake build directory.
Notice that if you add new test files (i.e. you do not simply extend the existing json input objects), before compiling you will need to tell CMake about your new files, editing Test/CMakeLists.txt accordingly.