Skip to content

docs: add commit signing setup instructions to CONTRIBUTING.md #143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
anfredette merged 1 commit into from
Apr 1, 2026
Merged

docs: add commit signing setup instructions to CONTRIBUTING.md #143

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 120 additions & 16 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Expand All @@ -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:
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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
Expand All @@ -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?

Expand Down
Loading