Versioned Docs

versioned_docs.md

Versioned Documentation for Storybook

Goals:

• Docs for the latest stable release of Storybook, statically hosted at https://storybook.js.org
• Docs for a preview release, clearly labeled as preview with disclaimers and pointers to the main docs
• Docs for previous minor releases of Storybook, with disclaimers and pointers to the main docs

Proposal

Patterned off of Meteor docs site (source)

1. A config file (package.json?) that lists out the versions, and also the current stable version
   • Code that reads this in and creates a drop-down
2. A naming convention on release branches release/X.y
3. A CI setup that:
   • deploys the branch to /vX.y/ if the change is to a release/X.y branch
   • deploys to / if it's on master
4. Code that displays a warning banner if the user is not viewing the current stable version

The biggest downside of this approach is that the old versions don't have links to all the new versions, unless you update all branches on release (like this commit I suspect they have a script to do this).

Happy to help do this, considering I was the one that set it up for Meteor. The only bit I'm not sure about is step 1--for the Hexo docs that info is in the config file for Hexo (see commit linked above). @shilman you'd have the best idea of how to do it for Gatsby.

The cool thing about doing this is we can ask PRs to new versions to include docs, and it will just work right? Monorepo++

You all are moving fast. It would be nice (on the readme.md at statement about upgrading. I have had a fair share of problems with configuring and installing storybook. Now that I have it working. I am afraid to upgrade the cli. Fortunately, Im only using storybook on a ui test app. I found it easier reinstall storybook, start a new project, then copy over the stories. It looks like you are posting new releases ever few days. The version I have works fine. I'd like to keep up with the changes. After more than a year, I've finally gotten storybook to work for me. THANKS!

@tmeasday I don't think the pointer to the latest documentation is a problem?

• latest version resides at both / and at /vX.y (not google-indexed)
• all versions at /vX.y point to latest at /

Re: Gatsby, I think @ndelangen is in the process of converting us to NextJS.

@smooJitter most of the releases we're doing are just minor bugfixes, and we're trying to limit breaking changes to 1-2x / year with major releases (3.0.0, 4.0.0, etc.). AFAIK we have documented all necessary migrations in MIGRATION.md. But we'll try to do a better job of documenting it all. Thanks!