Docs versioning #298

kylegach · 2021-10-06T16:44:03Z

Description

Add versioning to Storybook docs.

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

Note: This first attempt at the feature will only support a single "next" version. Once we decide on a convention for multiple "next" versions in the monorepo, I can extend the code here to support those, too (in a future PR).

Screenshot

Note: The messaging in the callout above the content is subject to change.

How to Test

Check Chromatic tests
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
Run the site locally with a reference branch specified (BRANCH=next yarn start, same for build)
- Ensure the correct version of docs is built and you can navigate fully
  - Keep in mind the redirects won't work
Ensure that yarn extract-monorepo-docs and yarn link-monorepo-docs still work, with their various arguments
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
Create release-6-0, release-6-1, and release-6-2 branches from their release/*.* counterparts in monorepo

After merging...

Create branches in this repo
- release-6-0, release-6-1, release-6-2
Add branches to Netlify build settings

- Makes for easier comparisons to other versions

- Get version from mapping of current branch to SB monorepo branch - Add current version to FrameworkSelector

src/util/create-addons-pages.js

domyen · 2021-10-12T16:14:31Z

@domyen to design a banner to point to the latest version

gatsby-config.js

kylegach · 2021-10-15T15:16:55Z

gatsby-node.js

 }

+let versions;


I need access to this inside onPostBuild, but it's created with data that (I think) is only available inside createPages. So mutating the value is how I share it across closures. Have a better idea?

kylegach · 2021-10-15T15:19:06Z

gatsby-node.js

+const { BRANCH } = process.env;
+let versionFromBranch;
+const nextVersion = shortenVersion(nextVersionFull);
+const NEXT_BRANCH = 'next';


I tried to build this in a way that could (eventually) support more than one "next" version. But because we need all available versions ahead of time, we need to know which branches from which to grab those versions, so the 'next' portion has to be hard-coded. Supporting, e.g. 'next-minor' & 'next-major' will require refactoring.

kylegach · 2021-10-15T15:42:57Z

scripts/extract-next-monorepo-version.sh

@@ -0,0 +1,14 @@
+#!/bin/bash -


If there's a better way to do this, I'm all ears.

I noticed https://github.com/storybookjs/storybook/blob/next/docs/versions/next.json, but when we're extracting docs from the main branch, the version is incorrect (for our usage, at least): https://github.com/storybookjs/storybook/blob/main/docs/versions/next.json.

kylegach · 2021-10-15T15:44:52Z

site-metadata.js

@@ -18,7 +18,8 @@ const siteMetadata = {
  ogImageAddons: '/images/social/og-addons.png',
  siteUrl: homepageUrl, // Used for gatsby-plugin-sitemap
  googleSiteVerification: '_OxxMv1o0aRcxPfieLW0BRsMxxIzkpA9Vv6O0AB5xg0',
-  latestVersion: 'v6.3',
+  latestVersion: '6.3', // TODO: Could get this from monorepo...


Not sure if that's worth another curl (assuming there's not a better way), but pulling this from the monorepo would remove a step from the process to document another version.

kylegach · 2021-10-15T15:54:25Z

@domyen to design a banner to point to the latest version

@domyen — This is nearly the only thing remaining. Remember that the header changes coming with the Component Catalog work will likely affect the placement.

Even a rough sketch just demonstrating visual placement would be helpful for me to get started. Thanks!

- Build versions list from filtered releases edges

- Preserve relative links

Broken: - Breaks on branch names like "release/6.2" - SB monorepo convention - BRANCH is a Netlify convention - Ensure branch names other than "next" and "release/*" extract docs from monorepo's main branch - Can also use locally

- https://developers.google.com/search/docs/advanced/crawling/block-indexing#http-response-header

- Was `release/6.2`, which caused character escaping problems

- Store in `context.versions`

- "Stable" and "Pre-release"

src/components/screens/DocsScreen/VersionCTA.tsx

domyen · 2021-10-20T17:14:26Z

Can we re-order the versions so that the latest appears as the top?

Current:

6.0
6.1
6.2

Proposed:

6.2
6.1.
6.0

kylegach · 2021-10-20T17:18:09Z

Can we re-order the versions so that the latest appears as the top?

Current:
* 6.0

* 6.1

* 6.2
Proposed:
* 6.2

* 6.1.

* 6.0

Yep. That makes sense now that we have a separate section for pre-release(s). 👍

src/components/screens/DocsScreen/VersionSelector.tsx

winkerVSbecks

LGTM the only open issue for me is regarding SB version in the header.

winkerVSbecks · 2021-10-20T19:06:29Z

site-metadata.js

@@ -18,7 +18,8 @@ const siteMetadata = {
  ogImageAddons: '/images/social/og-addons.png',
  siteUrl: homepageUrl, // Used for gatsby-plugin-sitemap
  googleSiteVerification: '_OxxMv1o0aRcxPfieLW0BRsMxxIzkpA9Vv6O0AB5xg0',
-  latestVersion: 'v6.3',
+  latestVersion: 6.3, // TODO: Could get this from monorepo...


We use this latestVersion in the header for frontpage, blog and tutorials. Like so:

It looks like we don't do that on frontpage any more. Should the other sites be updated to match this? cc: @domyen

We actually grab the version from this file in the blog and tutorials repo.

Oof. Had no idea other repos were referencing this property.

gatsby-node.js

winkerVSbecks · 2021-10-20T20:17:13Z

@domyen @kylegach I'm a little concerned that I haven't been able to green build after 5 tries. Doing that for every branch after rebasing is going to be a major concern.

Should we split the addon catalog into its own repo along with this change? That's where the instability comes from.

winkerVSbecks · 2021-10-20T20:54:53Z

There was actually a bug, pushed a fix for it.

kylegach · 2021-10-20T21:23:13Z

There was actually a bug, pushed a fix for it.

@winkerVSbecks — 🤦‍♂️ Thank you!

- Use pre-release label instead of "New" in VersionCTA badge - Reword messages in VersionCTA - Sort-by-newest in VersionSelector - Remove VersionSelectorTitle styled component - Move versions list generation into `buildVersions` - Refactor shape of versions list

kylegach · 2021-10-21T03:23:41Z

All comments addressed except for the use of latestVersion in other repos (#298 (comment)). If someone can provide me a list of places to check, I can look into that. When I search our GitHub org for "latestVersion" or "site-metadata", I only see results in this repo and in the monorepo.

winkerVSbecks · 2021-10-21T13:51:35Z

@kylegach these ones:

kylegach · 2021-10-21T14:27:17Z

Should we split the addon catalog into its own repo along with this change? That's where the instability comes from.

As I understand it, the primary reason this wasn't done initially was shared components between Addon Catalog and the rest of frontpage. We'll be pulling those components into the design system, so that we can use them for https://github.com/storybookjs/component-catalog. At which point, extracting Addon Catalog into its own repo should be relatively straightforward.

- storybookjs/frontpage#298 updates `latestVersion` to be a number - As this project pulls the value from that one, it needs to support either format (at least temporarily)

kylegach · 2021-10-22T03:46:11Z

@kylegach these ones:

* https://github.com/chromaui/blog

* https://github.com/chromaui/learnstorybook.com

I created PRs in each to ~~support either latestVersion format~~ remove latestVersion from their Headers:

@domyen — We only removed the latest version from the Header of frontpage because it was redundant with the selector in the sidebar. So I kept it in the other projects, which don't have the selector. Let me know if that's the correct choice.

- Because: storybookjs/frontpage#298

kylegach added 3 commits October 6, 2021 10:43

Remove version from Header

711756e

Remove "v" prefix from latestVersion

12004f0

- Makes for easier comparisons to other versions

Add current version to TOC paths

e6743e5

- Get version from mapping of current branch to SB monorepo branch - Add current version to FrameworkSelector

kylegach force-pushed the docs-versioning branch from 525965e to e94eb2d Compare October 8, 2021 06:40

kylegach changed the title ~~[WIP] Remove version from Header~~ [WIP] Docs versioning Oct 8, 2021

kylegach force-pushed the docs-versioning branch 2 times, most recently from ed97294 to 83d065c Compare October 8, 2021 15:52

kylegach commented Oct 8, 2021

View reviewed changes

src/util/create-addons-pages.js Outdated Show resolved Hide resolved

kylegach commented Oct 8, 2021

View reviewed changes

src/util/create-addons-pages.js Outdated Show resolved Hide resolved

kylegach commented Oct 12, 2021

View reviewed changes

gatsby-config.js Show resolved Hide resolved

kylegach force-pushed the docs-versioning branch 2 times, most recently from e720a86 to 09c591b Compare October 15, 2021 12:58

kylegach commented Oct 15, 2021

View reviewed changes

kylegach added 12 commits October 15, 2021 09:59

Add VersionSelector

6d901d6

- Build versions list from filtered releases edges

Add current version to URL

b4bc38a

- Preserve relative links

WIP: Extract relevant docs based on BRANCH env

dd10a85

Broken: - Breaks on branch names like "release/6.2" - SB monorepo convention - BRANCH is a Netlify convention - Ensure branch names other than "next" and "release/*" extract docs from monorepo's main branch - Can also use locally

Attempt to fix broken Netlify build

ac0c0ff

Only build addons when referencing latest version

b8aa948

Hide non-latest docs from search engines

38220ea

- https://developers.google.com/search/docs/advanced/crawling/block-indexing#http-response-header

Add more robust error handing to createAddonsPages

4b5c3ef

Correct canonical URL

d8e883f

Update to expect branch convention release-6-2

526faae

- Was `release/6.2`, which caused character escaping problems

Pull next monorepo version from package.json

7b2d36e

- Store in `context.versions`

Refactor VersionSelector to use sections

b0801d8

- "Stable" and "Pre-release"

Remove version from latest docs URL

ed14fa3

kylegach marked this pull request as ready for review October 20, 2021 14:46

kylegach requested review from winkerVSbecks, shilman and domyen October 20, 2021 14:46

kylegach changed the title ~~[WIP] Docs versioning~~ Docs versioning Oct 20, 2021

domyen reviewed Oct 20, 2021

View reviewed changes

src/components/screens/DocsScreen/VersionCTA.tsx Outdated Show resolved Hide resolved

domyen added 2 commits October 20, 2021 13:11

Add emoji to DocsLayout stories just like the real site

64da23d

Tweak styling on Framework and Version selector

669bba4

domyen reviewed Oct 20, 2021

View reviewed changes

src/components/screens/DocsScreen/VersionSelector.tsx Outdated Show resolved Hide resolved

winkerVSbecks approved these changes Oct 20, 2021

View reviewed changes

fix error checking logic for create-addons-pages

f02b088

Address comments

fac2c5a

- Use pre-release label instead of "New" in VersionCTA badge - Reword messages in VersionCTA - Sort-by-newest in VersionSelector - Remove VersionSelectorTitle styled component - Move versions list generation into `buildVersions` - Refactor shape of versions list

kylegach mentioned this pull request Oct 22, 2021

Remove latestVersion from Header chromaui/learnstorybook.com#541

Merged

kylegach added a commit to chromaui/learnstorybook.com that referenced this pull request Oct 25, 2021

Remove latestVersion from Header

215e3ce

- Because: storybookjs/frontpage#298

kylegach merged commit d5fda3d into master Oct 26, 2021

kylegach deleted the docs-versioning branch October 26, 2021 18:41

kylegach added a commit that referenced this pull request Oct 26, 2021

Revert #298 & 92e38b

8abc52f

This was referenced Oct 28, 2021

Migrate to Emotion #303

Merged

Docs versioning #304

Closed

kylegach mentioned this pull request Nov 4, 2021

Add docs versioning #310

Merged

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs versioning #298

Docs versioning #298

kylegach commented Oct 6, 2021 •

edited

Loading

domyen commented Oct 12, 2021

kylegach Oct 15, 2021

kylegach Oct 15, 2021

kylegach Oct 15, 2021

kylegach Oct 15, 2021

kylegach commented Oct 15, 2021

domyen commented Oct 20, 2021

kylegach commented Oct 20, 2021

winkerVSbecks left a comment

winkerVSbecks Oct 20, 2021

winkerVSbecks Oct 20, 2021

kylegach Oct 20, 2021

winkerVSbecks commented Oct 20, 2021

winkerVSbecks commented Oct 20, 2021

kylegach commented Oct 20, 2021

kylegach commented Oct 21, 2021

winkerVSbecks commented Oct 21, 2021

kylegach commented Oct 21, 2021

kylegach commented Oct 22, 2021 •

edited

Loading

		}

		let versions;

Docs versioning #298

Docs versioning #298

Conversation

kylegach commented Oct 6, 2021 • edited Loading

Description

Screenshot

How to Test

TODO

domyen commented Oct 12, 2021

kylegach Oct 15, 2021

Choose a reason for hiding this comment

kylegach Oct 15, 2021

Choose a reason for hiding this comment

kylegach Oct 15, 2021

Choose a reason for hiding this comment

kylegach Oct 15, 2021

Choose a reason for hiding this comment

kylegach commented Oct 15, 2021

domyen commented Oct 20, 2021

kylegach commented Oct 20, 2021

winkerVSbecks left a comment

Choose a reason for hiding this comment

winkerVSbecks Oct 20, 2021

Choose a reason for hiding this comment

winkerVSbecks Oct 20, 2021

Choose a reason for hiding this comment

kylegach Oct 20, 2021

Choose a reason for hiding this comment

winkerVSbecks commented Oct 20, 2021

winkerVSbecks commented Oct 20, 2021

kylegach commented Oct 20, 2021

kylegach commented Oct 21, 2021

winkerVSbecks commented Oct 21, 2021

kylegach commented Oct 21, 2021

kylegach commented Oct 22, 2021 • edited Loading

kylegach commented Oct 6, 2021 •

edited

Loading

kylegach commented Oct 22, 2021 •

edited

Loading