Docs: add capability matrix, cookbook, versioning guide, and CI quality gates#127
Docs: add capability matrix, cookbook, versioning guide, and CI quality gates#127teesofttech wants to merge 1 commit into
Conversation
📝 WalkthroughWalkthroughAdds API integration and gateway capability documentation, release/versioning guidance, MkDocs navigation entries, and a GitHub Actions workflow that lints, link-checks, and strictly builds the documentation. ChangesDocumentation quality and release guidance
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
.github/workflows/docs-quality.yml (1)
37-38: 🔒 Security & Privacy | 🔵 TrivialDisable credential persistence on checkout. This docs-only workflow only reads the repo, so
persist-credentials: falseavoids leaving the token in git config.🤖 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 @.github/workflows/docs-quality.yml around lines 37 - 38, Update the Checkout step in the docs-quality workflow to set persist-credentials to false, while preserving the existing actions/checkout configuration.Source: Linters/SAST tools
🤖 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 `@docs/api-cookbook.md`:
- Line 32: Update every repeated “Production checklist” heading in
docs/api-cookbook.md to include flow-specific context, and do the same for each
repeated “Pattern” heading and the headings at the referenced locations such as
“50-50” and “58-58”. Keep the headings semantically clear and uniquely named so
MD024 passes and generated navigation remains understandable.
---
Nitpick comments:
In @.github/workflows/docs-quality.yml:
- Around line 37-38: Update the Checkout step in the docs-quality workflow to
set persist-credentials to false, while preserving the existing actions/checkout
configuration.
🪄 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: defaults
Review profile: CHILL
Plan: Pro
Run ID: b1f1e993-4f4f-4a48-9677-97c18b8f2b7e
📒 Files selected for processing (8)
.github/workflows/docs-quality.yml.lychee.toml.markdownlint-cli2.jsoncdocs/api-cookbook.mddocs/gateway-capability-matrix.mddocs/index.mddocs/versioning-and-release-notes.mdmkdocs.yml
| 4. On redirect or webhook, call VerifyPaymentAsync. | ||
| 5. Fulfill only when provider verification confirms success and expected amount/currency. | ||
|
|
||
| ## Production checklist |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Make repeated headings unique.
The docs-quality workflow fails MD024 because Pattern and Production checklist recur. Add flow-specific context to every occurrence so markdownlint passes and the generated navigation remains clear.
Proposed fix
-## Production checklist
+## Production checklist — Flow 1: Create Payment
-## Production checklist
+## Production checklist — Flow 2: Automatic Routing
-## Pattern
+## Pattern — Flow 3: Secure Webhooks
-## Production checklist
+## Production checklist — Flow 3: Secure Webhooks
-## Pattern
+## Pattern — Flow 4: Refund Request and Reconciliation
-## Production checklist
+## Production checklist — Flow 4: Refund Request and ReconciliationAlso applies to: 50-50, 58-58, 66-66, 74-74, 81-81
🤖 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/api-cookbook.md` at line 32, Update every repeated “Production
checklist” heading in docs/api-cookbook.md to include flow-specific context, and
do the same for each repeated “Pattern” heading and the headings at the
referenced locations such as “50-50” and “58-58”. Keep the headings semantically
clear and uniquely named so MD024 passes and generated navigation remains
understandable.
Sources: Linters/SAST tools, Pipeline failures
There was a problem hiding this comment.
Pull request overview
Adds and wires new documentation pages (capability matrix, cookbook, versioning/release notes) into the MkDocs site, and introduces CI quality gates (markdown lint, link check, strict MkDocs build) to keep docs reliable as the project grows.
Changes:
- Added new docs pages: gateway capability matrix, API cookbook, and versioning/release notes.
- Updated MkDocs navigation and homepage discovery links to include the new pages.
- Added a “Docs Quality” GitHub Actions workflow plus markdownlint/lychee config for consistent docs validation in CI.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| mkdocs.yml | Adds new pages to MkDocs navigation under new sections. |
| docs/api-cookbook.md | Introduces end-to-end integration flows and production checklists. |
| docs/gateway-capability-matrix.md | Documents gateway feature support and webhook operational guidance. |
| docs/versioning-and-release-notes.md | Adds SemVer policy, release gating checklist, and release notes template. |
| docs/index.md | Links to new docs pages from the homepage. |
| .github/workflows/docs-quality.yml | Adds CI quality gates: markdown lint, link checking, strict MkDocs build. |
| .markdownlint-cli2.jsonc | Configures markdownlint rules for the docs gate. |
| .lychee.toml | Configures lychee link checking behavior and exclusions. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| ## Release Triggers | ||
|
|
||
| - Tag pattern: v*.*.* |
| "gateway": 2 | ||
| } | ||
| ``` | ||
|
|
Summary
Validation
Included files
Summary by CodeRabbit
Documentation
Chores