Design decisions

Code standards are the rules every file follows; this folder is why the system is shaped the way it is.

One file per decision. Each states the decision, the reasoning, the alternatives rejected, and the consequences — including the bad ones.

Transport

• 0001 — Git lives at the root namespace, REST lives under /api
• 0019 — SSH is a second transport, not a second git
• 0002 — The transport layer takes streams, not Request/Response
• 0013 — The request body is captured before anything else can await
• 0014 — A flush-only POST is a probe, not a malformed push
• 0003 — git/ is not a REST resource

Storage and durability

• 0004 — Object storage is the source of truth, local disk is a cache
• 0005 — One commit point per push, and it is a compare-and-swap
• 0006 — Entries carry no sequence number
• 0007 — Optimistic concurrency, never locks
• 0008 — The log is a binary format
• 0009 — The index holds a ref snapshot, not a diff
• 0010 — Orphaned entries are garbage, never corruption
• 0012 — Materialization is forward-only replay
• 0015 — Nothing holds a packfile in memory
• 0020 — Deleting a repository is a tombstone, then a purge

Review

• 0016 — A pull request spans two logs, and lends objects rather than copying them
• 0017 — Issues are rows, not branches
• 0018 — Timestamps are timestamptz, never bare timestamp
• 0021 — Repository access is a role ladder, and an invitation grants nothing
• 0022 — Users and organizations share one namespace
• 0023 — Organization access is a base permission, raised per repository
• 0024 — Tags live in git, releases live in rows
• 0025 — Stored files are billed to the owning account, and the quota is configuration
• 0026 — A review is pinned to the head it read, and threads hang off its line comments
• 0027 — Squash and rebase carry the head along
• 0028 — Branch writes from the API are ref-only pushes
• 0029 — Repository events go through an outbox, and notifications are its first consumer
• 0030 — Columns are snake_case in the database, camelCase in the schema
• 0031 — Outbound delivery is its own service, and Postgres is its queue
• 0032 — GitHub imports run outside the API, which owns the retries
• 0033 — Pull requests keep refs/pull/<n>/head and /merge in the base log

Open

• 0011 — Deferred decisions