Library versioning

[mattrosno]

Summary

What problem (or opportunity) are we solving? Why are we solving it? Is there supporting user
conversations or research?

A library in the Carbon Platform is an indexed repository, or repository subdirectory, that contains indexed assets. As such, a library is versioned through its containing repository. This can happen at the git branch, git tag, and git commit hash level.

There is additional complexity when the library has releases that are published to npm, where the version numbers coincide with release names.

By default, the catalogs "index" the latest version of libraries and their assets, but there are additional needs to view library and asset documentation at any version.

This will become increasingly important when local systems curate their catalogs and collections to "pin" specific versions of libraries and assets, so they can easily view version-correct documentation for what they are using in development.

This epic details what it will take to support library versioning.

Job stories

What value will this deliver?

1. When referencing library documentation for what we're building with, I want to view the exact version of the documentation regardless of what's the latest documentation so we don't lose valuable documentation if we aren't using the latest code package version. carbon-job-stories#5
2. When designing a page, I want to design with a component that has the same visuals and capabilities as the version of the component available in the code package, so my development team doesn't have to extend or override the code package. carbon-job-stories#43
3. When using an asset, I want to reference its full public API alongside its usage and design documentation so I don't reference incompatible usage/design and code versions. carbon-job-stories#37

Acceptance criteria

What requirements must be met to complete this request?

1. We figure out how to determine valid versions, and resolve the discrepency between repository version and package version (how they are often different in monorepos)
2. Design a library version switcher (dropdown used to view most ~8 recent versions, or only major versions, etc.)
3. Design a library versions page to view a table with all available versions (very large data set)
4. Canonical links are added to non-default versions of library and asset detail pages
5. Add "last published" date to npm resource cards