Contributing to sw2102-docs¶

This repo is the canonical documentation home for SectorWars 2102. It exists separately from the code repos (Sectorwars2102, sw2102-bang) so that design intent, system specs, and feature definitions can be reasoned about independently of any one implementation snapshot.

If you're new, read this file before editing or adding documentation.

When to add a doc here vs. in another repo¶

Add a doc to sw2102-docs when it describes:

How the game should work (rules, flows, balance, governance).
A system or subsystem that spans services or repos.
An API surface, data model, or operational concern that other contributors need to reference.
A definition or convention that should be authoritative.

Keep a doc in the source repo (e.g. Sectorwars2102/, sw2102-bang/) when it is:

A README explaining how to build, run, or develop that specific repo.
An inline code comment, module docstring, or implementation note.
A throwaway investigation or change log tied to a single PR.

Rule of thumb: if a doc would survive a full rewrite of the implementation, it belongs here.

Where does each section live and what belongs in it¶

Folder	Purpose	Examples
`ARCHITECTURE/`	System topology, services, deployment, dev environment.	service inventory, container layout, environment matrix
`DATA_MODELS/`	Entities, schema, migrations, persistence rules.	per-entity reference docs, migration policy
`FEATURES/`	What the game does, organized by player-visible concern. Only place implementation status lives.	gameplay rules, economy, galaxy, planets
`OPERATIONS/`	Cross-cutting operational concerns.	admin UI, player client, ARIA, i18n, multi-regional, realtime
`SYSTEMS/`	Prescriptive subsystem specs (one file per named subsystem).	combat resolver, market pricing, galaxy generation, realtime bus
`ADR/`	Architecture Decision Records.	one numbered file per significant architectural choice

Top-level files (README.md, CONTRIBUTING.md, GLOSSARY.md, TESTING.md) are foundational/meta and apply across all sections.

If a doc doesn't fit any existing section, propose a new top-level section in your PR rather than burying it.

Status convention¶

Implementation status lives in FEATURES/ only, marked inline beside the feature, mechanic, or rule it describes. Use one of four markers:

Marker	Meaning	When to apply
`✅ Shipped`	Implemented in the source repo and behaving as specified.	The behaviour exists in `Sectorwars2102` and matches the doc.
`🚧 Partial`	Some of the behaviour is implemented; the rest is not.	Code is present but incomplete, behind a flag, or with known gaps.
`📐 Design-only`	Specified here but not yet built.	The design is settled enough to document, but no production code exists.
`🐛 Bug`	Implemented, but the live behaviour diverges from this spec.	Live code disagrees with the spec, and the spec is the target.

All other folders (ARCHITECTURE/, DATA_MODELS/, OPERATIONS/, SYSTEMS/, ADR/) describe the target state. They do not carry status markers.

The REST API surface is intentionally not documented in this repo — the gameserver auto-publishes it at <api-host>/docs (Swagger), <api-host>/redoc, and <api-host>/openapi.json. WebSocket protocol design lives in SYSTEMS/realtime-bus.md.

If you find yourself wanting to track status outside FEATURES/, the right move is usually to add a feature entry that points at the system doc.

Phase tags¶

Each doc may carry one or more phase tags in YAML frontmatter to indicate where the documented behavior fits in the project's release timeline. The site filters by these tags. See tags.md for the rendered tag index.

The controlled vocabulary is exactly two values:

Launch — the end-state we're designing toward. Most prescriptive specs in this repo describe Launch behavior.
Current — the behavior actually shipped today. May be a subset of Launch, or may diverge while implementation catches up.

Tags are added at the very top of a markdown file:

---
tags:
  - Launch
---

A doc tagged only Launch describes the target. A doc tagged only Current describes shipped behavior. A doc tagged both means the Launch spec is fully implemented today.

When Launch and Current need to diverge meaningfully, prefer splitting a single page into two (e.g., a Launch end-state file plus a Current shipped-state file) rather than juggling both states in one doc.

tags_allowed in mkdocs.yml enforces the vocabulary — adding a tag outside the list will fail the build. Adding a new phase tag requires team agreement and a matching update to tags.md and mkdocs.yml.

Filename and folder rules¶

Files: lowercase-with-hyphens, .md extension. Example: first-login.md, combat-resolver.md.
Top-level folders: ALL CAPS. Example: FEATURES/, OPERATIONS/.
Subfolders: lowercase. Example: FEATURES/gameplay/, FEATURES/economy/.
Index files: every section folder has its own README.md acting as the index for that area.
No spaces, no underscores in filenames.

Cross-linking rules¶

Use repo-relative paths. From OPERATIONS/realtime.md to SYSTEMS/realtime-bus.md, write ../SYSTEMS/realtime-bus.md.
Do not use absolute filesystem paths.
Do not link to external commit SHAs in the source repos; link to a path under the source repo's main if you must, but prefer prose ("see services/gameserver/src/services/combat_service.py") so the reference survives a refactor.
When citing source files, use the repo-relative path within the source repo (e.g. services/gameserver/src/models/ship.py). These citations describe where the target code should live, not necessarily what is committed today.
When a term is defined in GLOSSARY.md, link to it on first use in a doc rather than redefining it.

Writing style¶

Prescriptive voice for non-FEATURES docs. Describe how the system should work, not how it currently works or used to work. "The combat resolver returns a CombatResult containing..." — not "The combat resolver was rewritten in 2024 and now returns...".

Inline status for FEATURES. When a feature doc covers behaviour that isn't fully shipped, mark each section, table row, or bullet with the appropriate status emoji. Do not bury status in a "current state" footer.

No historical narrative. Avoid:

"Previously, X..."
"We removed Y..."
"This used to be Z, but now..."
"Legacy behaviour..."
"Deprecated in favour of..."

If something has been removed or replaced, the doc simply describes the target state without referencing the prior one. ADRs (ADR/) are the place for "we decided X over Y" reasoning, not feature or system docs.

Concrete, specific, terse. Tables and bullets where they fit. Numbers where they're known. Code paths where they apply. Avoid marketing language.

No redundant prose. If a table conveys it, skip the paragraph. If GLOSSARY.md defines it, link rather than redefine.

Reviewing a doc PR¶

Use this checklist before approving:

Contributor onboarding¶

A short path for someone who has just cloned the repo:

Read the root README.md to understand the layout.
Skim GLOSSARY.md so the vocabulary clicks.
Read this file (CONTRIBUTING.md) end-to-end.
Read the README.md index of whichever section you're touching.
Open one or two existing docs in the same section to match tone and structure.
Make your edit; run through the review checklist above before opening a PR.

If your change crosses sections (for example, a new feature spec plus a system doc plus a data-model entry), open a single PR that updates all of them together — readers should not encounter half-applied changes.

For substantive architectural choices, open an ADR under ADR/ in the same PR. See ADR/README.md for when an ADR is warranted and the template to follow.