Skip to content

docs: add CONVENTIONS.md structure & taste guide#323

Draft
Troublor wants to merge 1 commit into
mainfrom
troublor/docs/conventions-guide
Draft

docs: add CONVENTIONS.md structure & taste guide#323
Troublor wants to merge 1 commit into
mainfrom
troublor/docs/conventions-guide

Conversation

@Troublor

Copy link
Copy Markdown
Collaborator

Summary

  • Add CONVENTIONS.md at the repo root — a cross-cutting code-organization & taste guide for mega-evm. It covers: a module-by-execution-layer map ("adding X → it belongs in module Y"), file-role conventions (mod.rs as a wiring façade, the factory.rs/result.rs/error.rs/helpers.rs role names), composition idioms (registry-of-trackers, macro-wrapped instruction table, trait factories, spec-gating), when to add a new file vs. extend one, readability/maintainability mechanisms, and a smell list.
  • Add a "How to use this doc" split between two review modes — PR gate (don't introduce new violations) and repo-level audit (treat conventions as detection rules and sweep the tree) — plus a repo-wide scan plan turning each convention into a query.
  • Add §8 "Known deviations & improvement backlog" — a labeled registry of current tech debt (the StateChangeSource::Transaction(0) placeholder, dead commented-out increment_balances code, duplicated data_size/kv_update tracker bodies, sandbox/ missing its nested AGENTS.md) so repo-level reviews mine documented deviations instead of mistaking them for endorsed convention.
  • Wire it in: pointers from AGENTS.md (Core Source Layout) and REVIEW.md (Design and architecture), and add CONVENTIONS.md to the doc-audit.yml / claude.yml agent-file scope so the freshness/correctness audits keep it current.

Test plan

  • Docs + CI-prompt-scope only; no code or behavior change (spec:unchanged, api:unchanged).
  • markdownlint-cli2 passes with 0 errors; prettier --check 'docs/**/*.md' '*.md' is clean.
  • Every code path cited in the doc was verified to exist on main at authoring time.

Cross-cutting code-organization reference for mega-evm: module-by-layer
map, file-role conventions, composition idioms (registry-of-trackers,
macro-wrapped instruction table, spec-gating), when to add a new file vs.
extend one, readability mechanisms, and a smell list. Includes a
'How to use' split between PR-gate and repo-level-audit modes, a repo-wide
scan plan, and a 'Known deviations & improvement backlog' (section 8) so
repo-level reviews can mine documented tech debt rather than treat it as
convention.

Wire it in: pointers from AGENTS.md (Core Source Layout) and REVIEW.md
(Design and architecture), and add it to the doc-audit/doc-impact agent-file
scope so freshness/correctness checks keep it current.
@Troublor Troublor added spec:unchanged No change to any `mega-evm`'s behavior api:unchanged No change to the public interface or API comp:doc Changes in the documentation labels Jun 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

api:unchanged No change to the public interface or API comp:doc Changes in the documentation spec:unchanged No change to any `mega-evm`'s behavior

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant