Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DO NOT MERGE] Prototype: configure two 'next' versions #4894

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

pepopowitz
Copy link
Collaborator

@pepopowitz pepopowitz commented Jan 23, 2025

Description

This PR imagines what it would be like for us to, hypothetically, manage two unreleased versions, instead of one.

Preview site

https://preview.docs.camunda.cloud/pr-4894/index.html

Which version is which?

To avoid confusion, due to how I implemented this PR (see first note in Implementation Notes) to move quickly yet prove a concept, I want to be very clear about how I refer to versions in this PR. And how they relate to the attached preview site, and how they would eventually relate to a future where versions 8.7 and 8.8 are both unreleased yet both in the docs.

When I say this version I am referring to this version in the related preview site And this version when versions 8.7 and 8.8 are both unreleased but documented
"current" 8.5 8.6
"next" 8.6 8.7
"next+1" 8.7 8.8
"unreleased" 8.6 & 8.7 8.7 & 8.8

Implementation notes

  • I did not cut a new version in this PR. Instead, I marked versions 8.6 and 8.7 as "unreleased", and 8.5 as the "current" version. I did this because it was significantly less work than cutting a new version, and enough to prove the concept that we can specify two versions as unreleased beyond the current version. To address the potential confusion from this, I've added a table describing versions above.
  • As a result of this little hack, this PR will not pass CI checks, because the "current" version here doesn't match the current version in production, therefore sitemap URLs are not preserved. Nothing to worry about. (The preview deploy succeeds, because it does not include sitemap validation.)
  • Importantly, the "current" version preserves its versionless URLs. This enables us to ship multiple "unreleased" versions without affecting the default version that a user browsing to would see, for example https://docs.camunda.io/docs/components/. When they visit the versionless URL, they will see the currently released version.
  • This also helps us avoid implementing a bunch of redirects prematurely, for content that relocates in version "next". This also applies to our sitemap.
  • Version "next" is currently configured in this PR to include its version (/8.6). Version "next+1" will include "/next" in its URL path.
  • We have very direct and simple control over the top-nav label and URL path for version "next", via the docusaurus.config.js. This is because it is actually a cut version. In the preview site, I've labelled this version "8.6 (unreleased)", but left its URL path configured to the default of "8.6". We can call both of these things whatever we want, easily.
  • We do not have direct and simple control over the top-nav label or URL path for version "next+1". We can control the top-nav label through a theme component override, as demonstrated in this PR. We cannot control the URL path (/next) without significant updates to Docusaurus itself, which effectively means we cannot control it at all.
  • There are other elements in the preview site that show the text "Next" instead of "8.7 (unreleased)". We probably have the ability to override these in all cases with theme component customizations, similar to the previous bullet point.
  • When we release the next alpha, we will need to cut version "next" through the typical minor version release process, but also adjust docusaurus configuration and components as done in this PR.
  • The presence of two "unreleased" versions will likely cause confusion in the source, which we will need to manage and address early and often. Contributors are used to the docs/ folder containing "next", and versioned_docs/ containing all released versions, including "current." After these changes, contributors will need to adjust to the fact that docs/ contains the source for "next+1", and the "next" version is sourced as a numbered version in versioned_docs/.
  • I have not implemented any of the described changes for the Optimize docs instance, or associated configuration changes for cross-instance linking. This means that linking across instances in the preview site will have unexpected results (I'm not even sure what it will actually do).

Screenshots

When should this change go live?

  • This is a bug fix, security concern, or something that needs urgent release support. (add bug or support label)
  • This is already available but undocumented and should be released within a week. (add available & undocumented label)
  • This is on a specific schedule and the assignee will coordinate a release with the DevEx team. (create draft PR and/or add hold label)
  • This is part of a scheduled alpha or minor. (add alpha or minor label)
  • There is no urgency with this change (add low prio label)
  • It should not go live.

PR Checklist

  • My changes are for the next minor and are in /docs directory (aka /next/).
  • My changes are for an already released minor and are in /versioned_docs directory.

@pepopowitz pepopowitz added hold This issue is parked, do not merge. deploy Stand up a temporary docs site with this PR labels Jan 23, 2025
Comment on lines +5 to +13
if (label === "Next") {
label = "8.7 (unreleased)";
}

items = items.map((item) => {
let { label } = item;
if (label === "Next") {
label = "8.7 (unreleased)";
}
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'd likely make this text a configuration setting, since it will probably be used in additional locations.

@github-actions github-actions bot temporarily deployed to camunda-docs January 23, 2025 23:08 Destroyed
Copy link
Contributor

The preview environment relating to the commit e56dd4a has successfully been deployed. You can access it at https://preview.docs.camunda.cloud/pr-4894/index.html

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
deploy Stand up a temporary docs site with this PR hold This issue is parked, do not merge.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant