Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
138 lines (103 loc) · 5.01 KB

CONTRIBUTING.md

File metadata and controls

138 lines (103 loc) · 5.01 KB
Raw

Contributing

Thank you for contributing to PHEvaluator! Here are some advices might be useful for passing the code review.

Basics

  • Check out the latest code in develop branch. Also target your Pull Request on the develop branch.
  • Follow these coding style guidelines:
  • Split your work into multiple Pull Request if they are irrelevant, so that we can merge them independently (usually with squash merge).
  • If you are planning to work on a large feature, it'd be helpful if we can understand your idea first, prior to getting your hands on the implementation. You may create a new issue or a new discussion.
  • The GitHub Actions workflow automatically test your code and run linters before merging your Pull Request. If any issues are detected, the workflow logs will display detailed information about the problems and the necessary changes to resolve them.
  • We recommend you to format, lint, build, and test your code locally before pushing your changes. This helps identify and fix issues quickly.

Formatting and linting

Formatting and linting are enforced by GitHub Actions on every Pull Request (see Continuous Integration below). When a check finds an auto-fixable problem, the workflow posts an inline suggestion on your Pull Request that you can apply with a single click. You can also run the same tools locally before pushing, as described in the sections below.

C++ development

See more details: README.md for C++

Requirements:

Code style:

  • Specified in .clang-format
  • Format code with clang-format -i <file-path>

Build:

cd cpp
cmake -B build # This will create a folder named build, and configure the Makefile
cmake --build build # This will start the build in the new folder

Test:

cd cpp/build
./unit_tests

Python development

See more details: README.md for Python

Code style:

  • Specified in pyproject.toml
  • Lint code with ruff check
  • Format code with ruff format

Type check:

mypy .

Test:

python -m unittest discover -v

Continuous Integration (CI) with GitHub Actions

We use GitHub Actions to automate various checks and tests for every Pull Request. If the build, tests, type checking, or package installation fails, the workflow will exit with a non-zero status code. Formatting and linting problems also cause the workflow to fail. If any job exits with a non-zero status code, merging your Pull Request will be blocked by GitHub Actions.

The Lint & Suggest workflow runs the formatters and linters and posts the required changes as inline suggestions you can apply with one click. Pull Requests opened from forks receive the same suggestions from a separate Lint & Suggest (forks) workflow. All checks still run and block on failure for fork Pull Requests.

Lint & Suggest checks

  • File hygiene (all text files): byte-order-marker removal, line endings normalised to LF, tabs replaced with spaces (Makefiles excluded), trailing whitespace removal, and a final newline at end of file.
  • TOML & YAML: validity checks.
  • C++: clang-format according to .clang-format (excluding the generated cpp/src/hashtable* and cpp/src/tables* files).
  • Python: ruff check and ruff format according to pyproject.toml.
  • Python type checking: mypy.
  • Repo guards: merge-conflict detection, private-key detection, and forbidding submodules.

The C++, Markdown, and Python formatting/lint jobs only inspect the files changed in your Pull Request.

CI checks

The Build and Test workflow additionally performs:

  • C++ build and unit tests
  • Python unit tests for Python 3.10 to 3.14
  • Python package installation for Python 3.10 to 3.14

See more details:

If you have any questions, need further assistance, or want to report a bug or suggest an enhancement, feel free to open an issue.