Contributing

Contributing#

Welcome, and thank you for your interest in making a difference! ModCAM relies on bug fixes and new algorithms from contributors like you.

If you have a bug fix or an enhancement you’d like to make, this document will guide you through the process. Here you’ll find

what sort of contributions we do and don’t want
where to find information and ask questions
how to contribute
how to style your code

Please review these guidelines and the code of conduct before making your contribution so that we can maintain consistent, high quality code.

Project scope#

The focus of modCAM is the control of machine tools for manufacturing. We welcome algorithms for additive and subtractive manufacturing, such as workpiece setup or tool path planning. Plant management operations, such as scheduling and logistics, fall outside the scope of modCAM.

Communication channels#

Questions about usage can be asked in Discussions.

For bug reports or enhancement suggestions, create an Issue.

For private communication, email modCAM.github@proton.me.

How to#

Submit a bug report or suggest an enhancement#

If you find a bug, or you want to suggest an enhancement, please start by opening an issue to raise awareness. However, before opening an issue…

Make sure that you are using the latest version.
Read the documentation carefully to check if the functionality already exists.
Perform a search to see if the enhancement or bug fix has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
For new features, make sure your idea fits within the scope of the project.

If you want to work on the improvements yourself, thank you! You can fork the repository, make your changes, and open a pull request.

Compile and test the code#

There is a development container with everything you need pre-installed, though you’re not required to use the container. To run the container:

docker pull ghcr.io/modcam/devcontainer:latest
docker run --rm -it ghcr.io/modcam/devcontainer:latest

ModCAM has the following dependencies:

Eigen
libigl
doctest (unit tests)
Doxygen (documentation)
Breathe (documentation)
Sphinx (documentation)

The CMake presets supplied with this project use vcpkg to install the C++ dependencies.

You can use the following presets and CMake options to configure your build:

Description	Preset	Equivalent options
Build only the library	build-minimal	N/A
Build the library with unit tests	build-tests	MODCAM_ENABLE_TESTING=ON
Build the library and documentation	build-docs	MODCAM_BUILD_DOC=ON
Unit tests and static analysis	linting	MODCAM_ENABLE_TESTING=ON	MODCAM_ENABLE_LINTING=ON
Build library with tests and docs	build-all	MODCAM_ENABLE_TESTING=ON	MODCAM_BUILD_DOC=ON
Tests, docs, and static analysis	build-all-with-linting	MODCAM_BUILD_DOC=ON	MODCAM_ENABLE_TESTING=ON	MODCAM_ENABLE_LINTING=ON
Only the documentation, no library	build-docs-only	MODCAM_BUILD_DOC=ON	MODCAM_BUILD_PROJECT=OFF

As an example, to build modCAM and run the unit tests, do

cmake -S . -D CMAKE_BUILD_TYPE=Release --preset build-tests
cmake --build build/
ctest --test-dir build/

Build the documentation#

ModCAM uses Python-based tools to build the documentation. The necessary Python packages are in requirements.txt and in pylock.toml. The requirements.txt file will be removed once pylock.toml is fully supported.

To build the docs, first set up a Python virtual environment:

pip

python -m venv .venv             # Create a Python virtual environment
source .venv/bin/activate        # Activate the environment
pip install -r requirements.txt  # Install the necessary Python packages

uv

uv venv                    # Create a Python virtual environment
uv pip sync pylock.toml    # Install the necessary Python packages
source .venv/bin/activate  # Activate the environment

Then, build with either CMake or Sphinx:

CMake

cmake -S . --preset build-docs-only  # Tell CMake you want to build only the docs
cmake --build build                  # Build the docs

Sphinx

sphinx-build -b html docs/ build/docs/sphinx

Style guide#

Code style and quality are enforced as much as possible with clang-format and clang-tidy.

Note that the static analysis checks defined in .clang-tidy are meant to be helpful and not a burden. If you think that one of the checks is overly burdensome, then please open an issue to discuss removing it.

Below are the style guidelines that cannot be enforced with clang-format.

Code organization#

The code is organized according to the Pitchfork Layout. The major points of the Pitchfork Layout are as follows:

The src/ directory contains the project source (.cpp) files and private header files. This directory also contains unit tests, which are denoted by the .test.cpp suffix.
The include/ directory contains the public header (.h) files.
The tools/ directory contains development utilities, such as Python scripts, CMake scripts, and packaging utilities.
The data/ directory contains project data files, such as images or data files needed by unit tests.
Documentation is in the docs/ directory.
The build/ directory is reserved for build artifacts.
Namespaces should match directories. For example, the namespaced function foo::bar::baz() should be declared in include/foo/bar/baz.h.

Functions#

Function and variable names should use underscore style.

When possible, use return values rather than output parameters. When output parameters are necessary, they should come before inputs in the function declaration so that default input values can be specified. For example: void foo(Out_Type1 &output1, Out_Type2 &output2, const In_Type1 &input1, const In_Type2 &input2)

Since there can be multiple approaches to the same problem, functions should be suffixed with the first three letters of the lead author’s surname and the year of publication (similar to some inline citation styles). For example: principal_curvature_rus2004

If you’re writing a new implementation of an existing function, then try to match the existing function’s interface. For example, if implementing a new principal curvature function, try to match the interface of modcam::mesh::principal_curvature_rus2004. This will make it easier for users to swap out different algorithms.

Documentation#

Functions should be documented using Doxygen in the Javadoc style. The documentation should follow Diataxis reference principles. Namely, it should be a neutral description of what the function does and how to use it. It should not attempt to instruct or explain why. How-to guides and tutorials cover instruction and explanation elsewhere.

Citations are strongly encouraged. Citation information should go in the BibTeX file docs/modCAM.bib. They can be referenced with the Doxygen @cite command.

Commit messages#

Git commit messages should follow the usual formatting rules. From https://cbea.ms/git-commit/:

Separate subject from body with a blank line
Limit the subject line to 50 characters
Capitalize the subject line
Do not end the subject line with a period
Use the imperative mood in the subject line
Wrap the body at 72 characters
Use the body to explain what and why vs. how

See the following resources for more information:

Changelog#

The changelog style is based on Common Changelog, though it’s been adapted for Calendar Versioning. Before merging a pull request, you should update the changelog according to the Common Changelog guidelines, with the following deviation:

Do not use the ## VERSION - DATE release header. Since modCAM uses Calendar Versioning, this info is filled in by the CI workflow. Instead, use a template placeholder:

## [LATEST] ([#<pull request number>](<pull request URL>))

Here, LATEST should be left as-is. The CI workflow will fill in the appropriate version. You should replace <pull request number> and <pull request URL> with the relevant pull request details.