Version Control

CEM-006

Standardizing the use of Git ensures a clean history, simplifies automated tooling, and improves the review process.

Commit Message Formatting (CEM-006-000)

Specification 🤖

All commits must adhere to the Conventional Commits Specification defined below:

Conventional Commits

Attribute

Format

Description

Type

feat, fix, docs, style, refactor, test, chore

Mandatory prefix indicating the nature of the change.

Scope

(optional, e.g., (api), (ui))

Optional context for the change.

Subject

imperative tense

Mandatory concise description of the change.

Body

Detailed explanation of the change

Optional concise description. If generated by a coding agent, add the prompt.

Footer

Closes #XXX, BREAKING CHANGE: …

Optional, for referencing issues or noting breaking changes.

Examples

fix(core): update build script dependency
Fixes a vulnerability in the outdated `webpack-config` package.
This required updating the Node environment, which is a breaking change for CI.
BREAKING CHANGE: Requires Node.js v18 or higher.

Motivation

  • Automated generation of changelogs

  • Automated semantic versioning

Blueprint

  • Pre-commit Hooks

  • CI/CD Pipelines TODO add URL to GitHub repo

  • Codex Config File TODO add URL to GitHub repo

  • Claude Config File TODO add URL to GitHub repo

Verified Commits (CEM-006-001)

Specification

Any commit must be a verified commit, i.e., it must contain cryptographic evidence that it was made by the person it claims to be from.

Motivation

  • Authenticity: Signed commits verify the true author.

  • Integrity: Guarantees code has not been altered since signing.

  • Accountability: Every change is traceable to a verified individual.

  • Trust in collaboration: Maintains trust in multi-contributor projects.

  • Security: Helps protect against supply chain attacks.

Blueprint

# Install GPG
sudo apt-get update && sudo apt-get install gnupg

# Generate a new GPG key (select RSA with a 4096 bits key, use your GitHub user name and email when prompted)
gpg --full-generate-key

# List your GPG keys to find your key ID
# Look for the line:
# sec   rsa4096/XXXXXXXXXXXXXXXX 2026-01-28 [SC]
gpg --list-secret-keys --keyid-format=long

# Copy your public key to the clipboard (replace XXXXXXXXXXXXXXXX with your key ID)
gpg --armor --export XXXXXXXXXXXXXXXX

# Add your GPG public key to GitHub:
#   - Go to GitHub > Settings > SSH and GPG keys > New GPG key
#   - Paste the key and save

# Configure Git to use your signing key for this repository
git config user.signingkey XXXXXXXXXXXXXXXX
git config commit.gpgsign true

# Now, all commits in this repo will be signed by default
git commit -m "feat(git): Look at that, it's verified!"