itsgoin/CONTRIBUTING.md

Contributing to ItsGoin

This document defines how all contributors — human and Claude Code instances — work on this repository. It is authoritative policy; follow it regardless of whether you are the primary context-holder or a newly-joined contributor.

---

Status

Adopted: 2026-04-23. The workflow below is policy, but some of its prerequisites are still being stood up. Until the Phase 0 checklist at the bottom of this file is complete, certain rules that reference infrastructure (e.g. "wait for CI to pass") are aspirational. The branching, PR, and review rules are in effect immediately. See the Phase 0 section for current state.

---

Core rules (all contributors)

Branching

• Never commit or push directly to master. Master is only updated through merged PRs.
• Before starting work, create a branch tied to a Forgejo issue:

  git checkout -b <type>/<issue-number>-<short-desc>
  

  • Types: feat, fix, refactor, chore, docs
  • Example: feat/142-pq-key-exchange, fix/89-anchor-handshake-timeout
• One branch per issue. If there's no issue yet, create one first.
• Keep branches short-lived — hours to a couple of days. Long branches accumulate conflicts.

Commits

• Commit early, commit often. WIP commits are fine; squash before PR if you want a cleaner history.
• Use imperative mood: "Add retry logic" not "Added retry logic".
• Reference the issue in the message: Fix anchor handshake timeout (#89).

Staying current with master

Before pushing, always:

git fetch origin
git rebase origin/master

Resolve conflicts locally, then push. If a rebase goes sideways, git rebase --abort safely returns you to where you started.

Pushing and opening PRs

• Push to your own branch: git push origin <branch-name>.
• Open a PR in Forgejo targeting master. Fill in the description: what, why, how tested.
• Link the Forgejo issue.
• Wait for CI to pass (once CI exists — see Phase 0) and at least one peer review before merging.

Force-pushing

• Never use git push --force.
• git push --force-with-lease is acceptable only on your own feature branch and only when you are its sole contributor.
• Never force-push to master or any shared branch.

Absolutely forbidden

• git push --force (without --with-lease)
• git reset --hard on a branch containing uncommitted work you didn't author
• Rebasing a branch another contributor is committing to
• Merging your own PR without review (unless explicitly authorized by Scott)
• Committing secrets, credentials, API keys, or large binaries
• Bypassing .deploy-creds into git history (it's .gitignored; keep it that way)

Before any destructive operation

Always check:

git status
git branch --show-current
git log -5 --oneline

Know what branch you're on and what you'd lose before you lose it.

---

Session protocol

Starting a session

1. git fetch origin
2. Read the latest sessions.md entries to understand recent state.
3. Pick or confirm your assigned Forgejo issue. Verify no other contributor is actively working it.
4. Create your branch from current master.
5. Append to sessions.md: timestamp, your instance identifier, issue number, branch name.

Ending a session

1. Commit any WIP with a clear message.
2. Push your branch if it's in a shareable state.
3. Update sessions.md with what you completed, what's pending, blockers, and your exact stopping point.
4. If work is ready, open the PR before signing off.

---

Reviewing PRs

• Any contributor can review any PR. Cross-review (reviewer ≠ author) is strongly preferred.
• Focus on intent and design — CI handles formatting, tests, and lints.
• Approvals should include a brief "why." Change requests should be specific.
• Scott is the tiebreaker for genuine disagreements, not the default reviewer.

---

Role-specific notes

Primary contributor (highest project context — "Lead")

• You have no special merge authority for normal PRs. Branch protection is the master manager, not you.
• Expect to be tagged for review on architecturally significant PRs. Prioritize these.
• You're often the best source for "why is this code this way?" — write that reasoning into PR reviews so the knowledge spreads to other contributors.
• Do not approve your own PRs. Having more context is not a substitute for peer review.

Lead role responsibilities (current Lead = Scott's Claude):

• Review PRs that Scott routes to you. Pull the branch, run cargo check --workspace + cargo test -p itsgoin-core, read for semantic issues that clean-merged textually but may break compile / violate invariants / change behavior subtly.
• Take dev work on senior-category issues only: protocol, crypto, concurrency / locking, receive_post gate changes, identity/network split, architectural refactors, production hotfixes.
• Own the full build + deploy pipeline: CLI + AppImage + APK on Linux; signing; uploads; anchor swap; release-announcement publish.
• Maintain reference_build_deploy.md, AGENTS.md, and your own sessions.md entries for any active branch.

Lead does NOT:

• Track who is working on what (Scott coordinates).
• Authorize anyone for anything (Scott authorizes).
• Answer jr questions unprompted (Scott pings you with specific ones when needed).
• Decide jr- vs senior-category scoping (Scott triages).
• Windows installer builds, iOS/Mac builds (handed off to environment-bound builders).

Secondary / newly-joined contributors ("Jr")

• Before writing code, read AGENTS.md, CONTRIBUTING.md (this file), and the last several sessions.md entries.
• If unsure whether an approach fits the project's existing patterns, ask Scott to route the question to the Lead before investing in the implementation.
• Defer to established architectural decisions unless you have a specific, articulable reason to revisit them. If you want to revisit, open a discussion issue first — not a PR.

---

Amendments to the base workflow (2026-04-23)

These adjust the generic contributor doc to ItsGoin's specific operational realities. They are policy, not suggestions.

1. Hotfix carve-out

For true production-down scenarios the Lead retains direct-to-master authority, bypassing branch + PR + review. Scope is narrow and specific:

• Anchor won't start / crash loop
• TLS handshake broken for all clients
• Storage corruption / migration failure
• Active security incident (e.g. key compromise, auth bypass)

Requirements when the carve-out is exercised:

1. Commit message must begin with hotfix: and clearly describe the production symptom.
2. A retrospective PR must be opened within 24 hours for review-after-the-fact. Purpose is audit trail + sanity check, not gating.
3. Logged in sessions.md with timestamp + what was broken + what was changed.

This does not apply to: routine bugs, feature requests flagged urgent, UX polish, or any case where the network is operational.

2. Build trigger: explicit

Builds and deploys happen only when Scott says "ship it" (or equivalent explicit authorization). There is no rolling auto-deploy on merge, no N-PRs-threshold that triggers a build automatically. This reduces surprise deploys and keeps release cadence under human control.

3. Review SLA: natural stopping point

When Scott routes a PR to the Lead for review, the Lead finishes the current task before picking it up. No hard time budget. The only exception: if a Jr is blocked on the review AND Scott flags it urgent, the Lead preempts.

4. Re-evaluation triggers for the Lead role

The current Lead role is "senior-category dev + reviewer + build/deploy owner." Shift to pure-reviewer/integrator (drop the dev hat) if any of these hold:

• 5+ concurrent Jr agents active
• Lead review queue regularly runs past 1-day latency
• Lead finds themselves rewriting Jr PRs in review rather than commenting
• Scott's coordination / routing load hits his limit

These are triggers for reassessment, not automatic policy flips.

5. Secrets and credentials

• .deploy-creds is .gitignored. Never commit it.
• Each contributor instance gets its own Forgejo account + SSH key (see Identity section below). Never share credentials.

---

Identity

Each instance has its own Forgejo account and SSH key. Set local Git config per repo:

git config user.name "Claude (<role-or-identifier>)"
git config user.email "<your-account>@<domain>"

• Never use another instance's credentials.
• Never share your own.
• Commit authorship is how we audit and debug multi-agent work. Keep it clean.

---

When in doubt

Stop and ask. A paused session is cheap; overwritten work is expensive. If something about the repo state looks unexpected (unfamiliar commits, a branch in a weird position, a conflict you don't understand), do not "fix" it autonomously — note it in sessions.md and surface it to Scott.

---

Phase 0 checklist — prerequisites still pending

These must be true before the full workflow above is operational. Until each is checked, the corresponding rule is aspirational and contributors should route around it by asking Scott.

• Forgejo CI stood up (minimum: cargo check --workspace + cargo test -p itsgoin-core on push to any branch and on PR).
• Branch protection enabled on master: require PR, require 1 passing review, require CI green.
• sessions.md exists in the repo root (this PR creates it).
• Second Forgejo account created for Jr Claude(s) with its own SSH key configured.
• AGENTS.md exists in the repo root (this PR creates it; cross-agent session guide — see security banner at top of that file).

Note on CLAUDE.md specifically: it is .gitignored at the repo root because historically AI agents (including Claude) have dropped credentials into a CLAUDE.md-style file and those leaks are catastrophic in git history. AGENTS.md replaces it as the committed contributor-facing guide, with an explicit security banner forbidding credential writes. If a Claude instance needs a local scratch file, it can still use CLAUDE.md in the working copy — just knowing it will never reach the repo.

Current state as of 2026-04-23: this PR (chore/workflow-adoption) creates CONTRIBUTING.md, AGENTS.md, and sessions.md. The remaining items (CI + branch protection + Jr account) are follow-up work Scott will coordinate.

Until CI exists, the Lead's cargo check --workspace + cargo test -p itsgoin-core during PR review serves as the CI gate.