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

.coderabbit.yaml

@@ -0,0 +1,177 @@
+language: en-US
+tone_instructions: ''
+early_access: false
+enable_free_tier: true
+reviews:
+  profile: chill
+  request_changes_workflow: false
+  high_level_summary: true
+  high_level_summary_placeholder: '@coderabbitai summary'
+  high_level_summary_in_walkthrough: false
+  auto_title_placeholder: '@coderabbitai'
+  auto_title_instructions: ''
+  review_status: true
+  commit_status: true
+  fail_commit_status: false
+  collapse_walkthrough: false
+  changed_files_summary: true
+  sequence_diagrams: true
+  assess_linked_issues: true
+  related_issues: true
+  related_prs: true
+  suggested_labels: true
+  auto_apply_labels: false
+  suggested_reviewers: true
+  auto_assign_reviewers: false
+  poem: false
+  labeling_instructions: []
+  path_filters: []
+  path_instructions:
+    - path: "src/**/*.{ts,tsx}"
+      instructions: |
+        If there are any changes to the public-facing API, add a review comment: "Public API changes detected. Please update the documentation and the Ably CLI."
+  abort_on_close: true
+  disable_cache: false
+  auto_review:
+    enabled: true
+    auto_incremental_review: true
+    ignore_title_keywords: []
+    labels: []
+    drafts: false
+    base_branches: []
+  finishing_touches:
+    docstrings:
+      enabled: true
+    unit_tests:
+      enabled: true
+  pre_merge_checks:
+    docstrings:
+      mode: warning
+      threshold: 80
+    title:
+      mode: warning
+      requirements: ''
+    description:
+      mode: warning
+    issue_assessment:
+      mode: warning
+  tools:
+    ast-grep:
+      rule_dirs: []
+      util_dirs: []
+      essential_rules: true
+      packages: []
+    shellcheck:
+      enabled: true
+    ruff:
+      enabled: true
+    markdownlint:
+      enabled: true
+    github-checks:
+      enabled: true
+      timeout_ms: 90000
+    languagetool:
+      enabled: true
+      enabled_rules: []
+      disabled_rules: []
+      enabled_categories: []
+      disabled_categories: []
+      enabled_only: false
+      level: default
+    biome:
+      enabled: true
+    hadolint:
+      enabled: true
+    swiftlint:
+      enabled: true
+    phpstan:
+      enabled: true
+      level: default
+    phpmd:
+      enabled: true
+    phpcs:
+      enabled: true
+    golangci-lint:
+      enabled: true
+    yamllint:
+      enabled: true
+    gitleaks:
+      enabled: true
+    checkov:
+      enabled: true
+    detekt:
+      enabled: true
+    eslint:
+      enabled: true
+    flake8:
+      enabled: true
+    rubocop:
+      enabled: true
+    buf:
+      enabled: true
+    regal:
+      enabled: true
+    actionlint:
+      enabled: true
+    pmd:
+      enabled: true
+    cppcheck:
+      enabled: true
+    semgrep:
+      enabled: true
+    circleci:
+      enabled: true
+    clippy:
+      enabled: true
+    sqlfluff:
+      enabled: true
+    prismaLint:
+      enabled: true
+    pylint:
+      enabled: true
+    oxc:
+      enabled: true
+    shopifyThemeCheck:
+      enabled: true
+    luacheck:
+      enabled: true
+    brakeman:
+      enabled: true
+    dotenvLint:
+      enabled: true
+    htmlhint:
+      enabled: true
+    checkmake:
+      enabled: true
+chat:
+  auto_reply: true
+  integrations:
+    jira:
+      usage: auto
+    linear:
+      usage: auto
+knowledge_base:
+  opt_out: false
+  web_search:
+    enabled: true
+  code_guidelines:
+    enabled: true
+    filePatterns: []
+  learnings:
+    scope: auto
+  issues:
+    scope: auto
+  jira:
+    usage: auto
+    project_keys: []
+  linear:
+    usage: auto
+    team_keys: []
+  pull_requests:
+    scope: auto
+code_generation:
+  docstrings:
+    language: en-US
+    path_instructions: []
+  unit_tests:
+    path_instructions: []

CONTRIBUTING.md

@@ -9,29 +9,71 @@
 5. Push the branch (`git push origin my-new-feature`)
 6. Create a new Pull Request
 
+## Validate website doc snippets
+
+To validate that the web documentation code snippets are accurate and up-to-date with the SDK source code, run the following prompt against a locally cloned copy of the [ably/docs](https://github.com/ably/docs) repository and this SDK repository.
+
+> [!IMPORTANT]
+> This prompt should be run with the most powerful LLM available to you (e.g. Claude Opus, GPT-5, etc.) for the best results.
+
+Replace `{DOCS_PATH}` with the path to your local clone of the [ably/docs](https://github.com/ably/docs) repository and `{SDK_PATH}` with the path to your local clone of the [ably-chat-react-ui-kit](https://github.com/ably/ably-chat-react-ui-kit) SDK repository. Ensure both the local `ably/docs` and `ably-chat-react-ui-kit` repositories are on the `main` branch and in sync with the remote.
+
+```text
+Verify all `react` annotated code snippets in `.mdx` files located at `{DOCS_PATH}/src/pages/docs/chat/react-ui-kit` against the `ably-chat-react-ui-kit` source code repository at `{SDK_PATH}`. Additionally, validate the file `{DOCS_PATH}/src/pages/docs/chat/getting-started/react-ui-kit.mdx` against the same `ably-chat-react-ui-kit` repository.
+
+### Verification Steps:
+
+1. **Find all code snippets**: Search for all code blocks with the `react` annotation in `.mdx` files.
+
+2. **Understand SDK structure**: Analyze the SDK source code to understand:
+   - Public React components and their props
+   - Public React hooks and their signatures (parameters, return types)
+   - Public context providers and their usage
+   - Exported types and interfaces
+   - Namespaces and import requirements
+
+3. **Cross-check each snippet** for the following issues:
+   - **Syntax errors**: Incorrect hook calls, missing or extra arguments, mismatched JSX tags, incorrect destructuring
+   - **Naming conventions**: Verify casing matches React conventions (e.g., `PascalCase` for components, `camelCase` for hooks and props, `use` prefix for hooks)
+   - **API accuracy**: Verify hook names, component names, prop names, and return values exist in the SDK
+   - **Type correctness**: Verify correct types are used (e.g., correct option keys, callback signatures)
+   - **Namespace/import requirements**: Note any required imports that are missing from examples
+   - **Wrong language**: Detect if code from another language was accidentally used
+
+4. **Generate a verification report** with:
+   - Total snippets found
+   - List of issues found with:
+     - File path and line number
+     - Current (incorrect) code
+     - Expected (correct) code
+     - Source reference in SDK
+   - List of verified APIs that are correct
+   - Success rate percentage
+   - Recommendations for fixes
+
+### Output Format:
+Create/update a markdown report file at `chat_react_ui_kit_api_verification_report.md` with all findings.
+```
+
 ## Release Process
 
-1. Make sure the tests are passing in CI for main
+1. Make sure the tests are passing in CI for main.
 2. Add a new commit using Semantic Versioning rules.
-    1. [Semantic Versioning guidelines](https://semver.org/) entail a format of M.m.p, for example 1.2.3, where:
-        - The first number represents a major release, which lets users know a breaking change has occurred that will
-          require action from them.
-        - The second number represents a minor release, which lets users know new functionality or features have been
-          added.
-        - The third number represents a patch release, which represents bug-fixes and may be used when no action should
-          be required from users.
-    2. The commit should update `package.json` and `package-lock.json`. Running `npm install` after changing
-       `package.json` will update `package-lock.json`.
-    3. You must also set the `version` field in `src/index.ts` file to match the new version.
-    4. Update the `CHANGELOG.md` with any customer-affecting changes since the last release.
-    5. Update the README.md for any references to the new version.
-    6. If making breaking changes, add steps to upgrade to the `UPGRADING.md`.
+   1. [Semantic Versioning guidelines](https://semver.org/) entail a format of M.m.p, for example 1.2.3, where:
+      - The first number represents a major release, which lets users know a breaking change has occurred that will require action from them.
+      - The second number represents a minor release, which lets users know new functionality or features have been added.
+      - The third number represents a patch release, which represents bug-fixes and may be used when no action should be required from users.
+   2. The commit should update `package.json` and `package-lock.json`. Running `npm install` after changing `package.json` will update `package-lock.json`.
+   3. You must also set the `version` field in `src/index.ts` file to match the new version.
+   4. Update the `CHANGELOG.md` with any customer-affecting changes since the last release.
+   5. Update the README.md for any references to the new version.
+   6. If making breaking changes, add steps to upgrade to the `UPGRADING.md`.
 3. Merge the commit into main.
-4. Tag a release
-   using [Github releases](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release).
-   The version needs to match the one from the commit. Use the "Generate release notes" button to
-   add changelog notes and update as required.
+4. Tag a release using [GitHub releases](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release). The version needs to match the one from the commit. Use the "Generate release notes" button to add changelog notes and update as required.
 5. Ensure that the NPM Publish action has run successfully.
+6. If you've deprecated any public components or hooks, 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 `react` 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.
+7. 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.
+8. Merge any [website docs](https://github.com/ably/docs) PRs related to the changes.
 
 ## Development Setup