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.

Sign up for GitHub

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

archive (1.3) exclude: remove versions 1.3 and 3.7.0, part 1: reviewable steps #2502

Closed
wants to merge 7 commits into from
Closed

archive (1.3) exclude: remove versions 1.3 and 3.7.0, part 1: reviewable steps #2502

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
75a3fe5
archive(1.2) exclude: remove 1.3 and 3.7.0 from the version manifests
pepopowitz Aug 28, 2023
53c27a6
archive(1.2) exclude: redirect 1.3 / 3.7.0 traffic to new website
pepopowitz Aug 28, 2023
7b84279
archive(1.2) exclude: move 1.3 to unsupported versions in navbar, rem…
pepopowitz Aug 28, 2023
128874d
refactor: extract versionMappings to a versions.js file, where we'll …
pepopowitz Aug 29, 2023
225d5d1
refactor: extract unsupportedVersions to versions.js, and use it to g…
pepopowitz Aug 29, 2023
387d3ac
refactor: update isolation scripts to target versionMappings in the n…
pepopowitz Aug 29, 2023
0442e77
docs: update release procedure to account for new versions.js file
pepopowitz Aug 29, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 1 addition & 3 deletions docusaurus.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ module.exports = {
className: "dropdown-unsupported-versions",
value: "<b>Unsupported versions</b>",
},
...["1.2", "1.1", "1.0", "0.26", "0.25"].map((version) => ({
...["1.3", "1.2", "1.1", "1.0", "0.26", "0.25"].map((version) => ({
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

This array turns into the “unsupported versions” in the versions dropdown. It leads to some confusing information when viewing Optimize docs.

We’ve customized the versions dropdown to display different supported versions, depending on if you’re browsing the main docs or Optimize docs. This is done by swizzling a component, and passing metadata to its children based on the current URL.

Unfortunately, the rendering of the static unsupported versions is a lot more simplistic than the rendering of the supported versions. Thus, when I’m viewing an Optimize doc, the static/unsupported versions show the main docs versions, because that’s all that’s configured to show there. Like this:

image

How much effort do we want to put into this?

I am pretty sure I can swizzle one or two components to make that static list toggle between two different sets, depending on which docs instance you’re viewing. But I also wonder if this is necessary. This is somewhere between a “small” and “medium” amount of effort — closer to small, but there is risk that I can’t accomplish it.

I can also think of at least two other solutions that are even smaller, but less correct. Since these are “unsupported” versions, we’ve already made decisions along the way guided by the idea that we don’t care about them as much as supported versions. Maybe they are good enough?

Possible solutions

  1. A more complicated solution, in which we swizzle some components to make the “static list of unsupported versions” toggle based on the doc you’re viewing. This is a "small" to "medium" effort. I am unsure how the pre-Optimize-extraction versions should appear in this dropdown when viewing an Optimize page, if we go this route.
  2. Just let the incorrect unsupported versions display when viewing an optimize doc (0 effort, what you see in my screenshot above).
  3. Similar to the work for the upcoming release, we could display both the main version and the Optimize version in the dropdown, separated by a slash (e.g. 1.3 / 3.7.0). This is a "small" effort. This is what it'd look like:
    image
    If we choose this option, the / 3.7.0 would also show in the unsupported versions when viewing a main docs page.

@akeller is there anything unclear here, and do you have any opinions on which route meets the "good enough" bar?

Copy link
Member

Choose a reason for hiding this comment

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

I agree on spending a small amount of time/effort here. Spending no effort sounds like it will create confusion and may even block people from finding what they need. Ideally it doesn't because people are running one of the 3 supported versions, but we can't ding people for not being on our schedule.

I like your 3rd option, particularly because we have similar upcoming work. Showing in the main docs page feels natural.

Copy link
Collaborator Author

@pepopowitz pepopowitz Aug 29, 2023 •
edited
Loading

Choose a reason for hiding this comment

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

oops, I forgot that the existing code is taking the displayed version number, and appending it to the unsupported.docs.camunda.io URL for the href. So for the "1.3 / 3.7.0" version, it's sending me to https://unsupported.docs.camunda.io/1.3%20/%203.7.0/ - which is not correct 😅

This means I have to do a little bit of work to keep track of both the label and the URL. I still think this is less work than trying to display specific versions on specific pages, but I'll see when i get there.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

My most recent commits address this. Just for clarity (and I'll add this to the body of the PR),

This is what the version dropdown looks like when viewing most docs:

image

This is what the version dropdown looks like when viewing an Optimize doc:

image

label: version,
href: `https://unsupported.docs.camunda.io/${version}/`,
})),
Expand Down Expand Up @@ -256,10 +256,8 @@ module.exports = {
"/docs/**/assets/**",
"/docs/**/tags/**",
"/docs/next/**",
"/docs/1.3/**",
"/docs/8.0/**",
"/docs/8.1/**",
"/optimize/3.7.0/**",
"/optimize/3.8.0/**",
"/optimize/3.9.0/**",
"/optimize/next/**",
Expand Down
2 changes: 1 addition & 1 deletion optimize_versions.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
["3.10.0", "3.9.0", "3.8.0", "3.7.0"]
["3.10.0", "3.9.0", "3.8.0"]
14 changes: 2 additions & 12 deletions static/.htaccess
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,6 @@ RewriteRule ^docs/apis-clients(.*)$ /docs/apis-tools$1 [R=301,L]
RewriteRule ^optimize/apis-clients(.*)$ /optimize/apis-tools$1 [R=301,L]
RewriteRule ^docs/8.0/apis-clients(.*)$ /docs/8.0/apis-tools$1 [R=301,L]
RewriteRule ^optimize/3.8.0/apis-clients(.*)$ /optimize/3.8.0/apis-tools$1 [R=301,L]
RewriteRule ^docs/1.3/apis-clients(.*)$ /docs/1.3/apis-tools$1 [R=301,L]

# Identity Authorizations
RewriteRule ^docs/next/self-managed/identity/user-guide/groups/creating-authorizations-for-a-group/(.*)$ /docs/next/self-managed/identity/user-guide/authorizations/managing-resource-authorizations/ [R=301,L]
Expand Down Expand Up @@ -223,8 +222,6 @@ RewriteRule ^docs/guides/implementing-connectors$ /docs/guides/configuring-out-o
RewriteRule ^docs/8.0/guides/implementing-connectors/(.*)$ /docs/8.0/guides/configuring-out-of-the-box-connectors/$1 [R=301,L]
RewriteRule ^docs/8.0/guides/implementing-connectors$ /docs/8.0/guides/configuring-out-of-the-box-connectors/ [R=301,L]

RewriteRule ^docs/1.3/self-managed/overview/(.*)$ /docs/1.3/self-managed/about-self-managed/$1 [R=301,L]
RewriteRule ^docs/1.3/self-managed/overview$ /docs/1.3/self-managed/about-self-managed/ [R=301,L]
RewriteRule ^docs/self-managed/overview/(.*)$ /docs/self-managed/about-self-managed/$1 [R=301,L]
RewriteRule ^docs/self-managed/overview$ /docs/self-managed/about-self-managed/ [R=301,L]

Expand All @@ -244,8 +241,6 @@ RewriteRule ^docs/self-managed/operate-deployment/authentication/(.*)$ /docs/sel
RewriteRule ^docs/self-managed/identity/troubleshooting/?$ /docs/self-managed/identity/troubleshooting/troubleshoot-identity/ [R=301,L]
RewriteRule ^docs/self-managed/identity/getting-started/?$ /docs/self-managed/identity/getting-started/install-identity/ [R=301,L]

RewriteRule ^docs/1.3/components/overview/(.*)$ /docs/1.3/components/components-overview/$1 [R=301,L]
RewriteRule ^docs/1.3/components/overview$ /docs/1.3/components/components-overview/ [R=301,L]
RewriteRule ^docs/components/overview/(.*)$ /docs/components/components-overview/$1 [R=301,L]
RewriteRule ^docs/components/overview$ /docs/components/components-overview/ [R=301,L]

Expand All @@ -269,8 +264,6 @@ RewriteRule ^docs/components/console/troubleshooting$ /docs/components/console/c
RewriteRule ^docs/components/best-practices/overview/(.*)$ /docs/components/best-practices/best-practices-overview/$1 [R=301,L]
RewriteRule ^docs/components/best-practices/overview$ /docs/components/best-practices/best-practices-overview [R=301,L]

RewriteRule ^docs/1.3/apis-clients/overview/(.*)$ /docs/1.3/apis-tools/working-with-apis-tools/$1 [R=301,L]
RewriteRule ^docs/1.3/apis-clients/overview$ /docs/1.3/apis-tools/working-with-apis-tools [R=301,L]
RewriteRule ^docs/apis-clients/overview/(.*)$ /docs/apis-tools/working-with-apis-tools/$1 [R=301,L]
RewriteRule ^docs/apis-clients/overview$ /docs/apis-tools/working-with-apis-tools [R=301,L]
RewriteRule ^docs/apis-clients/tasklist-api/tutorial/(.*)$ /docs/apis-clients/tasklist-api/tasklist-api-tutorial/$1 [R=301,L]
Expand Down Expand Up @@ -516,17 +509,14 @@ RewriteRule ^docs/self-managed/optimize-deployment/(.*)$ /optimize/self-managed/
RewriteRule ^docs/next/apis-clients/optimize-api/(.*)$ /optimize/next/apis-clients/optimize-api/$1 [R=301,L]
RewriteRule ^docs/apis-clients/optimize-api/(.*)$ /optimize/apis-clients/optimize-api/$1 [R=301,L]

## optimize extraction for version 3.7.0:
RewriteRule ^docs/1.3/components/optimize/what-is-optimize(\/?)$ /optimize/3.7.0/components/what-is-optimize/ [R=301,L]
RewriteRule ^docs/1.3/components/optimize/userguide/(.*)$ /optimize/3.7.0/components/userguide/$1 [R=301,L]
RewriteRule ^docs/1.3/self-managed/optimize-deployment/(.*)$ /optimize/3.7.0/self-managed/optimize-deployment/$1 [R=301,L]

## Archived versions. Note that the URL is adjusted to staging in the publish-stage workflow.
RewriteRule ^docs/0.25/(.*)$ https://unsupported.docs.camunda.io/0.25/docs/$1 [R=301,L]
RewriteRule ^docs/0.26/(.*)$ https://unsupported.docs.camunda.io/0.26/docs/$1 [R=301,L]
RewriteRule ^docs/1.0/(.*)$ https://unsupported.docs.camunda.io/1.0/docs/$1 [R=301,L]
RewriteRule ^docs/1.1/(.*)$ https://unsupported.docs.camunda.io/1.1/docs/$1 [R=301,L]
RewriteRule ^docs/1.2/(.*)$ https://unsupported.docs.camunda.io/1.2/docs/$1 [R=301,L]
RewriteRule ^docs/1.3/(.*)$ https://unsupported.docs.camunda.io/1.3/docs/$1 [R=301,L]
RewriteRule ^optimize/3.7.0/(.*)$ https://unsupported.docs.camunda.io/1.3/optimize/$1 [R=301,L]

# Add yaml mime type
AddType text/vnd.yaml yaml
Expand Down
2 changes: 1 addition & 1 deletion versions.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1 +1 @@
["8.2", "8.1", "8.0", "1.3"]
["8.2", "8.1", "8.0"]