ci(repo): restore release-triggered TypeDoc sync (#9988)

Co-authored-by: Michael Novotny <manovotny@gmail.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: 3 people

.changeset/fix-typedoc-workflow.md

@@ -0,0 +1,2 @@
+---
+---

.github/workflows/pr-title-linter.yml

@@ -34,5 +34,5 @@ jobs:
           PR_TITLE: ${{ github.event.pull_request.title }}
         run: |
           npm init --scope=clerk --yes
-          npm i --save-dev @commitlint/config-conventional @commitlint/cli globby --audit=false --fund=false
+          npm i --save-dev @commitlint/config-conventional @commitlint/cli --audit=false --fund=false
           echo "$PR_TITLE" | npm exec @commitlint/cli -- --config commitlint.config.ts

.github/workflows/release.yml

@@ -130,7 +130,6 @@ jobs:
 
       - name: Trigger workflows on related repos
         if: steps.changesets.outputs.published == 'true'
-        continue-on-error: true
         uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
         with:
           result-encoding: string
@@ -148,17 +147,25 @@ jobs:
               const targets = [
                 { repo: 'sdk-infra-workers', workflow_id: 'update-pkg-versions.yml', inputs: { clerkjsVersion, clerkUiVersion } },
                 { repo: 'dashboard', workflow_id: 'prepare-nextjs-sdk-update.yml', inputs: { version: nextjsVersion } },
-                { repo: 'clerk-docs', workflow_id: 'typedoc.yml' },
+                { repo: 'clerk', workflow_id: 'docs-typedoc.yml', inputs: { javascript_ref: context.sha }, critical: true },
               ];
               const results = await Promise.allSettled(
-                targets.map(t => github.rest.actions.createWorkflowDispatch({ owner: 'clerk', ref: 'main', ...t }))
+                targets.map(({ repo, workflow_id, inputs }) =>
+                  github.rest.actions.createWorkflowDispatch({ owner: 'clerk', repo, workflow_id, ref: 'main', inputs })
+                )
               );
               const failures = results
                 .map((r, i) => r.status === 'rejected' ? { target: targets[i], reason: r.reason } : null)
                 .filter(Boolean);
               if (failures.length) {
-                failures.forEach(f => core.error(`Dispatch to ${f.target.repo}/${f.target.workflow_id} failed: ${f.reason?.message ?? f.reason}`));
-                core.setFailed(`${failures.length} downstream dispatch(es) failed`);
+                failures.forEach(f => {
+                  const message = `Dispatch to ${f.target.repo}/${f.target.workflow_id} failed: ${f.reason?.message ?? f.reason}`;
+                  if (f.target.critical) {
+                    core.setFailed(message);
+                  } else {
+                    core.warning(message);
+                  }
+                });
               }
             } else{
               core.warning("Changeset in pre-mode should not prepare a ClerkJS production release")
@@ -171,7 +178,6 @@ jobs:
       # if the packages are already live.
       - name: Recover downstream notifications
         if: always() && steps.changesets.conclusion == 'failure'
-        continue-on-error: true
         uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
         with:
           result-encoding: string
@@ -230,24 +236,32 @@ jobs:
             const targets = [
               { repo: 'sdk-infra-workers', workflow_id: 'update-pkg-versions.yml', inputs: { clerkjsVersion, clerkUiVersion } },
               { repo: 'dashboard', workflow_id: 'prepare-nextjs-sdk-update.yml', inputs: { version: nextjsVersion } },
-              { repo: 'clerk-docs', workflow_id: 'typedoc.yml' },
+              { repo: 'clerk', workflow_id: 'docs-typedoc.yml', inputs: { javascript_ref: context.sha }, critical: true },
             ];
             const results = await Promise.allSettled(
-              targets.map(t => github.rest.actions.createWorkflowDispatch({ owner: 'clerk', ref: 'main', ...t }))
+              targets.map(({ repo, workflow_id, inputs }) =>
+                github.rest.actions.createWorkflowDispatch({ owner: 'clerk', repo, workflow_id, ref: 'main', inputs })
+              )
             );
             const failures = results
               .map((r, i) => r.status === 'rejected' ? { target: targets[i], reason: r.reason } : null)
               .filter(Boolean);
             if (failures.length) {
-              failures.forEach(f => core.error(`Recovery dispatch to ${f.target.repo}/${f.target.workflow_id} failed: ${f.reason?.message ?? f.reason}`));
-              core.setFailed(`${failures.length} recovery dispatch(es) failed`);
+              failures.forEach(f => {
+                const message = `Recovery dispatch to ${f.target.repo}/${f.target.workflow_id} failed: ${f.reason?.message ?? f.reason}`;
+                if (f.target.critical) {
+                  core.setFailed(message);
+                } else {
+                  core.warning(message);
+                }
+              });
             } else {
               core.notice('Recovery dispatch completed successfully');
             }
 
       - name: Generate notification payload
         id: notification
-        if: steps.changesets.outputs.published == 'true'
+        if: ${{ !cancelled() && steps.changesets.outputs.published == 'true' }}
         env:
           PUBLISHED_PACKAGES: ${{ steps.changesets.outputs.publishedPackages }}
           GH_ACTOR: ${{ github.actor }}
@@ -261,7 +275,7 @@ jobs:
 
       - name: Send commit log to Slack
         id: slack
-        if: steps.changesets.outputs.published == 'true'
+        if: ${{ !cancelled() && steps.changesets.outputs.published == 'true' && steps.notification.outcome == 'success' }}
         uses: slackapi/slack-github-action@fcfb566f8b0aab22203f066d80ca1d7e4b5d05b3 # v1.27.1
         with:
           payload: ${{ steps.notification.outputs.payload }}

docs/CICD.md

@@ -14,7 +14,7 @@ A stable release will be triggered every time the "ci(repo): Version packages" P
 - All SDKs will be published to `npm`, except for those found in the excluded packages list in `.changeset/config.json`, or any packages with `private: true` set in their `package.json` file.
 - A workflow dispatch will be triggered to update the `clerkjs-proxy` worker in `clerk/sdk-infra-workers`.
 - A workflow dispatch will be triggered to update the `@clerk/nextjs` version in `clerk/dashboard`.
-- A workflow dispatch will be triggered to update the typedoc generated docs in `clerk/clerk-docs`.
+- A workflow dispatch will be triggered to update the generated TypeDoc files in `clerk/clerk` under `clerk-docs/clerk-typedoc/`.
 
 For details regarding the package versioning/publishing process, refer to the [Publishing docs](https://github.com/clerk/javascript/blob/main/docs/PUBLISH.md).
 

docs/CONTRIBUTING.md

@@ -192,17 +192,17 @@ For a comprehensive guide on **authoring** JSDoc/Typedoc comments, see [this gui
 
 To review your changes locally, you can run `pnpm run typedoc:generate` to generate the docs. Afterwards, you can inspect the MDX files inside `.typedoc/docs`. But if you want to preview how the Typedoc output will look in Clerk Docs, there's a few things you need to do first:
 
-Create a PR that includes your changes to any Typedoc comments. Once the PR has been merged and a release is published, a PR will [automatically](https://github.com/clerk/clerk-docs/blob/main/.github/workflows/typedoc.yml) be opened in `clerk-docs` to merge in the Typedoc changes.
+Create a PR that includes your changes to any Typedoc comments. Once the PR has been merged and a release is published, the release workflow automatically opens a PR in Clerk's docs repository with the Typedoc changes.
 
 Typedoc output is embedded in `clerk-docs` files with the `<Typedoc />` component. For example, if you updated Typedoc comments for the `useAuth()` hook in `clerk/javascript`, you'll need to make sure that in `clerk-docs`, in the `/hooks/use-auth.mdx` file, there's a `<Typedoc />` component linked to the `./clerk-typedoc/react/use-auth.mdx` file, like:
 
 ```mdx
 <Typedoc src='react/use-auth' />
 ```
 
-Read more about this in the [`clerk-docs` CONTRIBUTING.md](https://github.com/clerk/clerk-docs/blob/main/CONTRIBUTING.md#typedoc-).
+Read more about this in the [`clerk-docs` CONTRIBUTING.md](https://github.com/clerk/clerk-docs/blob/main/contributing/CONTRIBUTING.md#typedoc-).
 
-Then, to preview how the `<Typedoc />` component renders, the `clerk-docs` PR will have a Vercel preview. Or to get local previews set up, see the [section in `clerk/clerk` about setting up local docs](https://github.com/clerk/clerk?tab=readme-ov-file#5-optional-set-up-local-docs).
+Then, to preview how the `<Typedoc />` component renders, that docs PR will have a Vercel preview. Or to get local previews set up, see the [section in `clerk/clerk` about setting up local docs](https://github.com/clerk/clerk?tab=readme-ov-file#5-optional-set-up-local-docs).
 
 ### Experimental and internal APIs