Added LLM-based website docs validation section to CONTRIBUTING.md

[sacOO7]

• Fixes https://ably.atlassian.net/browse/DX-485
• Added a new section in CONTRIBUTING.md with an LLM prompt to validate js/react code snippets in the web documentation against the SDK source code.

Summary by CodeRabbit

• Documentation
  • Added a documentation validation workflow for verifying JavaScript and React code snippets, including standardized prompts and report output formats.
  • Expanded the release process to require running doc-snippet validation, updating doc references/version selectors/examples, and addressing documentation issues discovered during validation.

---

Note

Low Risk
Documentation-only changes that adjust contributor/release guidance without affecting runtime code or published artifacts.

Overview
Adds a new “Validate website doc snippets” section to CONTRIBUTING.md with copy/paste LLM prompts to audit javascript and react code blocks in ably/docs chat .mdx pages against this SDK, including required checks and report file outputs.

Updates the Release Process to reference this validation step when public APIs change, and expands the docs-release checklist to include fixing issues found and merging related ably/docs PRs; also makes minor wording/punctuation tweaks.

^{Written by Cursor Bugbot for commit 7408b22. This will update automatically on new commits. Configure here.}

[coderabbitai]

Walkthrough

Adds a new "Validate website doc snippets" section to CONTRIBUTING.md with step-by-step JavaScript and React snippet verification prompts and report formats; expands the Release Process to include running doc-snippet validation and detailed doc/version/update steps; minor punctuation and organizational edits.

Changes

Cohort / File(s)	Summary
Documentation & contribution guidelines CONTRIBUTING.md	Introduces a "Validate website doc snippets" section with JavaScript and React LLM-assisted verification prompts and standardized verification report outputs; expands Release Process steps to require running doc-snippet validation, updating doc references/version selectors/examples, and applying documentation issue fixes; minor punctuation/formatting refinements.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding an LLM-based website docs validation section to CONTRIBUTING.md, which aligns with the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/doc-update-release-process

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sacOO7]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	95.56% (🎯 95%)	3961 / 4145
🔵	Statements	95.56% (🎯 95%)	3961 / 4145
🔵	Functions	98.98% (🎯 98%)	292 / 295
🔵	Branches	97.18% (🎯 97%)	965 / 993

File Coverage

No changed files found.

Generated in workflow #3155 for commit 7408b22 by the Vitest Coverage Report Action

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@CONTRIBUTING.md`:
- Around line 16-17: Replace the specific model examples in the "[!IMPORTANT]"
block that currently reads "These prompts should be run with the most powerful
LLM available to you (e.g. Claude Opus, GPT-4, etc.)" with a non-timebound
recommendation: either "the most capable model available to you" or, if you
prefer examples, update them to current flagship models (e.g., "GPT-5.2" and
"Anthropic Opus 4.6") and add a short parenthetical like "(update examples as
newer models are released)"; locate and edit the exact "[!IMPORTANT]" paragraph
in CONTRIBUTING.md to make this change.
- Line 57: The CONTRIBUTING prompt creates temporary report files
chat_javascript_api_verification_report.md and
chat_react_api_verification_report.md but they aren’t ignored; update the repo
so these generated reports aren’t accidentally committed by either adding those
two filenames to .gitignore or changing the prompt to write reports to an
explicit output directory outside the repository (e.g., a tmp/ or /tmp path).
Ensure you update the prompt text in CONTRIBUTING.md (the lines that reference
chat_javascript_api_verification_report.md and
chat_react_api_verification_report.md) to reflect the chosen fix so the
filenames or output path stay consistent.

[AndyTWF]

Question - should this be a skill/plugin we add to the internal MCP tooling? Perhaps it's re-usable across repositories rather than having to be in every single repos files?

[splindsay-92]

This should definitely be a skill (I think I mentioned this on the last PR adding to CONTRIBUTING.md. I think this sort of thing is useful for external users, but maybe this can also be an CI step that asks claude to validate website snippets and apply a review?

[sacOO7]

I looked into Claude Skills, and we can consider adding this as a Claude Skill in the near future.

However, that approach would be limited to Claude. We should also maintain a generic prompt that works with any LLM—especially in cases where Claude is unavailable or offline—so we can manually run it and verify the website documentation as a part of the release process.

Additionally, based on my experience, this task typically requires manual intervention and multiple refinement cycles to achieve accurate results.

[sacOO7]

Seems claude was down yesterday itself https://www.reddit.com/r/ClaudeAI/comments/1rir4n5/claude_is_down/, it's not always reliable : (

[splindsay-92]

Can we add a ticket around having a Claude skill (so we don't forget to revisit this) please? :)

[sacOO7]

Already have it here -> https://ably.atlassian.net/browse/DX-837

[splindsay-92]

Approving with the understanding we will track and add claude skills for devs around this soon.