Document Lading release configuration in the developer guide

[coderabbitai]

Summary

Document the repository's Lading release configuration in the developer guide.

Rationale

Pull request #568 adds lading.toml with a unit-test preflight rule and documentation-bump globs. Developers need documentation that explains this release configuration and its maintenance requirements.

Affected area

• lading.toml
• docs/developers-guide.md

Required changes

Add a developer-guide section that:

• Identifies lading.toml as the repository configuration for Lading.
• Explains that the preflight configuration runs unit tests.
• Explains that the documentation-bump configuration targets README.md and docs/users-guide.md.
• States when developers must update the configuration as release validation or documentation paths change.

Acceptance criteria

• docs/developers-guide.md contains a Lading configuration section.
• The section links to https://github.com/leynos/lading.
• The section describes the unit-test preflight rule.
• The section identifies the documentation-bump globs and their target files.
• The documentation is consistent with lading.toml.

Backlinks

• Pull request: Split CHANGELOG into v0.1.0-beta1 and v0.1.0-beta2 releases #568
• Request comment: Split CHANGELOG into v0.1.0-beta1 and v0.1.0-beta2 releases #568 (comment)
• Requested by: @leynos

[coderabbitai]

🔗 Related PRs

leynos/df12-www#4 - Add AGENTS guide for OpenTofu deploy [closed]
leynos/skyjoust#5 - Add documentation index and layout guide [closed]
#446 - Correct users-guide JSON/config claims and document glob [merged]
#469 - Add package-boundary smoke test (#411) [merged]
#568 - Split CHANGELOG into v0.1.0-beta1 and v0.1.0-beta2 releases [open]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[leynos]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

Add one new sentence-case ## Lading configuration section to docs/developers-guide.md that mirrors the existing tool-configuration section style.

Cover all acceptance criteria: link to Lading, describe the unit-test preflight rule, name the documentation-bump globs and their target files, and state the maintenance triggers.

Sync docs/contents.md with the new topic, per the style-guide index rule.

Reconcile the prose against lading.toml to guarantee consistency.

Design Choices

Design Choice 1: `lading.toml` is absent from the checkout: guarantee documentation consistency

Options Considered:

1. Document the configuration using the exact field values named in the ticket (unit-test preflight; documentation-bump globs targeting README.md and docs/users-guide.md), and instruct the implementing agent to reconcile the prose against lading.toml once the file is present.
2. Block the documentation change until lading.toml is merged and readable in the working tree.

Chosen Option: 1

Rationale: Write the section from the ticket-specified values and require a final read-back against lading.toml. The ticket already states the concrete configuration, and the file will exist on the target branch.

Design Choice 2: Placement of the new section within `docs/developers-guide.md`

Options Considered:

1. Place the section immediately after "Release help tooling", grouping it with release-oriented tooling.
2. Place the section near "Formal-verification tooling" / "Mutation-testing workflow contract tests", grouping it with other tool-configuration topics.

Chosen Option: 1

Rationale: Lading is a release-management tool. Place it after "Release help tooling" to keep release-related tooling adjacent.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Document the Lading release configuration

Add the new developer-guide section and keep the documentation index in step. Group these tasks together because they form one cohesive documentation change and must land together to satisfy the style-guide index-sync rule.

Task 1: Add the "Lading configuration" section to the developer guide

Add a new ##-level section that explains lading.toml and its maintenance requirements.

• Insert a new ## Lading configuration section in docs/developers-guide.md, immediately after the "Release help tooling" section.
• Identify lading.toml at the repository root as the configuration for Lading. Link to https://github.com/leynos/lading with an inline Markdown link on the tool name.
• State that Lading is a configuration-driven release tool for Rust workspaces, so the reader understands the file's role.
• Describe the preflight configuration. State that the preflight rule runs unit tests as release validation. Name the relevant [preflight] configuration in backticks.
• Describe the documentation-bump configuration. State that the [bump.documentation] globs target README.md and docs/users-guide.md. Explain that Lading updates workspace-crate version references inside TOML code fences in those files.
• Add an update-trigger note using the established phrasing pattern: when release-validation requirements or documentation paths change, update lading.toml and this section in the same change-set.
• Follow the existing section style: prose paragraphs, config keys and file paths in backticks, sentence-case heading, and inline external links.
• Do not add a completion checklist. Only the mutation-testing section carries one.

Task 2: Update the documentation index summary

Keep docs/contents.md synchronised with the new developer-guide topic.

• Extend the developers-guide.md bullet under ## Contributor guidance in docs/contents.md.
• Append a Lading configuration phrase to the existing comma-joined noun-phrase list, matching the current format and ~80-column wrap with a 2-space continuation indent.

Task 3: Reconcile the prose against `lading.toml`

Confirm the documentation matches the actual configuration file to meet the consistency acceptance criterion.

• Read lading.toml if it is present on the branch.
• Confirm the preflight description matches the actual preflight keys and values.
• Confirm the documentation-bump globs in the prose match the actual [bump.documentation].globs entries, including README.md and docs/users-guide.md.
• Correct any drift between the prose and the file before completion.

🤖 Prompt for AI agents

Implement a documentation-only change that adds a "Lading configuration" section
to `docs/developers-guide.md` and keeps `docs/contents.md` in sync.

Step 1 — Add the section:
- Insert a new `## Lading configuration` section into
`docs/developers-guide.md`, immediately after the "Release help tooling"
section.
- Identify `lading.toml` at the repository root as the configuration file for
Lading. Link the tool name inline to https://github.com/leynos/lading.
- State that Lading is a configuration-driven release tool for Rust workspaces.
- Describe the preflight configuration: state that the preflight rule runs unit
tests as release validation, and name the relevant `[preflight]` configuration
key in backticks.
- Describe the documentation-bump configuration: state that
`[bump.documentation]` globs target `README.md` and `docs/users-guide.md`, and
explain that Lading updates workspace-crate version references inside TOML code
fences in those files.
- Add an update-trigger note using the phrase pattern: when release-validation
requirements or documentation paths change, update `lading.toml` and this
section in the same change-set.
- Match the existing section style exactly: prose paragraphs, config keys and
file paths in backticks, sentence-case heading, inline Markdown links for
external URLs.
- Do not add a completion checklist to this section — only the mutation-testing
section carries one.

Step 2 — Sync the documentation index:
- Extend the existing `developers-guide.md` bullet under `## Contributor
guidance` in `docs/contents.md`.
- Append a Lading configuration phrase to the existing comma-joined noun-phrase
list.
- Match the current format and the ~80-column wrap with a 2-space continuation
indent.

Step 3 — Reconcile with `lading.toml`:
- If `lading.toml` is present on the branch, read it.
- Verify the preflight description in the new section matches the actual
preflight keys and values in the file.
- Verify the documentation-bump globs stated in the prose match the actual
`[bump.documentation].globs` entries, including `README.md` and
`docs/users-guide.md`.
- Correct any drift between the prose and the file before finishing.

File-level scope:
- `docs/developers-guide.md`: add one `## Lading configuration` section after
"Release help tooling".
- `docs/contents.md`: extend the `developers-guide.md` summary bullet with a
Lading phrase.
- `lading.toml`: read-only reference for consistency checking. Do not modify
this file.

Research

docs/developers-guide.md is a single large file that uses ## sentence-case headings for each developer-tooling and CI-configuration topic. It already documents comparable third-party tools with a consistent structure: tool purpose, concrete config file paths in backticks, invocation commands in fenced bash blocks, contract-test references, and an update-trigger note.

docs/contents.md holds one summary bullet per document under ## Contributor guidance.

docs/documentation-style-guide.md mandates sentence-case headings, inline Markdown links for external URLs, and the phrasing pattern "When <trigger> changes, update this file in the same change-set".

No reference to "Lading" or lading.toml exists anywhere in the repository yet.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Implement a documentation-only change that adds a "Lading configuration" section
to `docs/developers-guide.md` and keeps `docs/contents.md` in sync.

Step 1 — Add the section:
- Insert a new `## Lading configuration` section into
`docs/developers-guide.md`, immediately after the "Release help tooling"
section.
- Identify `lading.toml` at the repository root as the configuration file for
Lading. Link the tool name inline to https://github.com/leynos/lading.
- State that Lading is a configuration-driven release tool for Rust workspaces.
- Describe the preflight configuration: state that the preflight rule runs unit
tests as release validation, and name the relevant `[preflight]` configuration
key in backticks.
- Describe the documentation-bump configuration: state that
`[bump.documentation]` globs target `README.md` and `docs/users-guide.md`, and
explain that Lading updates workspace-crate version references inside TOML code
fences in those files.
- Add an update-trigger note using the phrase pattern: when release-validation
requirements or documentation paths change, update `lading.toml` and this
section in the same change-set.
- Match the existing section style exactly: prose paragraphs, config keys and
file paths in backticks, sentence-case heading, inline Markdown links for
external URLs.
- Do not add a completion checklist to this section — only the mutation-testing
section carries one.

Step 2 — Sync the documentation index:
- Extend the existing `developers-guide.md` bullet under `## Contributor
guidance` in `docs/contents.md`.
- Append a Lading configuration phrase to the existing comma-joined noun-phrase
list.
- Match the current format and the ~80-column wrap with a 2-space continuation
indent.

Step 3 — Reconcile with `lading.toml`:
- If `lading.toml` is present on the branch, read it.
- Verify the preflight description in the new section matches the actual
preflight keys and values in the file.
- Verify the documentation-bump globs stated in the prose match the actual
`[bump.documentation].globs` entries, including `README.md` and
`docs/users-guide.md`.
- Correct any drift between the prose and the file before finishing.

File-level scope:
- `docs/developers-guide.md`: add one `## Lading configuration` section after
"Release help tooling".
- `docs/contents.md`: extend the `developers-guide.md` summary bullet with a
Lading phrase.
- `lading.toml`: read-only reference for consistency checking. Do not modify
this file.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!