Skip to content

Contributing

Jump to bottom
BenJule edited this page May 31, 2026 · 2 revisions

Contributing

All contributions — from bug fixes to new features — are welcome. This page documents the required workflow. Please read it fully before opening a PR.

Workflow Overview

Open Issue → Create Branch → Commit → Open PR → Copilot Review → Fix → CI Green → Squash Merge

Important

Never push directly to master. Every change — including trivial fixes — must go through a pull request. Master has required status checks and signed-commit enforcement.

Step 1 — Open an Issue

Before writing code, open an issue:

  • Use the appropriate issue template
  • Set the milestone (currently v02.07.00-dev)
  • Assign BenJule as assignee
  • Apply the relevant label (bug, enhancement, ci/cd, etc.)

This ensures work is tracked and avoids duplicate effort.

Step 2 — Create a Branch

Branch off master:

git checkout master && git pull
git checkout -b fix/short-description     # for bug fixes
git checkout -b feat/short-description    # for features
git checkout -b ci/short-description      # for CI/CD changes
git checkout -b docs/short-description    # for documentation

Branch naming convention:

Prefix Use for
fix/ Bug fixes
feat/ New features
ci/ CI/CD workflow changes
docs/ Documentation only
refactor/ Refactoring without behaviour change
chore/ Maintenance, dependency bumps

Step 3 — Commit

Commit Message Format

Use the conventional commits style:

type(scope): short description

Optional longer body explaining the why, not the what.
Type Use for
fix Bug fix
feat New feature
ci CI/CD change
docs Documentation
refactor Code refactor
chore Maintenance
test Test additions/changes

Examples:

fix(ui): suppress gtk_window_resize assertion on Wayland startup
feat(pkg): add ccache to Debian trixie package build
ci: skip Fedora and Ubuntu builds when only docs changed

Commit Signing

All commits to master must be GPG-signed. Configure signing once:

gpg --full-generate-key          # generate a key if you don't have one
gpg --list-secret-keys --keyid-format LONG

git config --global user.signingkey YOUR_KEY_ID
git config --global commit.gpgsign true

Sign a commit manually:

git commit -S -m "fix(ui): ..."

Verify your commits are signed:

git log --show-signature -1

Note

Unsigned commits will be rejected by the branch protection rule on master. Your PR branch does not need signed commits — only the final squash-merge commit does, which GitHub creates automatically.

Step 4 — Open a Pull Request

git push origin your-branch-name
gh pr create --title "fix(ui): short description" \
             --body "Closes #<issue-number>"

PR requirements:

  • Title follows conventional commits format
  • Body references the issue: Closes #N
  • Milestone set to current milestone
  • Assignee set to BenJule

The PR template includes a checklist — fill it out.

Step 5 — Copilot Code Review

After CI completes, request a Copilot review:

  1. Go to the PR on GitHub
  2. In the Reviewers sidebar, click the gear icon
  3. Select Copilot and click Request

Note

Copilot review cannot be triggered from the CLI in this repository. Use the GitHub UI only.

Address all medium and high severity findings before requesting another review. Low severity findings should be evaluated and either fixed or explicitly dismissed with a comment explaining why.

Iterate (push additional commits, re-request review) until Copilot generates no new comments.

Step 6 — Merge

Once:

  • ✅ All required status checks pass (Detect affected platforms, Linux / Debian trixie .deb, Review dependency changes)
  • ✅ All PR conversations are resolved
  • ✅ Copilot review is clean

→ Squash merge the PR. This produces a single clean commit on master.

Code Style

C++

All C++ code must be formatted with clang-format-18. The configuration is in .clang-format at the repository root.

Check formatting before committing:

git diff --name-only HEAD | grep -E '\.(cpp|cc|cxx|h|hpp)$' \
  | xargs clang-format-18 --dry-run --Werror

Auto-fix formatting:

git diff --name-only HEAD | grep -E '\.(cpp|cc|cxx|h|hpp)$' \
  | xargs clang-format-18 -i

The ci-pull-request.yml workflow checks formatting automatically on every PR.

CMake

Follow the existing style in CMakeLists.txt files. Use lowercase commands.

YAML (GitHub Actions)

  • Use 2-space indentation
  • Pin all uses: to a full commit SHA with a version comment: uses: actions/checkout@abc123 # v4
  • Always set egress-policy: audit via Harden Runner

Pull Request Checklist

Before marking your PR as ready for review:

  • Code compiles without warnings on the target platform
  • Tested locally on at least one platform
  • C++ files formatted with clang-format-18
  • PR title follows conventional commits format
  • Issue referenced with Closes #N
  • Milestone and assignee set
  • No new Dependabot security alerts introduced
  • version.inc bumped if this PR should trigger a new release build

Dependabot PRs

Dependabot opens PRs for GitHub Actions and npm dependency updates weekly. These require manual review because the required-signatures branch protection prevents auto-merge.

To merge a Dependabot PR:

  1. Review the diff (usually a SHA/version bump)
  2. Check the linked release notes for breaking changes
  3. Approve and squash-merge normally

Branch Protection Rules (master)

Rule Setting
Required status checks Detect affected platforms, Linux / Debian trixie .deb, Review dependency changes
Require branches to be up to date No (not enforced — reduces friction)
Require conversation resolution Yes
Require signed commits Yes
Force push Blocked
Branch deletion Blocked
Enforce admins Yes

Clone this wiki locally