Update site with versioned release information

[zr-msft]

Related to #341

Docs site needs to show versioned content starting with release 1.1.0.

High-level tasks:

• Branching strategy
• "System Release" doc that shows versions of subprojects for a Notary Project release
• How versioned content is accessed (e.g. urls, redirects, UI elements, etc)
• Removing unsupported content
• Localization strategy

We can record decisions and discussions in this issue and link out to any PRs/Issues implementing those decisions.

[github-actions[bot]]

This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 30 days.

[github-actions[bot]]

This issue was closed because it has been stalled for 30 days with no activity.

[FeynmanZhou]

We still need to support version control on the documentation site.

[FeynmanZhou]

Reference: https://www.docsy.dev/docs/adding-content/versioning/

[FeynmanZhou]

A versioned website ensures the link will not be changed or broken in the future. Inspired by Kubeflow website versioning strategy, I want to propose the version control strategy for notaryproject.dev as follows.

The versioned website follows these conventions:

1. Only apply the version control to documentation. Other pages still point to notaryproject.dev/xxx. Provide a drop-down list to switch versions of docs

2. The documentation versioning aligns with the Notation CLI version, because most of the documentation content are related to CLI and Notary Project is generic brand that doesn't have a system versioning strategy.

3. Use different branch and sub-domains to support version control:

• notaryproject.dev always points to the current main branch, which is the dev branch for next release
• vX-Y.notaryproject.dev points to the stable release, for example, https://v1-1.notaryproject.dev/ points to v1.1 website. Provides a version drop-down list

In addition, the Kubernetes website version control adopts the similar strategy but the only difference is their main branch points to the latest stable release uses a non-versioned link, for example, Kubernetes v1.29 is hosted at https://kubernetes.io/docs/home/. The pros is that the stable release uses a short URL which looks much pretty, but the cons is that broken links may happen in the future if they don't use a versioned link for the stable release.

So I prefer the version control strategy of Kubeflow because all stable releases uses versioned links. Any thoughts and suggestions are welcome. Thanks

[whalelines]

It seems odd to me to have the "notaryproject" documentation site versioned via the notation CLI version since the Notary Project contains more than just the notation CLI, but perhaps this is more a product of the fact that the Notary project documentation site is mostly just a notation CLI project site. Ideally, the Notary project documentation site would contain appropriate documentation for all Notary Project products, notation CLI, notary CLI (deprecated), various specs (currently the docs site just points to specs on GitHub), and various other tooling, e.g., GitHub Action, golang libraries (at least pointers to the godoc pages), etc. The the site could be organized like https://notaryproject.dev/docs/PRODUCT/VERSION/. But perhaps that is too big an undertaking for the current task. Nonetheless, it is worth noting that the current proposal of creating a subdomain per version of the notation CLI precludes such a reorganization in the future, at least without undertaking another restructuring of the site.

[toddysm]

@whalelines idea to have https://notaryproject.dev/docs/PRODUCT/VERSION/ is very good and I remember we discussed this in a few meetings last summer. The problem we hit was with fexibility of the hosting and whether this structure will be possible and whether we can do it from the mono-repo for the site right now. It will be much better experience if we have this one, of course.

At a min, we should link to the place where other docs can be found on the docs home page. As a compromise, we may want to go with the current proposal for this version of the CLI and rethink the whole docs structure for the next.

[github-actions[bot]]

This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 30 days.

[github-actions[bot]]

This issue was closed because it has been stalled for 30 days with no activity.