Document desired process for managing publication of spec revisions

[tdcox]

As part of the cdevents.dev refresh, we need to document the desired process for managing publication of spec revisions.

This has two main drivers:

1. We need to understand the release process well enough to identify any issues that might arise that would shape the requirements for the website itself.

2. We should publish the process itself on the website, both for transparency, and to ensure that it is easy to repeat the process consistently and reliably over time, with new contributors.

This requires a conversation over the next 1-2 weeks to ensure that we have enough information to support the completion of the website refresh.

[tdcox]

The current specification is mapped as a submodule under content/en/docs/ and is checked every night for changes using a GitHub Action in this repo.

Advantages:

• The website always has the latest version of the spec, automatically

Disadvantages:

• The website does not permit viewing of historical versions of the spec.
• There is no provision to permit translated instances of a version of the spec to be published
• Nightly polling makes it hard to see when spec changes have been published
• Updates relate to commits rather than tags, so it's hard to establish which spec version is current

[tdcox]

Comparing to other related Hugo-based documentation sources that the consumers of our information will be familiar with, there are two extremes:

Kubernetes documentation is structured by namespacing the entire domain, such that a reader is redirected to a static site instance containing all content for a historical version of the platform. An alert pane is injected into every page, warning that the information is out of date and indicating the version it applies to. The default site refers to the current version and is not explicitly namespaced with that version number.

CloudEvents documentation completely avoids the problem by redirecting the reader to the GitHub repo containing all the specification content.

Sitting in between, Jenkins-X implements a namespaced URL path with a dropdown top menu item to select the version. All content is authored directly in the site repo and version management is a manual process.

[e-backmark-ericsson]

I'd like to see a solution where a dropdown menu would let you select an earlier supported version. It would be fine to me if that option was just available in the actual spec documentation part of the site, and not on the top pages. The top pages could assume that latest version of the spec is used, if we include any spec version specific content there.

I think we should re-render the whole site, including historical versions, each time we do a release of the spec. We shouldn't need to do it every night. We should not need to include all historical versions, but just the supported ones, so I believe we would never render more than 3-4 versions.

I'm not sure about the namespacing through a url path or parameter containing the version number, since that could mean that people create hard links to our website containing version numbers, and those will not work when that version is out of support. I believe the website could be default always show the latest version, and you'd need to actively select an older version in the dropdown to see it. It could be stored in a cookie so that it is not reset every time you access the page.

[tdcox]

We should be mindful that any solution needs to remain Docsy-compatible as much as possible, to avoid incurring an ongoing maintenance overhead for custom extensions. Menu construction is synthesised, out of the box, so it would be best to seek a structure that allows us to leverage this rather than require explicit customisation.

Ideally, we shouldn’t need to explicitly render the site - the Netlify release process does this for you when you merge changes. There is the issue of keeping sub modules synchronised appropriately.

The most straightforward solution is probably to have a default namespace that references the latest tagged version of the specification as an embedded module, then provide a menu to redirect to the spec github repo for historical versions. That would mean that the website would always have valid links and would eliminate all the ongoing overhead of trying to reconcile history in the website.

Ideally, the preview and release builds should automatically sync the submodule, rather than requiring a nightly build.

How does this look?

[afrittoli]

I'd like to see a solution where a dropdown menu would let you select an earlier supported version. It would be fine to me if that option was just available in the actual spec documentation part of the site, and not on the top pages. The top pages could assume that latest version of the spec is used, if we include any spec version specific content there.

I think we should re-render the whole site, including historical versions, each time we do a release of the spec.

Well, at least when a new latest release is made, we need to switch what the unversioned URL points to.

We shouldn't need to do it every night.

It depends if we want to render main on top of released versions or not.
In any case the unversioned URLs should point to the latest release, so main would be an extra item in the dropdown to pick from, if we decide to have it.

We should not need to include all historical versions, but just the supported ones, so I believe we would never render more than 3-4 versions.

It would probably make sense to only include the latest patch version for each major.minor. We still need to define when a version is EOL, but in any case which versions we display should be configurable and independent of this decision.

I'm not sure about the namespacing through a url path or parameter containing the version number, since that could mean that people create hard links to our website containing version numbers, and those will not work when that version is out of support.

I don't see the problem with that. If people want to hard link to v0.1 of the spec, once that version is EOL it's fine if the spec is not there anymore. We can leave a redirect in place to show the latest version instead with a warning message.

I believe the website could be default always show the latest version, and you'd need to actively select an older version in the dropdown to see it. It could be stored in a cookie so that it is not reset every time you access the page.

There's no need to client-side cookies for this solution - that's supported out of the box by docsy.

[tdcox]

I think we need an explicit decision as to whether main should be treated as the latest released version or not. If we follow that approach, you can rely upon the automated Netlify release process, which is what we do with Best Practices, but if you require a more complex release process for the spec, then it should be based upon tags rather than main.

[afrittoli]

We should be mindful that any solution needs to remain Docsy-compatible as much as possible, to avoid incurring an ongoing maintenance overhead for custom extensions. Menu construction is synthesised, out of the box, so it would be best to seek a structure that allows us to leverage this rather than require explicit customisation.

+1

Ideally, we shouldn’t need to explicitly render the site - the Netlify release process does this for you when you merge changes. There is the issue of keeping sub modules synchronised appropriately.

The approach we use in Tekton is to sync different branches of the source docs to different folders, and use the version switch to point to different paths in the content. That requires however custom sync code and custom docsy code, so I would prefer to avoid if possible.

The approach supported by docsy out of the box is to have different versions in the dropbox be configured to different URLs, like v1.cdevents.dev and v2.cdevents.dev. Those URLs could be achieved by using branches on the website repo and configuring branch builds in Netlify. The content submodule could point to the corresponding tag on the spec repo side:

• https://draft.cdevents.dev -- is rendered from --> cdevents.dev@main -- submodule points to -- > spec@main
• https://v0.1.0.cdevents.dev -- is rendered from --> cdevents.dev@release-v0.1.0 -- submodule points to -- > spec@v0.1.0
• https://v0.2.0.cdevents.dev -- is rendered from --> cdevents.dev@release-v0.2.0 -- submodule points to -- > spec@v0.2.0
• https://cdevents.dev -- is rendered from --> cdevents.dev@release-v0.2.0 -- submodule points to -- > spec@v0.2.0

The problem with this approach though is the non-versioned part of the website - how to keep it consistent across versions?
I would be interested in learning how k8s or knative do that - we can probably replicate the same.

The most straightforward solution is probably to have a default namespace that references the latest tagged version of the specification as an embedded module, then provide a menu to redirect to the spec github repo for historical versions. That would mean that the website would always have valid links and would eliminate all the ongoing overhead of trying to reconcile history in the website.

I think as long as we have only one supported minor version at the time it makes sense.
I can imagine that in future when we do new minor/major versions, we may still have to support older versions, in which case it would be nice to have many versions rendered. Supporting multiple versions could also be a future improvement on the website, it doesn't have to be available right away

Ideally, the preview and release builds should automatically sync the submodule, rather than requiring a nightly build.

We can certainly link the website build to the release - the only issue with this kind of automation is that, when it fails, it will leave the website out of sync. Nightly sync make sure that the website is in sync.

How does this look?

[afrittoli]

I think we need an explicit decision as to whether main should be treated as the latest released version or not. If we follow that approach, you can rely upon the automated Netlify release process, which is what we do with Best Practices, but if you require a more complex release process for the spec, then it should be based upon tags rather than main.

main of the spec repo is always a draft.
main of the website repo could be the live website - I guess it depends on what we decide about displaying multiple versions.

[e-backmark-ericsson]

I was mostly dreaming on how I would like it to be. I could be fine with just having the current/latest version rendered on the website. I would like it to show somehow what version it represents though. Best would probably be if that could be read from the "highest" tag released in the spec repo, but that might not be possible with docsy/netlify

If we could have multiple versions of the spec statically included on the website it would be a plus. What versions to include should in that case be based on a hardcoded list of supported releases I believe. If the web framework can handle non-existing urls the way you describe @afrittoli , by redirecting to some default (latest) version, then it is of course fine to have url parameters distinguishing different versions.

I totally agree that we shouldn't make any fork of Docsy or a lot of specific addons. I don't know the limitations of Docsy/Netlify at all, so I'm just dreaming :)

I expect that a release in the spec repo could directly trigger a rebuild, or maybe an automated PR/commit in the cdevents.dev repo which would rebuild the site.

We can certainly link the website build to the release - the only issue with this kind of automation is that, when it fails, it will leave the website out of sync. Nightly sync make sure that the website is in sync.

Well, the nightly builds could fail, and then we manually need to rebuild them once that happens. If it was part of the automated release process we could just verify that the rebuild worked and then it won't get touched until next release.

[tdcox]

The K8S approach of using versioned domains is the tidiest solution. They use a default domain for ‘latest’ and only version supported, historical snapshots. For us, that would mean cdevents.dev always pointing to the latest release and then v1.cdevents.dev, v2.cdevents.dev etc being created as new versions are released.

From a practical standpoint, we only have pre-release versions and until such time as we introduce a breaking change post-v1 there is no immediate urgency to implement versions on the site. If we choose the K8S approach, we can implement the default path behaviour in this piece of work and that will be compatible with the future versioning requirement. When that instance arises, we can branch the website as suggested and expose the branch as the historic snapshot on an appropriate subdomain.

The act of publishing a new version really just consists of refreshing the git submodule in the cdevents.dev repo to point to the new tagged commit on the spec repo. Ideally, this would be a PR, triggered by the tagging action on the spec repo. The PR would allow you to review the change on the website preview before merging.

If only we had some standard for communicating delivery events to build processes…

[e-backmark-ericsson]

I wouldn't bet too much on that we will not have backwards incompatibilities between some of our coming pre-1.0 minor releases, so I think we should have the revision routines of the docs set up already now. We might release 0.2 before xmas and then I'd like to see that we can choose between v0.2 (default) and v0.1, and also a "draft" for changes after v0.2.

If only we had some standard for communicating delivery events to build processes…

:) I'd vote for trying out CDEvents for this sooner rather than later, but we'd need some infrastructure to deploy it on until GitHub provides native support for it...

[tdcox]

My recommendation would be to build your versioning scheme to align to your semantic versioning scheme.

Pre-v1.0.0 releases are expected to change rapidly and to be unsupported. You actively want to discourage adopters from lagging behind the development edge on these version as there will likely be significant issues in prior point releases. The v1.0.0 release is the first supported asset stream that should have a history over a pre-defined length of time, and you generally want to treat that supported version as the latest point release in the v1.x.x stream. Under this scheme, you don’t need a supported history facility to be actually working until v2.0.0 releases.

[e-backmark-ericsson]

Ok. I agree. For developers that want to see a specific pre-v1.0 spec version they could visit the spec repo itself and select the appropriate tag. We don't need to overdo the cdevents.dev docs rendering just because of the pre-v1.0 stage.

[tdcox]

Documentation Versioning has been added to the site with #22

There is now a Releases drop-down on the main menu, which allows you to select prior versions of the specification.

A version indicator has been added to the root of the breadcrumb trail, so you can see which version the displayed docs relate to.

The process to make a new release is currently as follows:

1. In Specification GitHub repo, merge changes to spec and tag a numbered release.
2. In cdevents.dev repo, sync docs git submodule with tagged release of spec repo.
3. In cdevents.dev repo, edit config.toml file. In the [params] section, update version variable to match tagged version. Edit [[params.versions]] section to add link to historical docs.
4. Merge and publish changes to cdevents.dev

Note that prior to a formal, semantic v1.0.0 release, historical links point to the associated tagged version of the spec repo.

From release v2.0.0 onward, the following revised process should be used:

Between steps 1 and 2, cdevents.dev should be branched to create a clone of the current release docs, prior to the new release. In the netlify config, set this branch to deploy to 'v1.cdevent.dev' (or other appropriate historical version number). In config.toml file, in the [params] section, edit archived_version to be true.

The first time this is done, you will need to edit the [[params.versions]] section to redirect the historical link to 'v1.cdevent.dev' version of the site instead of the spec repo tag, as currently.