search

carbon-design-system / carbon-platform

The "next" version of the Carbon Design System website, as a platform.
https://next.carbondesignsystem.com
Apache License 2.0
21 stars 5 forks source link

Determine library version prefetching strategy #678

Open mattrosno opened 2 years ago

mattrosno commented 2 years ago

Each library will likely have a version dropdown or table. Selecting a version will keep you on-site to view the library at that point in time.

We get library (and its asset) data by querying for GitHub content at a ref which can be the name of the commit, a branch, or a tag. The default ref if not specified is the repository's default branch.

For a library to show up in the web application, the library at that ref needs valid carbon.yml files so we can index it. The question then becomes: how do we know which versions to include in the dropdown or table?

There are some UX and content issues to figure out:

There are also some GitHub API questions:

If the version switcher (dropdown or table) shows valid versions that you can switch to, we'll likely need scheduled job that on a timer:

  1. Finds all release tags for a library: https://docs.github.com/en/rest/releases/releases#get-a-release-by-tag-name
  2. If a tag hasn't been index yet, try to fetch it
  3. If the fetch is successful (has valid carbon.yml files), the library now exists in our caching layers and can then be queried and included in the version switcher

This issue is to determine the version prefetching capabilities. Once this is known, we can determine design considerations prior to implementing in the client.

mattrosno commented 2 years ago

Should we show pre-released data (e.g. default branch)? Or only data coming from tagged releases?

If we show pre-release data, should the version in the dashboard say "Latest"?

mattrosno commented 2 years ago

This issue was discussed in this Slack thread: https://ibm-studios.slack.com/archives/GSCEH4RSP/p1667501190174149

Per the release radar, releases are published every two weeks: https://github.com/carbon-design-system/carbon/wiki/Release-radar

The system squad doesn't create the tags until the release.

Since we're indexing main branch, there can be up to a two week window where content could get off. For example, let's say main branch has updated a demoLink in the carbon.yml metadata time. But, that demo link isn't valid until the next release is published and Storybook is deployed.

In that scenario, we wouldn't want main to be indexed by default; we'd want the default indexed version to be what's deployed to Storybook. Ideally, that version should also be the latest tag in npm: https://www.npmjs.com/package/@carbon/react

Right now, our URL strategy uses latest to map to the the repository's default branch (e.g. main or master.)

https://next.carbondesignsystem.com/libraries/carbon-react/latest

Instead, we might need to update our logic so latest maps to the latest npm tag. In that example, even through the URL says latest, it renders this parameter:

https://next.carbondesignsystem.com/libraries/carbon-react/v11.17.0

(This assumes the fix for https://github.com/carbon-design-system/carbon-platform/issues/915 is in, so the URL used is for the repository v11.17.0, which includes the latest version v1.17.0 for the @carbon/react package.)

image