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 swift code snippets in the web documentation against the SDK source code.

Summary by CodeRabbit

• Documentation
  • Added guidance to the contributing guide for validating documentation Swift code snippets, including how to run validation, inspect output, and expected formatting.
  • Extended the release process with steps to run documentation validation locally when deprecating or uncertain, and to create/update and merge website docs PRs for SDK/version and doc fixes.
  • Note: the new guidance appears duplicated in the contributing guide.

[coderabbitai]

Walkthrough

Adds duplicated "Validate website doc snippets" guidance to CONTRIBUTING.md and inserts two Release-process steps recommending running the validation task locally, creating a website docs PR to update SDK/version and fix docs, and merging related website docs PRs.

Changes

Cohort / File(s)	Summary
Documentation CONTRIBUTING.md	Added a duplicated "Validate website doc snippets" guidance block. Updated Release process in two places to: (1) recommend running the validation task locally when deprecating public members or unsure impact, (2) create a website docs PR to update SDK version and fix documentation issues, and (3) merge related website docs PRs.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I hopped through CONTRIBUTING with glee,

Checked each snippet, swift as can be.
Two little guides now guard the docs' light,
So SDK and website stay tidy and right.
🥕

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

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

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

✨ Finishing Touches

🧪 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.

[coderabbitai]

Actionable comments posted: 4

🤖 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`:
- Line 204: Update the CONTRIBUTING.md instruction that tells the LLM to
create/update chat_swift_api_verification_report.md to specify a safe output
location and/or prevent commits: change the directive to either write the file
to an explicit out‑of‑tree path (for example in the user's home directory) or
add guidance to add chat_swift_api_verification_report.md to .gitignore and
state clearly that the file must not be committed; reference the filename
chat_swift_api_verification_report.md in the text so readers and automation know
which file to ignore or where to place it.
- Line 220: The sentence on line containing "made changes to public interfaces"
is wordy; update that phrase to "changed public interfaces" so the line reads:
"If you’ve deprecated any public methods or properties, changed public
interfaces, or are uncertain about the impact of your updates, run the [Validate
website docs snippet changes](`#validate-website-docs-snippet-changes`) task
locally..." — replace only the phrase "made changes to public interfaces" with
"changed public interfaces" to keep the rest of the sentence intact.
- Line 170: The fenced code block in CONTRIBUTING.md is missing a language
specifier which triggers MD040; update the opening triple-backtick fence for the
snippet that starts with "Verify all `swift` annotated code snippets ..." to
include a language tag (e.g., use text or plaintext) so the fence becomes
```text and enables correct rendering and linting.
- Around line 185-188: Update the CONTRIBUTING.md bullets "Syntax errors" and
"Naming conventions" to remove non‑Swift examples and replace them with
Swift‑specific guidance: for "Syntax errors" mention issues like missing init
methods, incorrect use of optional unwrapping (force unwrapping vs optional
binding), incorrect protocol conformance signatures, and misplaced braces or
parentheses; for "Naming conventions" replace JS/C#/Kotlin examples with Swift
conventions (UpperCamelCase for types, camelCase for properties/variables,
lowerCamelCase for enums/cases only when using camelCase API, and leading
underscore rules). Ensure the "API accuracy" and "Type correctness" bullets
remain but, where examples are needed, reference Swift symbols such as init(),
Optional, enum cases, and protocol names to avoid cross‑language artifacts.

[coderabbitai]

🤖 Prompt for all review comments with AI agents

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

Duplicate comments:
In `@CONTRIBUTING.md`:
- Line 204: The CONTRIBUTING.md instruction to "Create/update a markdown report
file `chat_swift_api_verification_report.md`" lacks a safe output path; update
the docs to either (1) recommend creating the report in an out-of-tree location
(example: ~/chat_swift_api_verification_report.md) or (2) require adding
`chat_swift_api_verification_report.md` to .gitignore before creating it;
reference the filename `chat_swift_api_verification_report.md` in the text and
add a short note showing the preferred option so contributors won’t accidentally
stage/commit the file.

[maratal]

Shouldn't it use similar aproach as implemented in ably/docs#3192? (translate-examples-to-swift skill). If no, shouldn't the provided prompt live in the skills directory instead of floating as a text block in the guide?

[sacOO7]

Shouldn't it use similar aproach as implemented in ably/docs#3192? (translate-examples-to-swift skill). If no, shouldn't the provided prompt live in the skills directory instead of floating as a text block in the guide?

We can surely add this to claude skills in the near future and also add it to the CI -> https://ably.atlassian.net/browse/DX-837. However, this approach seems limited to Claude. So, we should always have a separate generic prompt that can be used with any LLM, in case Claude is unavailable/offline, so we can manually run and verify the website docs as part of the release process.

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

[coderabbitai]

🧹 Nitpick comments (2)

CONTRIBUTING.md (2)

220-221: Break down this complex multi-action step for clarity.

This bullet point combines several distinct actions into a single, dense sentence:

1. A conditional check (deprecated methods, changed interfaces, or uncertainty)
2. Running the validation task
3. Reviewing the report
4. Creating a docs PR with version update and fixes
5. A requirement to create a PR even without API changes

Consider restructuring this as a parent bullet with sub-items, or as separate sequential bullets, to improve readability and make each action explicit.

Additionally, the statement "Even if there are no public API changes, a PR must still be created to update the SDK version" conflicts with the conditional opening. If a version-update PR is always required, consider making that a separate, unconditional step rather than embedding it within a conditional step.

♻️ Possible restructure

-- If you've deprecated any public methods or properties, changed public interfaces, or are uncertain about the impact of your updates, run the [Validate website doc snippets](`#validate-website-doc-snippets`) task locally. This will verify that the `swift` code snippets in the web documentation (https://github.com/ably/docs) are accurate and aligned with the current SDK source. Review the generated report and address any issues it identifies.
-- Create a PR on the [website docs](https://github.com/ably/docs) that updates the SDK version in the setup/installation guide. Additionally, include fixes for any documentation issues identified in the previous step. Even if there are no public API changes, a PR must still be created to update the SDK version.
+- If you've deprecated any public methods or properties, changed public interfaces, or are uncertain about the impact of your updates:
+  - Run the [Validate website doc snippets](`#validate-website-doc-snippets`) task locally to verify that the `swift` code snippets in the web documentation are accurate and aligned with the current SDK source
+  - Review the generated report and address any issues it identifies
+- Create a PR on the [website docs](https://github.com/ably/docs) to update the SDK version in the setup/installation guide and include fixes for any documentation issues identified above

🤖 Prompt for AI Agents

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

In `@CONTRIBUTING.md` around lines 220 - 221, Split the combined bullet that
begins "If you've deprecated any public methods or properties, changed public
interfaces, or are uncertain about the impact of your updates, run the [Validate
website doc snippets](`#validate-website-doc-snippets`) task locally..." into a
parent bullet with clear sub-items: (a) list the condition that triggers
validation ("deprecated methods, changed interfaces, or uncertainty"), (b)
instruct to run the "Validate website doc snippets" task, (c) instruct to review
and address the generated report, and (d) instruct to create a PR on the website
docs to update the SDK version and include any fixes; then extract the sentence
"Even if there are no public API changes, a PR must still be created to update
the SDK version" and make it a separate unconditional bullet so the
version-update requirement is explicit and not tied to the conditional
validation step.

---

226-226: Clarify which website docs PRs should be merged.

The phrase "Merge any [website docs] PRs related to the changes" is ambiguous. Does this refer to:

1. The version-update PR mentioned in the previous step (line 221)?
2. Additional PRs that may have been created independently?
3. Both?

Consider being more explicit, for example:

• "Merge the website docs PR created in the previous step" (if it's always one PR), or
• "Merge the version-update PR and any additional website docs PRs related to this release" (if there can be multiple)

♻️ Possible clarification

-- Merge any [website docs](https://github.com/ably/docs) PRs related to the changes.
+- Merge the [website docs](https://github.com/ably/docs) PR created above that updates the SDK version and any related fixes.

🤖 Prompt for AI Agents

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

In `@CONTRIBUTING.md` at line 226, Replace the ambiguous sentence "Merge any
[website docs] PRs related to the changes." with an explicit instruction naming
the version-update PR and any other docs PRs — e.g., "Merge the website docs
version-update PR created in the previous step and any additional website docs
PRs related to this release." This clarifies that both the version-update PR and
any other independent website docs PRs should be merged.

🤖 Prompt for all review comments with AI agents

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

Nitpick comments:
In `@CONTRIBUTING.md`:
- Around line 220-221: Split the combined bullet that begins "If you've
deprecated any public methods or properties, changed public interfaces, or are
uncertain about the impact of your updates, run the [Validate website doc
snippets](`#validate-website-doc-snippets`) task locally..." into a parent bullet
with clear sub-items: (a) list the condition that triggers validation
("deprecated methods, changed interfaces, or uncertainty"), (b) instruct to run
the "Validate website doc snippets" task, (c) instruct to review and address the
generated report, and (d) instruct to create a PR on the website docs to update
the SDK version and include any fixes; then extract the sentence "Even if there
are no public API changes, a PR must still be created to update the SDK version"
and make it a separate unconditional bullet so the version-update requirement is
explicit and not tied to the conditional validation step.
- Line 226: Replace the ambiguous sentence "Merge any [website docs] PRs related
to the changes." with an explicit instruction naming the version-update PR and
any other docs PRs — e.g., "Merge the website docs version-update PR created in
the previous step and any additional website docs PRs related to this release."
This clarifies that both the version-update PR and any other independent website
docs PRs should be merged.

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Jira integration is disabled

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 9fa8b7d and 71ee872.

📒 Files selected for processing (1)

• CONTRIBUTING.md