Ilia Denisov
64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
# Galaxy Game — Project Conventions
|
|
|
|
This repository hosts the Galaxy Game project.
|
|
|
|
## Sources of truth
|
|
|
|
- `ARCHITECTURE.md` — global architecture, project-wide rules
|
|
and links to the implemented services.
|
|
- `galaxy/<service>/README.md` - service conventions and agreements
|
|
for the implemented or planned to be implemented service.
|
|
|
|
## Planning of service implementation and Implementing Plan
|
|
|
|
- `galaxy/<service>/PLAN.md` — staged implementation plan for the service.
|
|
May be already complete and resides for historical reasons.
|
|
- `galaxy/<service>/docs/` — per-stage decision records
|
|
(one file per decision, re-organized after full implementation
|
|
of `PLAN.md`).
|
|
|
|
## Decision records when implementing stages from PLAN.md
|
|
|
|
- Stage-related discussion and decisions do NOT live in `README.md` or
|
|
`ARCHITECTURE.md`. Those files describe the current state, not the history.
|
|
- Each non-trivial decision gets its own `.md` under the module's `docs/`,
|
|
referenced from the relevant `README.md`.
|
|
- Any agreement reached during interactive planning that is not obvious from
|
|
the code must be captured — either as a decision record or as an entry in
|
|
the module's README.
|
|
|
|
## Scope of PLAN.md changes
|
|
|
|
The existing codebase of `galaxy/<service>` may be modified or extended when a
|
|
plan stage requires it. All such changes must be covered by new or updated tests
|
|
and reflected in documentation when they affect documented behavior.
|
|
|
|
## Documentation discipline
|
|
|
|
- Code and docs are kept in sync. If an implementation changes behavior
|
|
described in a `.md` or `.yaml` file, update that file in the same patch.
|
|
- If existing docs are incomplete or wrong for behavior you are already
|
|
touching, fix them in the same patch.
|
|
- Do not silently remove commitments from `galaxy/<service>/README.md`
|
|
or `galaxy/<service>/docs/*.md`. When a rule changes, either update it
|
|
in place with the new agreement, or move the section to a more appropriate
|
|
doc with a reference kept.
|
|
- Cross-module impact: if a new agreement requires changes in
|
|
already-implemented modules, make those changes — code, tests, docs — in
|
|
the same patch, and record the new rule in `ARCHITECTURE.md`.
|
|
|
|
## Dependencies
|
|
|
|
- Before adding a new module, check its upstream repository for the latest
|
|
stable version and use that.
|
|
- When a well-maintained library clearly outperforms stdlib for a concrete
|
|
need, do not adopt it silently — propose a short list of 1+ candidates for
|
|
the user to pick. Default remains stdlib.
|
|
|
|
## Language
|
|
|
|
- All code, comments, identifiers, commit messages, docs, and filenames are
|
|
written in English.
|
|
- User-facing chat responses follow the Russian-translation rule from the
|
|
user-level `CLAUDE.md`.
|