From 63c1255420fe671a0b52b847fecf818e56f5e3ee Mon Sep 17 00:00:00 2001
From: Nathan Castaldi <Nathan.Castaldi+Wheels@wheels.com>
Date: Thu, 16 Apr 2026 09:07:20 -0400
Subject: [PATCH] feat: add contributing guidelines to establish intentional
 Git workflow

---
 CONTRIBUTING.md | 181 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 181 insertions(+)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..c5094c5
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,181 @@
+# Contributing Guidelines
+
+This document describes the **intentional Git workflow** used in this repository. The goal is to keep history clean, minimize merge noise, and reduce unnecessary process overhead while still staying safe and deliberate.
+
+These guidelines assume:
+
+* Short‑lived feature branches
+* Primarily independent, non‑overlapping changes
+* Emphasis on clarity and intent over automation
+
+***
+
+## Branching Strategy
+
+### Main branch (`main`)
+
+* `main` represents **stable, reviewable history**
+* Changes land on `main` via pull requests (PRs)
+* Direct commits to `main` should be avoided unless explicitly approved
+
+***
+
+### Feature branches
+
+* New work should be done on feature branches:
+  * feat/short-description
+  * project/short-description
+  * chore/short-description
+* Feature branches should be **focused and intentional**
+* Avoid mixing unrelated work in the same branch
+
+Example:
+
+```bash
+git switch -c feat-reporting-shard
+```
+
+***
+
+## Keeping Feature Branches Up to Date
+
+Feature branches are **not required** to be constantly rebased against `main`.
+
+### Default rule (most of the time)
+
+> **Do nothing. Keep working.**
+
+If your branch:
+
+* Is independent
+* Is not affected by recent `main` changes
+* Is developing cleanly and testing successfully
+
+…then there is no requirement to update it mid‑stream.
+
+Rebasing is considered a **tool**, not a requirement.
+
+***
+
+### When rebasing *is* appropriate
+
+Rebase a feature branch onto `main` when:
+
+* `main` has received changes that affect your branch’s behavior
+* You are preparing to open a PR
+* You want to reduce integration risk before merging
+
+***
+
+### How to rebase correctly (Option A)
+
+> Rebasing always affects **only the current branch**, not `main`.
+
+From the feature branch:
+
+```bash
+git status        # confirm you are on the feature branch
+git fetch origin
+git rebase origin/main
+```
+
+This:
+
+* Replays the feature branch’s commits on top of the latest `main`
+* Does **not** modify `main`
+* May create new commit hashes for the feature branch only
+
+If there are no new commits on `main`, rebasing is unnecessary and should be skipped.
+
+***
+
+## Decision Check Before Rebasing
+
+Before rebasing, confirm whether it provides value:
+
+```bash
+git fetch origin
+git log --oneline HEAD..origin/main
+```
+
+* If this command shows **no commits**, rebasing offers no benefit
+* In that case: **do nothing and continue working**
+
+***
+
+## Pull Requests and Merging
+
+Before opening a PR:
+
+1. Ensure the branch builds and tests cleanly
+2. Optionally rebase onto the latest `main`
+3. Confirm the branch scope is intentional and self‑contained
+
+After merge:
+
+* Delete the feature branch (local and remote)
+* Avoid leaving stale branches behind
+
+***
+
+## Handling Accidental Commits on the Wrong Branch
+
+If a commit is made on the wrong branch:
+
+### If the commit logically belongs to the feature
+
+✅ Leave it — no action needed.
+
+### If the commit belongs on `main`
+
+Use a **cherry‑pick + reset** workflow:
+
+1. Cherry‑pick the commit onto `main`
+2. Reset the feature branch back to its remote state
+
+This avoids rebasing or rewriting shared history.
+
+***
+
+## Branch Cleanup
+
+To identify local branches whose upstream no longer exists:
+
+```bash
+git branch -vv | grep ': gone]'
+```
+
+If confirmed obsolete, delete intentionally:
+
+```bash
+git branch -D <branch-name>
+```
+
+Branch deletion is considered part of normal repo hygiene.
+
+***
+
+## Guiding Principles
+
+* Prefer **clarity over cleverness**
+* Rebasing is optional, intentional, and local
+* Doing nothing is a valid decision
+* The branch you are *on* is the only branch modified by rebase
+* Clean history is valuable, but not at the expense of momentum
+
+***
+
+## Summary
+
+This workflow aims to:
+
+* Reduce cognitive overhead
+* Avoid unnecessary Git operations
+* Keep history readable and intentional
+* Reflect how work is actually done, not how tools are marketed
+
+If you are unsure whether to rebase, merge, or wait:
+
+> **Stop, check the current state, and choose the smallest action that solves the problem.**
+
+***