# 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 /- ``` - 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 `. - 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 `.gitignore`d. 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 ()" git config user.email "@" ``` - 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. - [x] `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. - [x] `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 `.gitignore`d 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.