docs(intro): cherry-pick #2991 + #2993 to stable for end-to-end test#2995
Merged
Conversation
* docs(intro): tighten installation card copy * chore: retrigger docs preview workflow
* ci(release): gate production docs on stable release success Mintlify currently deploys from main, so docs ship as soon as a doc commit lands, often weeks before the underlying packages reach npm via the weekly stable release. Move production docs onto a `docs-stable` branch that the release workflow only advances after every publish step succeeds, so docs and packages move together. - release-stable.yml pushes stable -> docs-stable as its final step, only reachable on full success - new preview-stable-docs.yml triggers a Mintlify preview for any PR targeting stable so the promote-stable PR shows reviewers the exact docs that will go live - requires manual setup before this can take effect: create the docs-stable branch from current stable, switch Mintlify's deployment branch in the dashboard, and add MINTLIFY_API_KEY / MINTLIFY_PROJECT_ID repo secrets (preview workflow no-ops without them) * fix(release): gate docs-stable promote on verified release SHA Address review on PR 2989. Two issues: - The promote step refetched `origin/stable` and pushed it, so a newer commit landing on stable while the release was still publishing would be promoted to docs-stable before the next run actually published it. The orchestrator now emits `promote_sha` (current HEAD) only when no package failed and no deferral happened; the workflow gates the push on that output and pushes the explicit SHA instead of refetching. - The preview workflow called `gh pr comment` without checking out the repo, so gh had no repo context. Added `--repo "$GITHUB_REPOSITORY"`.
Doc authors who PR against main currently get no hosted preview because Mintlify's automatic previews only fire on PRs targeting the deployment branch (docs-stable) and our preview workflow only fired on PRs targeting stable. They'd only see a preview when their work reached the promote-stable PR, days later. Add main as a trigger branch so doc-touching PRs to main get an instant preview URL. Path filter on apps/docs, document-api contract, and the generator script keeps the 5 req/min Mintlify API quota from being spent on unrelated code PRs. The path filter also applies to stable PRs but that's fine: promote-stable PRs always include docs, and code-only stable hotfixes don't need a docs preview.
The previous gate `action == 'opened'` skipped the comment whenever the workflow first ran on a `synchronize` event, which happens whenever the workflow file didn't exist on the base branch when the PR was opened (or on reopens). Replace it with an idempotency check that lists existing PR comments and only posts if none starts with the `📖 Docs preview:` marker.
Add a workflow that fires on docs-touching pushes to main and re-triggers Mintlify's preview for the main branch. Gives the team a persistent superdoc-main.mintlify.app URL that always reflects the current state of main, without anyone needing to open a draft PR. Production docs continue to come from docs-stable so this is purely additive.
Rename `preview-stable-docs.yml` to `docs-preview-pr.yml` (the file covered both main and stable PRs since #2992, so the old name was misleading) and `refresh-main-docs-preview.yml` to `docs-preview-main.yml`. Both now share the `docs-preview-` prefix so they sort together in the Actions UI, with display names "📖 Docs preview (PR)" and "📖 Docs preview (main)". Production promotion stays as a step inside release-stable.yml since it's gated on the orchestrator's `promote_sha` output and benefits from sharing a job with the release steps.
Contributor
|
📖 Docs preview: https://superdoc-caio-docs-stable-promote-test.mintlify.app |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
End-to-end validation of the docs deploy gate. Cherry-picks the two docs changes already merged on
main(#2991 and #2993) ontostableso we can watch them flow: PR opens →docs-preview-pr.ymlfires and posts a preview URL → reviewer checks the preview → on merge,release-stable.ymlruns, succeeds, pushes todocs-stable→ Mintlify deploys →docs.superdoc.devupdates to "Get started in seconds" + "Headless mode and agent workflows". This is a manual stand-in for whatpromote-stable.ymlwould do on its Tue/Sat schedule.