Add developer guide; remove usage-guide docs - #49
Conversation
![terragon-labs[bot]](https://github.githubassets.com/images/gravatars/gravatar-user-420.png){kind=avatar}
• Add `docs/developers-guide.md` with detailed info on internal APIs, testing patterns, workspace helpers, and programmatic publish options. • Remove `docs/usage-guide.md`, consolidating end-user CLI reference into users-guide.md as noted. This reorganization improves documentation clarity by separating developer-focused content from user-facing guides. Co-authored-by: terragon-labs[bot] <terragon-labs[bot]@users.noreply.github.com>
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings. WalkthroughReplace the user-facing usage guide with a developer-focused guide that documents CLI invocation, testing hooks, workspace discovery helpers, and programmatic publish options for contributors (≤50 words). Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro 📒 Files selected for processing (1)
🧰 Additional context used📓 Path-based instructions (2)docs/**/*.md📄 CodeRabbit inference engine (AGENTS.md)
Files:
**/*.md📄 CodeRabbit inference engine (AGENTS.md)
Files:
⚙️ CodeRabbit configuration file
Files:
🔍 Remote MCP DeepwikiAdditional context relevant to PR #49 (add developers-guide.md; remove usage-guide.md)
Concrete reviewer checklist derived from gathered context
Sources
⏰ Context from checks skipped due to timeout of 120000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
🔇 Additional comments (1)
Comment |
Reviewer's GuideAdds a new developer-focused documentation guide for internal APIs and workflows, and removes the deprecated usage guide in favor of the consolidated users guide, with no code changes. Flow diagram for updated documentation structureflowchart TD
A["Repository_docs_directory"] --> B["users_guide_md
(user oriented CLI and config guide)"]
A --> C["developers_guide_md
(contributor oriented internal APIs and workflows)"]
B --> D["End_users
(run CLI, configure lading_toml)"]
C --> E["Contributors
(development invocation, testing hooks, workspace helpers, publish options)"]
F["usage_guide_md
(removed, content migrated)"] -.removed.-> B
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![codescene-delta-analysis[bot]](https://avatars.githubusercontent.com/in/53921?s=60&v=4){kind=small}
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 2 issues, and left some high level feedback:
- Consider turning references like
docs/users-guide.mdandcmd-mox-usage-guide.mdinto explicit Markdown links so contributors can navigate between guides directly from the rendered docs. - In the
PublishOptionssection, it might help to briefly note the default values forpreserve_symlinksandcleanupso readers understand how the examples differ from the standard behavior.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- Consider turning references like `docs/users-guide.md` and `cmd-mox-usage-guide.md` into explicit Markdown links so contributors can navigate between guides directly from the rendered docs.
- In the `PublishOptions` section, it might help to briefly note the default values for `preserve_symlinks` and `cleanup` so readers understand how the examples differ from the standard behavior.
## Individual Comments
### Comment 1
<location> `docs/developers-guide.md:9` </location>
<code_context>
+
+## Development invocation
+
+The console script resolves to `lading.cli.main`. During development you can
+invoke the implementation module directly:
+
</code_context>
<issue_to_address>
**issue (review_instructions):** The sentence uses the second-person pronoun "you", which the guidelines prohibit.
Rephrase to avoid second-person narration, for example "During development, the implementation module can be invoked directly".
<details>
<summary>Review instructions:</summary>
**Path patterns:** `**/*.md`
**Instructions:**
Avoid 2nd person or 1st person pronouns ("I", "you", "we").
</details>
</issue_to_address>
### Comment 2
<location> `docs/developers-guide.md:21` </location>
<code_context>
+Behavioural tests invoke the CLI as an external process and spy on the `python`
+executable with [`cmd-mox`](./cmd-mox-usage-guide.md). Setting
+`LADING_USE_CMD_MOX_STUB` to a truthy value such as `1` or `true` forces
+publish pre-flight checks to proxy through the cmd-mox IPC server so that the
+suite can assert on `cargo::<subcommand>` invocations without launching real
+tools. This pattern keeps the tests faithful to real user interactions while
</code_context>
<issue_to_address>
**issue (review_instructions):** "IPC" is introduced without expanding the acronym on first use.
Please expand IPC on first mention, for example "inter-process communication (IPC) server".
<details>
<summary>Review instructions:</summary>
**Path patterns:** `**/*.md`
**Instructions:**
Define uncommon acronyms on first use.
</details>
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
- Updated link to user guide with relative path and markdown format. - Reworded sentences for better readability and correctness. - Expanded IPC abbreviation for clarity. - Clarified defaults and options in `PublishOptions` usage section. - General cleanup and formatting improvements in documentation. Co-authored-by: terragon-labs[bot] <terragon-labs[bot]@users.noreply.github.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (2)
docs/developers-guide.mddocs/usage-guide.md
💤 Files with no reviewable changes (1)
- docs/usage-guide.md
🧰 Additional context used
📓 Path-based instructions (2)
docs/**/*.md
📄 CodeRabbit inference engine (AGENTS.md)
docs/**/*.md: Use the markdown files within thedocs/directory as a knowledge base and source of truth for project requirements, dependency choices, and architectural decisions.
Proactively update relevant files in thedocs/directory when new decisions are made, requirements change, libraries are added/removed, or architectural patterns evolve to keep documentation accurate and current.
docs/**/*.md: Use British English based on the Oxford English Dictionary (en-GB-oxendict) with suffixes: -ize in words like 'realize' and 'organization', -lyse in words like 'analyse' and 'paralyse', -our in words like 'colour' and 'behaviour', -re in words like 'centre' and 'calibre', double 'l' in words like 'cancelled' and 'counsellor', maintain 'e' in words like 'likeable', -ogue in words like 'catalogue'
Use the Oxford comma in documentation: 'ships, planes, and hovercraft' where it aids comprehension
Treat company names as collective nouns in documentation, for example 'Lille Industries are expanding'
Write headings in sentence case
Use Markdown headings (#, ##, ###, and so on) in order without skipping levels
Follow markdownlint recommendations for Markdown formatting
Always provide a language identifier for fenced code blocks; use 'plaintext' for non-code text
Use '-' as the first level bullet and renumber lists when items change in Markdown
Prefer inline links using text or angle brackets around the URL in Markdown
Ensure blank lines before and after bulleted lists and fenced blocks in Markdown
Ensure tables have a delimiter line below the header row in Markdown
Expand any uncommon acronym on first use, for example, Continuous Integration (CI)
Wrap paragraphs at 80 columns in documentation
Wrap code at 120 columns in documentation
Do not wrap tables in documentation
Use footnotes referenced with [^label] in Markdown documentation
Include Mermaid diagrams in documentation where they add clarity
When embedding figures in documentation, use 
**/*.md: For Markdown files (.md only), ensure changes pass lint checks viamake markdownlint.
For Markdown files (.md only), ensure Mermaid diagrams pass validation using nixie viamake nixie.
Files:
docs/developers-guide.md
⚙️ CodeRabbit configuration file
**/*.md: * Avoid 2nd person or 1st person pronouns ("I", "you", "we")
- Use en-GB-oxendict (-ize / -yse / -our) spelling and grammar
- Headings must not be wrapped.
- Documents must start with a level 1 heading
- Headings must correctly increase or decrease by no more than one level at a time
- Use GitHub-flavoured Markdown style for footnotes and endnotes.
- Numbered footnotes must be numbered by order of appearance in the document.
Files:
docs/developers-guide.md
🪛 LanguageTool
docs/developers-guide.md
[uncategorized] ~9-~9: A comma is probably missing here.
Context: ...t resolves to lading.cli.main. During development you can invoke the implementation modul...
(MISSING_COMMA_AFTER_INTRODUCTORY_PHRASE)
[uncategorized] ~20-~20: Possible missing preposition found.
Context: ...uthy value such as 1 or true forces publish pre-flight checks to proxy through the ...
(AI_HYDRA_LEO_MISSING_TO)
[style] ~47-~47: Would you like to use the Oxford spelling “normalizes”? The spelling ‘normalises’ is also correct.
Context: ...data["workspace_root"]) ``` The helper normalises the workspace path, invokes `cargo meta...
(OXFORD_SPELLING_Z_NOT_S)
[uncategorized] ~50-~50: Use a comma before ‘so’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...etadataError` with a descriptive message so callers can present actionable feedback...
(COMMA_COMPOUND_SENTENCE_2)
[style] ~75-~75: Would you like to use the Oxford spelling “customize”? The spelling ‘customise’ is also correct.
Context: ...orkspaceprogrammatically, callers can customise behaviour viaPublishOptions: - Pub...
(OXFORD_SPELLING_Z_NOT_S)
🔍 Remote MCP
The repository isn't indexed in Deepwiki yet. Let me try a web search to verify the technical details mentioned in the PR and gather relevant context about the project.Based on the search results, I can see that the web searches returned information about Elixir's Mox (a mocking library) and general Rust workspace/Cargo knowledge, but not specific information about the "lading" project itself. The searches indicate the project isn't readily discoverable via web or Deepwiki. Let me provide a summary of what I can verify from the PR context and note what would need verification:
Summary of PR Context Review
Key Information Found
Rust Workspace & Publishing Context:
The cargo_metadata crate provides a Rust API for reading metadata, which aligns with the PR's mention of load_cargo_metadata. The cargo metadata command provides information about workspace members and resolved dependencies in JSON format, useful for developers who need to programmatically access metadata about their Rust projects. This validates the technical relevance of documenting workspace discovery helpers.
Rust 1.90 brings support for a new command, cargo publish --workspace, that will automatically publish all of the crates in a workspace in the proper order, which provides context for the programmatic publish options mentioned in the developer guide.
Unverified Claims Requiring Attention
The following technical details from the PR cannot be verified via available resources:
-
cmd-mox testing framework - Web searches returned results for Elixir's "Mox" mocking library, not a Rust tool called "cmd-mox". This tool needs verification that it exists and is actually used in the lading project.
-
LADING_USE_CMD_MOX_STUB environment variable - No results found. Requires verification this is an actual environment variable used in the project.
-
Internal API functions - Functions like
load_cargo_metadata,load_workspace,WorkspaceGraph, andPublishOptionsare claimed to be internal APIs but cannot be verified without access to the actual codebase. -
Documentation migration - The claim that usage guide content was migrated to
docs/users-guide.mdcannot be verified without repository access.
Recommendations for Review
Critical verifications needed:
- Confirm that
cmd-moxis the correct tool name (not a typo or misremembering of another testing framework) - Verify all internal API names are accurate and currently match the codebase
- Confirm that
docs/users-guide.mdexists and contains the migrated content fromdocs/usage-guide.md - Check that documentation examples (e.g.,
uv run python -m lading.cli --help) reflect the actual current CLI invocation method
Review effort: The AI summary suggests "Low" estimated code review effort due to documentation-only changes, which is appropriate. However, technical accuracy verification requires examining the actual codebase since the specific APIs and tools mentioned are not discoverable through public documentation.
⏰ Context from checks skipped due to timeout of 120000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Sourcery review
🔇 Additional comments (2)
docs/developers-guide.md (2)
18-19: Wrap lines and verify referenced file.Line 18 exceeds 80 columns (81 characters). Additionally, confirm that
./cmd-mox-usage-guide.mdexists in the repository before merging.
5-5: Verify that docs/users-guide.md exists.Line 5 references
docs/users-guide.mdas the location for end-user CLI reference and configuration guide. Confirm this file exists in the repository and contains migrated user-facing documentation from the removeddocs/usage-guide.md.
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (5)
docs/developers-guide.md (5)
3-5: Reflow paragraph to respect 80-column wrap limit.Lines 3–4 exceed the 80-column boundary (82 and 81 characters respectively). Restructure the introduction as:
This guide documents internal APIs, testing patterns, and development workflows for contributors to lading. For the end-user CLI reference and lading.toml configuration, see the user guide.Update the link format to match.
Proposed fix
-This guide documents internal APIs, testing patterns, and development workflows -for contributors to `lading`. For the end-user CLI reference and `lading.toml` -configuration, see the [user guide](./users-guide.md). +This guide documents internal APIs, testing patterns, and development +workflows for contributors to `lading`. For the end-user CLI reference and +`lading.toml` configuration, see the [user guide](./users-guide.md).
48-48: Use Oxford English spelling for -ize suffix.Replace "normalises" with "normalizes" per the en-GB-oxendict spelling guideline.
Proposed fix
-The helper normalises the workspace path, invokes +The helper normalizes the workspace path, invokes
50-51: Add comma before coordinating conjunction in compound sentence.Insert a comma before "so" to clarify the compound sentence joining two independent clauses:
Proposed fix
-Any execution errors or invalid output raise `CargoMetadataError` with a -descriptive message so callers can present actionable feedback to users. +Any execution errors or invalid output raise `CargoMetadataError` with a +descriptive message, so callers can present actionable feedback to users.
20-22: Fix passive construction grammar.Line 20 uses an incomplete passive construction. Change "forces publish pre-flight checks to proxy through the cmd-mox inter-process communication (IPC) server" to "forces publish pre-flight checks to be proxied through the cmd-mox inter-process communication (IPC) server" so the sentence reads naturally.
Proposed fix
-`LADING_USE_CMD_MOX_STUB` to a truthy value such as `1` or `true` forces -publish pre-flight checks to proxy through the cmd-mox inter-process -communication (IPC) server so that the +`LADING_USE_CMD_MOX_STUB` to a truthy value such as `1` or `true` forces +publish pre-flight checks to be proxied through the cmd-mox inter-process +communication (IPC) server so that the
76-76: Use Oxford English spelling for -ize suffix.Replace "customise" with "customize" per the en-GB-oxendict spelling guideline.
Proposed fix
-When invoking `lading.commands.publish.prepare_workspace` programmatically, -callers can customise behaviour via `PublishOptions`. The defaults are +When invoking `lading.commands.publish.prepare_workspace` programmatically, +callers can customize behaviour via `PublishOptions`. The defaults are
📜 Review details
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (1)
docs/developers-guide.md
🧰 Additional context used
📓 Path-based instructions (2)
docs/**/*.md
📄 CodeRabbit inference engine (AGENTS.md)
docs/**/*.md: Use the markdown files within thedocs/directory as a knowledge base and source of truth for project requirements, dependency choices, and architectural decisions.
Proactively update relevant files in thedocs/directory when new decisions are made, requirements change, libraries are added/removed, or architectural patterns evolve to keep documentation accurate and current.
docs/**/*.md: Use British English based on the Oxford English Dictionary (en-GB-oxendict) with suffixes: -ize in words like 'realize' and 'organization', -lyse in words like 'analyse' and 'paralyse', -our in words like 'colour' and 'behaviour', -re in words like 'centre' and 'calibre', double 'l' in words like 'cancelled' and 'counsellor', maintain 'e' in words like 'likeable', -ogue in words like 'catalogue'
Use the Oxford comma in documentation: 'ships, planes, and hovercraft' where it aids comprehension
Treat company names as collective nouns in documentation, for example 'Lille Industries are expanding'
Write headings in sentence case
Use Markdown headings (#, ##, ###, and so on) in order without skipping levels
Follow markdownlint recommendations for Markdown formatting
Always provide a language identifier for fenced code blocks; use 'plaintext' for non-code text
Use '-' as the first level bullet and renumber lists when items change in Markdown
Prefer inline links using text or angle brackets around the URL in Markdown
Ensure blank lines before and after bulleted lists and fenced blocks in Markdown
Ensure tables have a delimiter line below the header row in Markdown
Expand any uncommon acronym on first use, for example, Continuous Integration (CI)
Wrap paragraphs at 80 columns in documentation
Wrap code at 120 columns in documentation
Do not wrap tables in documentation
Use footnotes referenced with [^label] in Markdown documentation
Include Mermaid diagrams in documentation where they add clarity
When embedding figures in documentation, use 
**/*.md: For Markdown files (.md only), ensure changes pass lint checks viamake markdownlint.
For Markdown files (.md only), ensure Mermaid diagrams pass validation using nixie viamake nixie.
Files:
docs/developers-guide.md
⚙️ CodeRabbit configuration file
**/*.md: * Avoid 2nd person or 1st person pronouns ("I", "you", "we")
- Use en-GB-oxendict (-ize / -yse / -our) spelling and grammar
- Headings must not be wrapped.
- Documents must start with a level 1 heading
- Headings must correctly increase or decrease by no more than one level at a time
- Use GitHub-flavoured Markdown style for footnotes and endnotes.
- Numbered footnotes must be numbered by order of appearance in the document.
Files:
docs/developers-guide.md
🪛 LanguageTool
docs/developers-guide.md
[uncategorized] ~20-~20: Possible missing preposition found.
Context: ...uthy value such as 1 or true forces publish pre-flight checks to proxy through the ...
(AI_HYDRA_LEO_MISSING_TO)
[style] ~48-~48: Would you like to use the Oxford spelling “normalizes”? The spelling ‘normalises’ is also correct.
Context: ...data["workspace_root"]) ``` The helper normalises the workspace path, invokes `cargo meta...
(OXFORD_SPELLING_Z_NOT_S)
[uncategorized] ~51-~51: Use a comma before ‘so’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...etadataError` with a descriptive message so callers can present actionable feedback...
(COMMA_COMPOUND_SENTENCE_2)
[style] ~76-~76: Would you like to use the Oxford spelling “customize”? The spelling ‘customise’ is also correct.
Context: ...orkspaceprogrammatically, callers can customise behaviour viaPublishOptions`. The def...
(OXFORD_SPELLING_Z_NOT_S)
🔍 Remote MCP Deepwiki
Summary of additional repository context relevant to this PR review
-
Repository docs/wiki exists and documents the exact internals referenced by the PR: workspace discovery, bump/publish command behavior, testing hooks, and developer workflows. (Pages present: Overview, Development Guide, Command Reference, bump, publish, Preflight Checks, Publication Planning, Workspace Staging, Configuration Guide, Development Guide, etc.),
-
cmd-mox testing hook and env var are present and documented:
- The test harness supports an IPC-based subprocess stub called cmd-mox; production code switches to the stub when LADING_USE_CMD_MOX_STUB is set; CMOX_IPC_SOCKET must be provided for IPC. (Used by preflight/cargo invocations and workspace metadata invocation.)
-
Internal API names referenced in the PR exist and match the docs:
- load_cargo_metadata / load_workspace / WorkspaceGraph model / CargoMetadataError are documented in workspace discovery and models pages.
- PublishOptions and its fields (preserve_symlinks, cleanup, build_directory, command_runner, allow_dirty) are documented in the publish command page.
- BumpOptions, bump behavior, and documentation-fence rewriting logic are documented in the bump command page.
-
CLI invocation examples cited in the PR (uv run python -m lading.cli --help or uv run lading --help) match the documented CLI usage and entry point (console script lading → lading.cli:main).
-
docs/usage-guide.md content (user-facing) is present in the repo's docs pages; the wiki indicates the same content and that it is used by CLI docs/quickstart — ensure the PR migration moved/renamed usage-guide → users-guide as claimed. The wiki references docs/usage-guide.md in multiple places.
Concrete reviewer action items (based on above findings)
- Verify the PR actually adds docs/developers-guide.md matching the documented internal APIs (load_cargo_metadata, load_workspace, WorkspaceGraph, PublishOptions, cmd-mox usage) — names and behaviors in the new doc should match code and the documentation already present in the repository.
- Confirm LADING_USE_CMD_MOX_STUB and CMOX_IPC_SOCKET are documented consistently (exists in preflight/workspace metadata docs) and that examples in developers-guide.md match the repository's cmd-mox integration.
- Confirm user-facing content removed from docs/usage-guide.md is present in docs/users-guide.md (PR claims migration); the repository wiki shows usage-guide content — ensure no user docs were lost.
Tools/sources used
- Deepwiki_read_wiki_structure (leynos/lading) — confirmed available wiki pages.
- Deepwiki_read_wiki_contents (leynos/lading) — retrieved page contents documenting the exact APIs, env vars, CLI, testing hooks, and options described above.
⏰ Context from checks skipped due to timeout of 120000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Sourcery review
🔇 Additional comments (1)
docs/developers-guide.md (1)
19-19: Cross-reference to./cmd-mox-usage-guide.mdis valid; the file exists in the repository.
Extended the programmatic publish options section with detailed explanations of PublishOptions parameters including allow_dirty, live, build_directory, preserve_symlinks, and cleanup. Added security notes and usage examples for better clarity. Co-authored-by: terragon-labs[bot] <terragon-labs[bot]@users.noreply.github.com>
1 participant
Summary
docs/users-guide.mdand reduce duplication.Changes
Added
docs/developers-guide.md: New comprehensive guide covering:uv run python -m lading.cli --help)cmd-mox, andLADING_USE_CMD_MOX_STUBenvironment variable guidanceload_cargo_metadataandload_workspace, plus a description of theWorkspaceGraphmodelPublishOptions(e.g., preserving symlinks, automatic cleanup)Removed
docs/usage-guide.md: Removed user-oriented usage guide. Content has been migrated todocs/users-guide.md.Rationale
How to review
docs/developers-guide.mdto ensure its sections align with current codebase and tooling.docs/users-guide.md.Impact
🌿 Generated by Terry
ℹ️ Tag @terragon-labs to ask questions and address PR feedback
📎 Task: https://www.terragonlabs.com/task/9634e82a-6552-457f-ab0f-8899375b398d
Summary by Sourcery
Add a dedicated developer guide documenting Lading’s internal APIs and workflows while removing the deprecated standalone usage guide.
Documentation: