Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add docs versioning #310

Merged
merged 14 commits into from
Nov 11, 2021
Merged

Add docs versioning #310

merged 14 commits into from
Nov 11, 2021

Conversation

kylegach
Copy link
Collaborator

@kylegach kylegach commented Nov 4, 2021 •
edited

Note for reviewers

This is a much-improved take on #298. This new approach requires only updating releases files and Netlify branch build settings; everything else is automatic (based on the monorepo). 馃槑

I've taken care to organize the commits such that reviewing commit-by-commit should be clear (and doing so is recommended).

Description

Add versioning to Storybook docs.

  • Add a workflow to respond to monorepo events dispatched and create version branches
  • Via Netlify's branch deploys, build an instance of the docs portion of the site referencing specific versions from the monorepo.
  • Use Netlify's redirects to proxy the versioned URL to the branch build and Netlify's headers to prevent non-latest pages from being indexed by search engines.
  • Update URLs throughout to include version (unless latest)
    • Ensure relative links, canonical URLs, and social graph images are not broken
  • Add a version selector control to the docs sidebar to allow switching between these versions.
  • When not viewing latest docs, add a banner pointing to the latest version.
  • Other minor changes
    • Remove version from Header
    • Remove "v" prefix from latestVersion
    • Only build addons pages when referencing latest version
    • Add "Publishing new versions" section to README

Screenshot

Docs page showing the version in the url, version selector in the sidebar, and version callout above the content

How to Test

  1. Check Chromatic tests
  2. Run the site locally (yarn start & yarn build)
    • Ensure the correct version of docs is built and you can navigate fully
      • Keep in mind the redirects won't work
  3. Run the site locally with a reference branch specified
    • BRANCH=release-6-0 yarn build, or BRANCH=release-6-0 yarn extract-monorepo-docs && yarn start
    • Ensure the correct version of docs is built and you can navigate fully
      • Keep in mind the redirects won't work
  4. Ensure that yarn extract-monorepo-docs and yarn link-monorepo-docs still work, with their various arguments
  5. Triple-check anything SEO-related (redirect generation code, canonical URLs, headers), please 馃槈

TODO

  • Ensure algolia search works w/ and w/o versions
    • Fairly sure it works w/o
    • They provided a path for versioning support, but will wait until we get on their latest beta release

After merging this...

  • Add release-6-0, release-6-1, release-6-2, release-6-4 branches to Netlify build settings

After merging storybookjs/storybook#16580...

  • Push to those branches in the monorepo to kick off the process

@kylegach
Add workflow to create version branch
a0d5f0e 
- Responds to event dispatched by monorepo workflow
    - storybookjs/storybook#16580
@kylegach kylegach force-pushed the docs-versioning-3 branch 2 times, most recently from c162580 to 48c4fb0 Compare November 4, 2021 20:45
@kylegach
Copy link
Collaborator Author

kylegach commented Nov 4, 2021

I approved the Chromatic checks myself as the visual changes are identical (literally copy/pasted the code) to those already approved in #298.

@kylegach
Extend extract-monorepo-docs
437f127 
- Still pulls from main by default
- Will pull from relevant monorepo branch based on env.BRANCH
    - That env var is a Netlify convention
@kylegach
Add extract-all-monorepo-versions script
88130d1 
- Run inside `extract-monorepo-docs` & `link-monorepo-docs` to grab necessary version numbers
@kylegach
Add versioned pages with correct URLs
c906d1f 
- Add version to all appropriate URLs
- Use `pageContext.fullPath` instead of `data.currentPage.fields.slug`, where appropriate
    - `fullPath` includes version & framework
- Use `pageContext.slug` instead of `data.currentPage.fields.slug` everywhere else
    - Obviates the need for `data.currentPage.fields.slug` entirely
- Extract addStateToToc util
- Make stories more realistic
@kylegach
Remove/fix latestVersion renders
e91ecff 
- Remove from Header
- Fix format in IndexScreen/Hero
kylegach
kylegach commented Nov 4, 2021
View reviewed changes
scripts/move-built-files.sh Outdated Show resolved Hide resolved
@kylegach
Copy link
Collaborator Author

kylegach commented Nov 5, 2021 •
edited

Versioned builds shouldn't have a sitemap. Done.

@kylegach kylegach force-pushed the docs-versioning-3 branch 5 times, most recently from 2f4706d to 98940aa Compare November 6, 2021 03:11
@kylegach
Copy link
Collaborator Author

kylegach commented Nov 8, 2021 •
edited

You can preview the (now working! 馃帀 thanks, @winkerVSbecks!) functionality in this deploy preview:

https://6189eb2701d89a00078dc040--storybook-frontpage.netlify.app/docs/react/get-started/introduction

Note that only 6.2, 6.3 (latest), and 6.4 (beta) are currently built, so you can only switch between those three for this preview build.

You can also check the "next" redirect:

https://6189eb2701d89a00078dc040--storybook-frontpage.netlify.app/docs/next/react/get-started/introduction

@kylegach kylegach force-pushed the docs-versioning-3 branch 6 times, most recently from 435b92e to 9cb8216 Compare November 9, 2021 04:37
@kylegach kylegach mentioned this pull request Nov 11, 2021
Merged
kylegach and others added 2 commits November 11, 2021 09:14
@kylegach @domyen
Add VersionSelector
327a37f 
- Generate structured list of versions
    - Place on pageContext
- Extend `buildPathWithFramework` to use a provided version instead of always using the current version
- Refactor FrameworkSelector
    - To have a similar API
- Adjust styles & layout

Co-authored-by: domyen <dom@hichroma.com>
@kylegach @domyen
Add VersionCTA
2d90598 
- Render on docs pages when not viewing latest

Co-authored-by: domyen <dom@hichroma.com>
kylegach and others added 7 commits November 11, 2021 09:14
@kylegach @winkerVSbecks
Update headers, redirects, and others
03cc708 
- Hide non-latest docs from search engines
- Only build sitemap for latest version
- Prevent addons pages from being built when not on latest version
- Add redirects for versioned URLs
- Add redirects from `/docs/next/*` to `/docs/6.4/*`
    - Where `6.4` is whatever the "next" version is
- Move built files to appropriate location when not on latest version
- Make AddonsDetailsScreen resilient to bad data
- Add more robust error handing to createAddonsPages

Co-authored-by: winkerVSbecks <varunvachhar@gmail.com>
@kylegach
Add "Publishing new versions" to README
80d8276 
- Add docs/versioning.md to explain steps and how it works
@kylegach
WIP: README
40733bd
@kylegach
Add workflow to push release branches
3bcc1d1 
- On push to master
@kylegach @winkerVSbecks
Add assetPrefix
b5785ee 
- Set to release branch URL when not on latest
- Update CSP to allow release branch URL origin
- Update build & serve commands to enable prefix
- Remove `move-built-files` script

Co-authored-by: Varun Vachhar <varunvachhar@gmail.com>
@kylegach
Fix redirects
f016278 
- Ensure redirects don't include current version
- Change "next" redirect to a permanent proxy rewrite
@kylegach
Prevent CircleCI from running on release-x-x
f7624e0
@kylegach kylegach merged commit 66f7be5 into master Nov 11, 2021
@kylegach kylegach deleted the docs-versioning-3 branch November 11, 2021 16:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@winkerVSbecks winkerVSbecks winkerVSbecks left review comments

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
2 participants
@kylegach @winkerVSbecks