Contributing - xcsf-dev/xcsf GitHub 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.PATCH - specified in xcsf.h, CMakeLists.txt and setup.py.

From v1.3.0 onwards, semantic versioning will be used:

  • MAJOR version: Increment the MAJOR version when you make incompatible API changes or introduce significant changes that might break existing functionality. These changes typically involve removing or changing existing APIs or adding new features that are not backward compatible.
  • MINOR version: Increment the MINOR version when you add new features or functionalities in a backward-compatible manner. This means that existing APIs remain intact, and users can upgrade to the new version without making changes to their code.
  • PATCH version: Increment the PATCH version for backward-compatible bug fixes or minor improvements that do not affect the existing APIs significantly. These updates should not introduce any new features or break existing functionality.