From f25f71d27bdace632a4c239c39308c8a2064c56e Mon Sep 17 00:00:00 2001 From: Andre Fredette Date: Mon, 30 Mar 2026 17:02:08 -0400 Subject: [PATCH] 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 Signed-off-by: Andre Fredette --- CONTRIBUTING.md | 136 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 120 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0092c000..7f9fbbc1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,12 +1,14 @@ # 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) @@ -14,23 +16,27 @@ Thank you for your interest in contributing to NeuralNav! This document provides ## 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' @@ -38,6 +44,7 @@ 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,11 +53,13 @@ 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 @@ -58,29 +67,35 @@ 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 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 ``` @@ -88,17 +103,21 @@ 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 @@ -106,10 +125,12 @@ 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 @@ -117,13 +138,15 @@ Alternatively, go to the upstream repository and click "New pull request", then **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 @@ -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?