Contributing - rpreen/xcsf Wiki

Contributions to this repository are very welcome. If you are interested in contributing, feel free to contact me or create an issue in the issue tracking system. Alternatively, you may fork the project and submit a pull request. All contributions must be made under the same license as the rest of the project: GNU Public License v3. Ideally, new code would be accompanied with appropriate test cases and documented — but most importantly the code just needs to work and I'm happy to help assimilate/clean up any useful contribution.

Remember to:

  1. Add your @author at the top of each modified source file and update the date.
  2. Include a GPLv3 license at the top of any new files.
  3. Include a description of the changes in CHANGELOG.md.
  4. Add your details to the CITATION.cff.

Style Guides

Each data structure and function should be documented with Doxygen comments. Please try to follow the general style of existing code by using const-correctness and avoid typedefs to aid comprehension. Python code should be linted with pylint; a perfect score is not necessary, but try to clean up as much as is reasonable. Yaml files should be linted with yamllint.

A pre-commit configuration file is provided to automatically:

  • Trim trailing whitespace and fix line endings;
  • Check for spelling errors;
  • Check and format JSON files;
  • Check Yaml files;
  • Format C/C++ with clang-format;
  • Format CMakeLists with cmake-format;
  • Check Python with flake8;
  • Format Python with black;
  • Upgrade Python syntax with pyupgrade.

Pre-commit can be setup as follows:

$ pip install pre-commit

Then to run on all files in the repository:

$ pre-commit run -a

To install as a hook that executes with every git commit:

$ pre-commit install

Version Numbering

Version number format: MAJOR.MINOR.BUILD - specified in xcsf.h, CMakeLists.txt and setup.py.

  • Increment BUILD number for minor bug fixes and changes that do not break compatability with file saving/loading.
  • Increment MINOR number for major bug fixes and changes that break compatability with file saving/loading.
  • Criteria for incrementing the MAJOR number to be determined later.