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

feat: cut 8.0 version (and default to it); expose "next" version #1118

Merged
merged 2 commits into from Aug 9, 2022

Conversation

pepopowitz
Copy link
Collaborator

@pepopowitz pepopowitz commented Aug 3, 2022

Addresses #1115

What

This PR:

  1. Cuts a new 8.0 version
  2. Configures docusaurus to use 8.0 as the default version
  3. Exposes a "next" version

The vast majority of changes in this PR are to cut the 8.0 version -- this process clones the entire set of docs into a new versioned folder. The only exception is visible in 6772e2b -- it configures docusaurus to use a Next version, and default to 8.0 as the current version.

Why

This gives us the ability to iterate on docs for upcoming releases and content restructuring efforts. Rather than being forced to do them in a long-lived branch, we can do them in main, as part of the “next” version.

More specifically, it sets us up to iterate toward giving the Optimize documentation its own set of versions, as described in #1116.

How does this impact users?

  1. When viewing the docs for the current version, they'll see an 8.0 selected in the version selector, instead of latest. This will remain the default version when they come to docs.camunda.io.
  2. They'll be able to view a set of docs for the Next version, which they hadn't been able to do before.

What does it look like?

Default version

By default, browsing to docs.camunda.io will serve the user the 8.0 docs. The URLs will look the same as they currently do for the latest version in production -- absent of a version (e.g. /docs/guides/). Because of this, we do not need to add any redirect rules.

The docs they're viewing for 8.0 will be sourced from the /versioned_docs/version-8.0 source folder.

image

Next version

If the user selects Next from the version dropdown, they'll browse the next set of docs. Their URL will include the /next/ version. The docs they're viewing will be sourced from the /docs source folder.

image

How does this impact content authors?

  1. Updates to docs for our current release (8.0) will take place in the /versioned_docs/version-8.0 source folder, instead of /docs
  2. Updates to our next release (8.1?) will take place in the /docs source folder. These updates can be merged whenever, rather than waiting for the 8.1 release to take place.
  3. Open PRs may need to be recreated. I will follow up on each currently open PR with guidance on this. I'm willing to assist in whatever work needs to happen, too.

When will this be merged?

Because of the impact of this PR, especially on existing PRs, I don't intend to merge this immediately. I will be following up with all currently open PRs to develop a plan for minimizing merge headaches. If all goes well, early next week (August 8th) I intend to:

  1. re-generate version 8.0 in this PR so that it includes all recently merged changes, then
  2. merge this PR, then
  3. work with authors of open PRs that need to be recreated.

Background

This work is in preparation of giving the Optimize documentation its own set of versions. It is the implementation of Recommendation #2 described in the Optimize Multi-Instance Documentation Proposal.

korthout
korthout previously approved these changes Aug 5, 2022
Copy link
Member

@korthout korthout left a comment

Choose a reason for hiding this comment

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

I think this is a wonderful idea! 💯

👍 I like that we can just work in /docs/ to add changes for the upcoming version
👍 I like that we can just merge to main when we have changes for the upcoming version
👍 I like that we don't have to keep a long-lived 'upcoming-release' branch
👍 I like that the upcoming version is labeled as Next (it has my preference over a concrete version like 8.1 🚧, because its more clear to users that this is not yet available)
👍 I like that it only takes 12 removed lines of config to make this work

Keep up the great work @pepopowitz ❤️

@pepopowitz pepopowitz marked this pull request as ready for review August 8, 2022 13:53
@pepopowitz
Copy link
Collaborator Author

I don't like to do this, but I'm bypassing branch protection to get this merged without an approval -- it was approved before I regenerated the 8.0 version, and I don't want to delay this merge another day (and risk a new batch of PRs in conflict).

@pepopowitz pepopowitz enabled auto-merge (squash) August 9, 2022 20:59
@pepopowitz pepopowitz merged commit 09abf98 into main Aug 9, 2022
@pepopowitz pepopowitz deleted the pepopowitz/1115-next-version branch August 9, 2022 20:59
@akeller akeller added component:docs Documentation improvements, including new or updated content dx Documentation infrastructure typically handled by the Camunda DX team labels Aug 11, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
component:docs Documentation improvements, including new or updated content dx Documentation infrastructure typically handled by the Camunda DX team epic:optimize-versions
Projects
Status: ✅ Done
Development

Successfully merging this pull request may close these issues.

None yet

3 participants