Contributing

Hi, glad you are here. First, we setup the development environment so you are aligned with all other contributors.

Development Setup

Setting up the git repository locally

# Fork the repo (from Codeberg GUI) then clone
git clone https://codeberg.org/dpaletti/openorti.git
cd openorti

# Keep it updated with upstream
git remote add upstream https://codeberg.org/dpaletti/openorti.git
git fetch upstream

# Create your branch
git checkout -b <branch_name>

Installing development tools

Hardware development happens on KiCad, grab the latest version on the official site.

We use REUSE to ensure license compliance. Install it through UV:

# Install UV if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install reuse without interfering with pre-existing python packages
uv tool install reuse

Add copyright and a license to new files with reuse annotate, using the license that matches:

Files	License (SPDX)
hardware/** design files	CERN-OHL-S-2.0
Markdown documentation	CC-BY-SA-4.0
Software and firmware	GPL-3.0-or-later

reuse download "<SPDX id>"   # only if LICENSES/<SPDX id>.txt is missing
reuse annotate \
  --copyright "<codeberg.org/dpaletti/openorti> contributors" \
  --license "<SPDX id>" \
  <file>

We run the Git hooks with prek. Install it through UV as well:

uv tool install prek

Git hooks

Activate the hooks with:

prek install

The pre-commit hooks check for private keys and format the Markdown files. The pre-push hook checks that the files are REUSE compliant. The same hooks run in Codeberg CI.

Previewing the documentation

uv run mkdocs serve

Served at http://127.0.0.1:8000/openorti/.

Developer Certificate of Origin (DCO)

Commits need to be signed to comply with the DCO.

To sign your commit, just add the -s flag when committing:

git commit -s -m "your commit message"

This appends a line like:

Signed-off-by: Your Name <your.email@example.com>

We won't merge commits if they aren't signed off. If you forget, you can amend the last commit like this:

git commit --amend -s

If you're submitting a PR with multiple commits make sure each one is signed.

For JJ users you can add this to your config:

[templates]
commit_trailers = '"Signed-off-by: " ++ author.name() ++ " <" ++ author.email() ++ ">"'

commit_trailers is applied whenever a commit description is written, including non-interactive commands such as jj describe -m, jj new -m and jj commit -m. It also deduplicates trailer lines, so re-describing a commit will not append the same trailer twice.

Do not use templates.draft_commit_description for this: it only seeds the editor, so it silently does nothing when you pass -m. That is the usual reason a commit ends up without a Signed-off-by trailer.