docs: add commit signing setup instructions to CONTRIBUTING.md

Add GPG and SSH signing setup guides, update commit requirements
to reference the new section, and fix markdown lint issues.

Fixes #138

Assisted-by: Claude <noreply@anthropic.com>
Signed-off-by: Andre Fredette <afredette@redhat.com>

Author: anfredette

CONTRIBUTING.md

@@ -1,43 +1,50 @@
 # Contributing to NeuralNav
 
-Thank you for your interest in contributing to NeuralNav! This document provides guidelines for contributing to the project.
+Thank you for your interest in contributing to NeuralNav! This document provides
+guidelines for contributing to the project.
 
 ## Table of Contents
 
 - [Code of Conduct](#code-of-conduct)
 - [Recommended Git Workflow](#recommended-git-workflow)
 - [Guidelines](#guidelines)
+- [Commit Signing Setup](#commit-signing-setup)
 - [Commit Message Guidelines](#commit-message-guidelines)
 - [Testing Requirements](#testing-requirements)
 - [Documentation](#documentation)
 - [Communication](#communication)
 
 ## Code of Conduct
 
-This project follows standard open source community guidelines. Be respectful, inclusive, and constructive in all interactions.
+This project follows standard open source community guidelines. Be respectful,
+inclusive, and constructive in all interactions.
 
 ## Recommended Git Workflow
 
-This section describes the complete workflow from setup to submitting a pull request.
+This section describes the complete workflow from setup to submitting a pull
+request.
 
 ### Initial Setup (One-Time)
 
 **1. Fork the repository** on GitHub to your own account.
 
 **2. Clone your fork locally:**
+
 ```bash
 git clone https://github.com/YOUR_USERNAME/neuralnav.git
 cd neuralnav
 ```
 
 **3. Set up remotes:**
+
 ```bash
 # Your fork is already set as 'origin' by the clone
 # Add the main repository as 'upstream'
 git remote add upstream https://github.com/redhat-et/neuralnav.git
 ```
 
 Verify your remotes:
+
 ```bash
 git remote -v
 # origin    https://github.com/YOUR_USERNAME/neuralnav.git (fetch)
@@ -46,84 +53,100 @@ git remote -v
 # upstream  https://github.com/redhat-et/neuralnav.git (push)
 ```
 
-**4. Set up your development environment** by following the [Quick Start guide](README.md#quick-start).
+**4. Set up your development environment** by following the [Quick Start
+guide](README.md#quick-start).
 
 ### Keep Your Main Branch Synchronized
 
 Before starting new work, sync your local main with upstream:
+
 ```bash
 git checkout main
 git fetch upstream
 git rebase upstream/main
 git push origin main    # Keeps your fork's main updated on GitHub
 ```
 
-NOTE: Don't make any changes directly on your fork's main branch -- keep it in sync with upstream/main.
+NOTE: Don't make any changes directly on your fork's main branch -- keep it in
+sync with upstream/main.
 
 ### Development Workflow
 
 **1. Create a branch from main:**
+
 ```bash
 git checkout main
 git checkout -b your-feature-name  # branch names like feature/your-feature-name are common but not required.
 git push -u origin your-feature-name
 ```
 
-The `-u` flag sets up tracking so future `git push` and `git pull` commands work without specifying the remote.
+The `-u` flag sets up tracking so future `git push` and `git pull` commands work
+without specifying the remote.
 
 **2. Do your work and create logical commits:**
+
 ```bash
 # Make changes...
 git add <files>
 git commit -s -m "feat: Add your feature description"
 ```
 
-Use the `-s` flag to add the required DCO sign-off. See [Commit Message Guidelines](#commit-message-guidelines) for formatting details.
+Use the `-s` flag to add the required DCO sign-off. See [Commit Message
+Guidelines](#commit-message-guidelines) for formatting details.
 
 **3. Push to your fork:**
+
 ```bash
 git push
 ```
 
 ### Submitting a Pull Request
 
 **1. Before submitting, rebase on upstream/main:**
+
 ```bash
 git fetch upstream
 git rebase upstream/main
 ```
 
-Resolve any conflicts if they occur, then force push (needed because rebasing rewrites history):
+Resolve any conflicts if they occur, then force push (needed because rebasing
+rewrites history):
+
 ```bash
 git push -f
 ```
 
 **2. Run tests locally:**
+
 ```bash
 make test
 make lint
 ```
 
 **3. Create the PR from GitHub:**
 
-When you're ready to submit your changes in a PR, visit either your fork or the main repo on GitHub. 
-If you've pushed recently, you'll see a prompt: "Compare & pull request" — click it.
+When you're ready to submit your changes in a PR, visit either your fork or the
+main repo on GitHub. If you've pushed recently, you'll see a prompt: "Compare &
+pull request" — click it.
 
-Alternatively, go to the upstream repository and click "New pull request", then select your fork and branch.
+Alternatively, go to the upstream repository and click "New pull request", then
+select your fork and branch.
 
 ## Guidelines
 
 ### Discuss Before You Code
 
 **For significant changes**, discuss your approach upfront:
 - Open an issue describing the problem and proposed solution
-- For substantial features or architectural changes, create a design document in `docs/`
+- For substantial features or architectural changes, create a design document in
+  `docs/`
 - Wait for feedback from maintainers before investing significant effort
 - Small bug fixes and typos don't require prior discussion
 
 ### Keep PRs Small and Targeted
 
-- **Aim for PRs under 500 lines** whenever possible (not counting auto-generated code)
+- **Aim for PRs under 500 lines** whenever possible (not counting auto-generated
+  code)
 - Each PR should address a single concern or feature
 - Break large features into incremental PRs that preserve functionality
 - Incremental PRs should:
@@ -133,6 +156,7 @@ Alternatively, go to the upstream repository and click "New pull request", then
   - Update documentation as needed
 
 **Example of breaking up a large feature**:
+
 ```
 PR 1: Add database schema for new feature (no breaking changes)
 PR 2: Implement backend API endpoints with tests
@@ -146,7 +170,8 @@ If a breaking change is unavoidable:
 - Discuss in an issue first with the "breaking-change" label
 - Document the migration path clearly
 - Consider deprecation warnings before removal
-- For very large refactors, consider working from a branch in the main repository
+- For very large refactors, consider working from a branch in the main
+  repository
 - Provide upgrade instructions in the PR description
 
 ### PR Requirements
@@ -197,6 +222,76 @@ Fixes #[issue number]
 - Rebase and force-push if requested (don't create merge commits)
 - Be open to suggestions and iterate on your implementation
 
+## Commit Signing Setup
+
+All commits must be cryptographically signed. You can use either GPG or SSH
+signing — choose whichever you prefer.
+
+### Option A: SSH Signing (Recommended)
+
+SSH signing reuses keys you likely already have.
+
+**1. Configure git to sign commits with SSH:**
+
+```bash
+git config --global commit.gpgsign true
+git config --global gpg.format ssh
+git config --global user.signingkey ~/.ssh/id_ed25519.pub
+```
+
+Replace `~/.ssh/id_ed25519.pub` with the path to your actual SSH public key
+(e.g., `~/.ssh/id_rsa.pub`).
+
+**2. Add your key to GitHub** as a **Signing Key** (not just Authentication):
+
+- Go to **GitHub > Settings > SSH and GPG keys > New SSH key**
+- Set **Key type** to **Signing Key**
+- Paste your public key
+
+### Option B: GPG Signing
+
+**1. Generate a GPG key** (if you don't have one):
+
+```bash
+gpg --full-generate-key
+```
+
+Select RSA 4096-bit, and use the same email as your GitHub account.
+
+**2. Get your key ID:**
+
+```bash
+gpg --list-secret-keys --keyid-format=long
+```
+
+Look for the key ID after `sec rsa4096/` (e.g., `ABCDEF1234567890`).
+
+**3. Configure git:**
+
+```bash
+git config --global commit.gpgsign true
+git config --global user.signingkey ABCDEF1234567890
+```
+
+**4. Add your GPG key to GitHub:**
+
+```bash
+gpg --armor --export ABCDEF1234567890
+```
+
+Copy the output and add it at **GitHub > Settings > SSH and GPG keys > New GPG
+key**.
+
+### Verifying Your Setup
+
+After setup, make a test commit and verify it shows as signed:
+
+```bash
+git log --show-signature -1
+```
+
+On GitHub, signed commits display a **Verified** badge.
+
 ## Commit Message Guidelines
 
 ### Format
@@ -227,10 +322,16 @@ Follow the [Conventional Commits](https://www.conventionalcommits.org/) style:
   - Bad: "Added GPU costs" or "This adds GPU cost calculation"
 - **Body**: Wrap at 72 characters, explain what and why (not how)
 - **Sign-off**: Include DCO sign-off with `-s` flag:
+
   ```bash
   git commit -s -m "feat: Add support for custom SLO templates"
   ```
-- **AI Assistance**: Nontrivial and substantial AI-generated or AI-assisted content should be “marked”.  Using the `Assisted-by:` tag is recommended as shown in the following example:
+
+- **Signing**: All commits must be cryptographically signed (GPG or SSH). See
+  [Commit Signing Setup](#commit-signing-setup) for configuration.
+- **AI Assistance**: Nontrivial and substantial AI-generated or AI-assisted
+  content should be “marked”.  Using the `Assisted-by:` tag is recommended as
+  shown in the following example:
 
   ```
   Assisted-by: Claude <noreply@anthropic.com>
@@ -314,10 +415,12 @@ make format
 ### Stay in Touch
 
 - **Rebase often**: Keep your branch up-to-date with upstream/main
+
   ```bash
   git fetch upstream
   git rebase upstream/main
   ```
+
 - **Communicate frequently**:
   - Comment on issues and PRs
   - Ask questions if requirements are unclear
@@ -332,7 +435,8 @@ make format
 
 ## License
 
-By contributing to NeuralNav, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)).
+By contributing to NeuralNav, you agree that your contributions will be licensed
+under the same license as the project (see [LICENSE](LICENSE)).
 
 ## Questions?