Refresh repository documentation instructions - #47
Open
lodyai[bot] wants to merge 1 commit into
Open
Conversation
Import the latest Rust agent instructions and align the documentation index with the current style-guide structure. Add the canonical repository layout reference so contributors have one source of truth for path ownership and fixture locations. Run the Markdown formatter across the documentation set so existing prose continues to satisfy the repository documentation gates.
Contributor
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
Documentation alignment with Rust template standardsThis pull request refreshes the repository's documentation to align with the latest Rust template conventions and standards. It is a documentation-only change with no modifications to Rust behaviour or code logic. New documentationdocs/repository-layout.md has been added as the canonical reference for repository structure. This document provides:
Documentation reorganisationdocs/contents.md has been restructured from a flat link-heavy list into a categorised index with section headings: User and contributor guides, Architecture and design, Decision records, Reference material, and Execution plans. The Execution plans section now comprehensively lists roadmap steps through the 3.x series, expanding substantially from the prior version. AGENTS.md updatesAGENTS.md guidance has been refreshed to follow current Rust template conventions:
Formatting improvementsMarkdown formatting has been normalised across documentation, including:
ValidationAll repository checks passed:
WalkthroughUpdates ChangesDocumentation policy refresh and repository layout guide
Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 19 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (19 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
Reviewer's GuideRefreshes repository documentation by updating AGENTS guidance, restructuring the docs index around a canonical taxonomy, and adding a new repository layout guide, along with formatter-only touch-ups to existing execplans and an ADR. Flow diagram for updated documentation placement guidanceflowchart TD
Start[Agent has information to document]
Q1{Is this about
user-visible behaviour
or UI?}
Q2{Is this about
internal interfaces or
component architecture?}
Q3{Is this a
long-lived design or
architecture decision?}
Q4{Is this about
repository structure or
file locations?}
Start --> Q1
Q1 -->|Yes| UsersGuide[docs/users-guide.md]
Q1 -->|No| Q2
Q2 -->|Yes| DevGuide[docs/developers-guide.md]
Q2 -->|No| Q3
Q3 -->|Yes| ADR[docs/adr-NNN-short-description.md]
Q3 -->|No| Q4
Q4 -->|Yes| RepoLayout[docs/repository-layout.md]
Q4 -->|No| StyleGuide[docs/documentation-style-guide.md]
UsersGuide --> End[Document added]
DevGuide --> End
ADR --> End
RepoLayout --> End
StyleGuide --> End
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
pandalump
marked this pull request as ready for review
June 23, 2026 19:51
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@AGENTS.md`:
- Around line 321-331: The documentation checklist in the Project documentation
section is incomplete and omits `docs/repository-layout.md`, which serves as the
canonical home for repository structure and path ownership. Add
`docs/repository-layout.md` to the checklist alongside the existing
documentation guidelines for `docs/users-guide.md` and
`docs/developers-guide.md`, ensuring that any changes to repository structure or
path ownership are properly documented in the appropriate location.
- Around line 111-119: The Abstraction / port / helper policy section currently
directs recording decisions to the developers-guide, but substantive
architectural decisions should be captured in relevant design documents and ADRs
instead. Update step 3 (Record the decision...) to clarify that developers
should record design decisions in the appropriate design document or ADR, not in
developers-guide.md which is for ongoing conventions. Ensure the guidance
reflects that design documents are the primary location for substantive
decisions with ADR references when the choice affects the architecture.
In `@docs/contents.md`:
- Around line 48-67: The reference material section in the contents.md file uses
US English spellings that conflict with the repository style guide. Replace the
US spelling variants with en-GB equivalents: change "anti-patterns" to
"antipatterns", "parametrization" to "parameterisation", "localizable" to
"localisable", and "localization" to "localisation" in the blurbs for the
rust-doctest-dry-guide.md, rust-testing-with-rstest-fixtures.md, and
localizable-rust-libraries-with-fluent.md entries.
In `@docs/repository-layout.md`:
- Around line 23-28: The repository layout tree in the docs incorrectly lists
`theorem_file_macro_bdd` as a directory with a trailing slash, but it should be
represented as a file named `theorem_file_macro_bdd.rs` to align with how it is
referenced elsewhere in the documentation. Update the tree structure in the
tests directory section to show `theorem_file_macro_bdd.rs` as a file instead of
a directory, and apply the same correction at lines 63-64 where this path is
also mentioned.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 1dd92cca-1b84-4f44-ace6-9d2635432117
📒 Files selected for processing (8)
AGENTS.mddocs/adr-004-action-signature-specification.mddocs/contents.mddocs/execplans/1-2-1-validate-required-fields-and-non-empty-constraints.mddocs/execplans/2-3-1-argument-decoding-for-plain-yaml-strings.mddocs/execplans/2-3-2-optional-literal-text-wrapper.mddocs/execplans/3-2-2-gate-generated-kani-harnesses.mddocs/repository-layout.md
Comment on lines
+111
to
+119
| - **Abstraction / port / helper policy:** Before implementing an abstraction, | ||
| port, or extracted helper, the agent must: | ||
| 1. Sweep the repository to confirm there is no existing equivalent helper, | ||
| port, or abstraction. | ||
| 2. Document the new abstraction's intended scope and re-use policy | ||
| (ownership boundaries, permitted call-sites, and composition rules). | ||
| 3. Record the decision in the appropriate architecture, design, or | ||
| developers-guide document using `docs/contents.md` as the index to select | ||
| the correct location. |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Route abstraction decisions into design docs and ADRs.
Line 111-119 sends new abstraction/port/helper decisions to docs/developers-guide.md, but that guide is for ongoing conventions, not architectural decisions. Keep substantive cases in the relevant design document, then capture an ADR when the choice affects the architecture. As per coding guidelines, record design decisions in the design document and reference the ADR from there.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@AGENTS.md` around lines 111 - 119, The Abstraction / port / helper policy
section currently directs recording decisions to the developers-guide, but
substantive architectural decisions should be captured in relevant design
documents and ADRs instead. Update step 3 (Record the decision...) to clarify
that developers should record design decisions in the appropriate design
document or ADR, not in developers-guide.md which is for ongoing conventions.
Ensure the guidance reflects that design documents are the primary location for
substantive decisions with ADR references when the choice affects the
architecture.
Source: Coding guidelines
Comment on lines
+321
to
+331
| ## Project documentation | ||
|
|
||
| Record design decisions in the design document. Where a decision is | ||
| substantive, record it in an ADR document following the documentation style | ||
| guide, then reference that ADR from the design document. | ||
|
|
||
| Update `docs/users-guide.md` for any change to application behaviour or user | ||
| interface that a user should know about. Document internally facing interfaces | ||
| or practices in the relevant component architecture document. Document | ||
| internally facing conventions or practices in `docs/developers-guide.md`. | ||
|
|
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Add docs/repository-layout.md to the documentation checklist.
Line 321-331 covers the users and developers guides, but it omits docs/repository-layout.md, which is now the canonical home for repository structure and path ownership. Add it here so structural changes are updated in the right document. As per coding guidelines, docs/repository-layout.md is the repository-layout source of truth.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@AGENTS.md` around lines 321 - 331, The documentation checklist in the Project
documentation section is incomplete and omits `docs/repository-layout.md`, which
serves as the canonical home for repository structure and path ownership. Add
`docs/repository-layout.md` to the checklist alongside the existing
documentation guidelines for `docs/users-guide.md` and
`docs/developers-guide.md`, ensuring that any changes to repository structure or
path ownership are properly documented in the appropriate location.
Source: Coding guidelines
Comment on lines
+48
to
+67
| ## Reference material | ||
|
|
||
| - [Navigating code complexity: a guide for implementers and maintainers](complexity-antipatterns-and-refactoring-strategies.md) | ||
| - Practical guide to complexity metrics, anti-patterns, and refactoring | ||
| strategies for long-lived codebases. | ||
| - [Developer's guide](developers-guide.md) - Maintainer-oriented manual | ||
| covering the build system, internal architecture, contributor workflows, and | ||
| extension points. | ||
| - [Documentation style guide](documentation-style-guide.md) - Authoring rules | ||
| for spelling, formatting, Markdown structure, diagrams, and documentation | ||
| consistency. | ||
| - [Name mangling rules](name-mangling-rules.md) - Normative mapping rules for | ||
| theorem action names, generated Kani harness symbols, and external theorem | ||
| identifiers. | ||
| strategies for long-lived codebases. | ||
| - [Reliable testing in Rust via dependency injection](reliable-testing-in-rust-via-dependency-injection.md) | ||
| - Patterns for testable Rust design using dependency injection to avoid | ||
| global-state coupling. | ||
| - [A systematic guide to effective, ergonomic, and "don't repeat yourself" (DRY) doctests in Rust](rust-doctest-dry-guide.md) | ||
| global-state coupling. | ||
| - [A systematic guide to effective, ergonomic, and DRY doctests in Rust](rust-doctest-dry-guide.md) | ||
| - Detailed reference for writing maintainable Rust doctests with minimal | ||
| duplication. | ||
| duplication. | ||
| - [Mastering test fixtures in Rust with `rstest`](rust-testing-with-rstest-fixtures.md) | ||
| - Comprehensive reference for fixture design, parametrization, and best | ||
| practices with `rstest`. | ||
| - [Scripting standards](scripting-standards.md) - Standards for project | ||
| scripts, covering toolchain choices, structure, and operational expectations. | ||
| - [Theorem file format](theorem-file-specification.md) - Schema and behavioural | ||
| specification for `.theorem` documents and their compile-time semantics. | ||
| - [Theoremc development roadmap](roadmap.md) - Phased | ||
| implementation roadmap with traceable tasks derived from design, schema, | ||
| mangling, and ADR requirements. | ||
| - [Theoremc design specification](theoremc-design.md) - End-to-end architecture | ||
| and design rationale for theoremc, including parser, code generation, | ||
| backend, and reporting design. | ||
| - [User's guide](users-guide.md) - Guide for library consumers covering | ||
| schema types, loading API, identifier rules, and value forms. | ||
| - [Execution plans](execplans/) - Implementation plans for roadmap steps. | ||
| practices with `rstest`. | ||
| - [Scripting standards](scripting-standards.md) - Standards for project scripts, | ||
| covering toolchain choices, structure, and operational expectations. | ||
| - [Localizable Rust libraries with Fluent](localizable-rust-libraries-with-fluent.md) | ||
| - Reference material for library-safe localization patterns and Fluent | ||
| integration. | ||
|
|
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Normalise the reference blurbs to en-GB spelling.
This section mixes US spellings (anti-patterns, parametrization,
localizable, localization) into a docs index that is meant to follow the
repository style. Use antipatterns, parameterisation, localisable, and
localisation instead.
Triage: [type:spelling] [type:docstyle]
As per path instructions, use en-GB-oxendict spelling and grammar in **/*.md files.
🧰 Tools
🪛 LanguageTool
[misspelling] ~51-~51: This word is normally spelled as one.
Context: ... Practical guide to complexity metrics, anti-patterns, and refactoring strategies for lon...
(EN_COMPOUNDS_ANTI_PATTERNS)
[typographical] ~62-~62: To join two clauses or introduce examples, consider using an em dash.
Context: ...pting standards](scripting-standards.md) - Standards for project scripts, coverin...
(DASH_RULE)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/contents.md` around lines 48 - 67, The reference material section in the
contents.md file uses US English spellings that conflict with the repository
style guide. Replace the US spelling variants with en-GB equivalents: change
"anti-patterns" to "antipatterns", "parametrization" to "parameterisation",
"localizable" to "localisable", and "localization" to "localisation" in the
blurbs for the rust-doctest-dry-guide.md, rust-testing-with-rstest-fixtures.md,
and localizable-rust-libraries-with-fluent.md entries.
Source: Path instructions
Comment on lines
+23
to
+28
| ├── tests/ | ||
| │ ├── common/ | ||
| │ ├── features/ | ||
| │ ├── fixtures/ | ||
| │ ├── snapshots/ | ||
| │ └── theorem_file_macro_bdd/ |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Keep theorem_file_macro_bdd as a file path, not a directory.
The canonical layout here disagrees with the rest of the docs, which refer to
tests/theorem_file_macro_bdd.rs. Align the tree and the path-responsibility
note so contributors see one stable location.
♻️ Suggested fix
-├── tests/
-│ ├── common/
-│ ├── features/
-│ ├── fixtures/
-│ ├── snapshots/
-│ └── theorem_file_macro_bdd/
+├── tests/
+│ ├── common/
+│ ├── features/
+│ ├── fixtures/
+│ ├── snapshots/
+│ └── theorem_file_macro_bdd.rs
@@
-- `tests/theorem_file_macro_bdd/` contains support code for macro behavioural
-- tests that need fixture crates or Cargo/Kani command wrappers.
+- `tests/theorem_file_macro_bdd.rs` contains support code for macro
+ behavioural tests that need fixture crates or Cargo/Kani command wrappers.Also applies to: 63-64
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/repository-layout.md` around lines 23 - 28, The repository layout tree
in the docs incorrectly lists `theorem_file_macro_bdd` as a directory with a
trailing slash, but it should be represented as a file named
`theorem_file_macro_bdd.rs` to align with how it is referenced elsewhere in the
documentation. Update the tree structure in the tests directory section to show
`theorem_file_macro_bdd.rs` as a file instead of a directory, and apply the same
correction at lines 63-64 where this path is also mentioned.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This branch refreshes the repository's agent and documentation guidance so the
local instructions match the latest Rust template and the documentation set has
a canonical repository-layout entrypoint.
The branch imports the latest upstream
AGENTS.mdguidance, keeps thealready-current documentation style guide aligned with the template, rewrites
the contents index around the style-guide document taxonomy, and adds the
missing repository layout document. The Markdown formatter also normalized a
small set of existing documentation lines while applying the required docs
formatting gate.
Roadmap task: none.
Execplan: none.
Review walkthrough
Validation
make fmt: passed.make check-fmt: passed.make markdownlint: passed.make nixie: passed; all Mermaid diagrams validated successfully.make lint: passed.make test: passed;cargo nextestran 560 tests with 560 passed, and workspace doctests passed.Notes
copy after download, so it does not appear as a content diff in this branch.