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

pepopowitz · 2023-08-28T20:03:12Z

🛑 BLOCKED 🛑

The unsupported/1.3 site is not yet in production.
The version dropdown is confusing when viewing an Optimize doc! I'm intending to resolve in this PR, see comments.
OpenSearch is not yet supported in C8 Optimize (OpenSearch support is tracked at a platform level at https://github.com/camunda/product-hub/issues/997. Optimize support is tracked at https://github.com/camunda/product-hub/issues/1908.)

We should check back when #2432 is complete, to see if OpenSearch support has been included in Optimize. If it has, we can complete this issue. If it has not, we should schedule a reminder to check again a month or so later.

Description

Part of #2189.

Includes the smaller items for removing version 1.3 from the main docs, to keep the PR in a reviewable state.

Included in this PR

Remove v1.3 & Optimize v3.7.0 from the version manifest files, so that they're not included in the deployed site
Redirect all 1.3 / 3.7.0 traffic to unsupported.docs.camunda.io/1.3 (or stage.unsupported.docs.camunda.io/1.3 for the staging build)
Move 1.3 to the "Unsupported versions" sub-list in the top nav version selector, redirecting to unsupported.docs.camunda.io/1.3.
- The label for this version combines both the main version & Optimize version. This combined version label shows when viewing both a main doc (shown below on the left side) and an Optimize doc (shown below on the right side):

When should this change go live?

This change is not yet live and should not be merged until {ADD_DATE} (apply hold label or convert to draft PR)?
There is no urgency with this change.
This change or page is part of a marketing blog, conference talk, or something else on a schedule.
This functionality is already available but undocumented.
This is a bug fix or security concern.

PR Checklist

I have added changes to the relevant /versioned_docs directory, or they are not for an already released version.
I have added changes to the main /docs directory (aka /next/), or they are not for future versions.
My changes require an Engineering review, and I've assigned an engineering manager or tech lead as a reviewer, or my changes do not require an Engineering review.
My changes require a technical writer review, and I've assigned @christinaausley as a reviewer, or my changes do not require a technical writer review.

…ove 1.3 and 3.7.0 from sitemap ignore patterns

pepopowitz · 2023-08-28T20:37:11Z

docusaurus.config.js

@@ -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) => ({


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:

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

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.

Just let the incorrect unsupported versions display when viewing an optimize doc (0 effort, what you see in my screenshot above).

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:

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?

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.

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.

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:

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

…track more version things

…enerate dropdown items whose label doesn't match URL suffix

…ew file

pepopowitz · 2023-08-29T17:40:20Z

docusaurus.config.js

-            ...["1.2", "1.1", "1.0", "0.26", "0.25"].map((version) => ({
-              label: version,
-              href: `https://unsupported.docs.camunda.io/${version}/`,
+            ...unsupportedVersions.map((version) => ({


I moved these to a separate file because I wanted to type the array items, and I didn't want to clutter this already-large config.

pepopowitz · 2023-08-29T17:40:55Z

hacks/isolateVersion/8-configureOptimizeDocs.sh

@@ -24,7 +24,7 @@ sed -i '' "/^const versionMappings = \[$/,/\];/c\\
 const versionMappings = [\\
  { docsVersion: \"$ARCHIVED_VERSION\", optimizeVersion: \"$ARCHIVED_OPTIMIZE_VERSION\" },\\
 ];\\
-" src/mdx/expandVersionedUrl.js
+" src/versions.js


these versionMappings were moved to the same file as the new unsupportedVersions, because they are all about versions.

pepopowitz · 2023-08-29T17:41:46Z

howtos/release-procedure.md

@@ -63,7 +63,7 @@ To create the new versions:
   ];
   ```

-   - Add the new mapping in the first position of the array.
+   - Order of the items in the array is important. Add the new mapping in the first position of the array, because the first item is treated as the "current" version mapping.


I added this note because I think it's important. I only noticed it missing because I was editing the docs right above.

CLAassistant · 2023-10-05T08:35:35Z

All committers have signed the CLA.

akeller · 2023-12-12T17:28:30Z

@pepopowitz are you aware of the status of Optimize 1.3? Will this be included with the January minor release?

pepopowitz · 2023-12-12T21:20:35Z

@pepopowitz are you aware of the status of Optimize 1.3? Will this be included with the January minor release?

OpenSearch for Optimize is tracked at https://github.com/camunda/product-hub/issues/1908. It is targeting 8.5.

(I'll update this issue to include a link to the Optimize-specific Product Hub issue.)

akeller · 2024-03-13T18:13:28Z

This remains blocked. See internal update - https://camunda.slack.com/archives/C02AWA0RF8A/p1710317097178729?thread_ts=1703089659.451659&cid=C02AWA0RF8A

akeller · 2024-08-16T16:37:10Z

@pepopowitz, is your plan to resurrect this PR or open a new one?

pepopowitz · 2024-08-19T21:13:20Z

we should definitely close this and re-create later.

pepopowitz added 3 commits August 28, 2023 14:56

archive(1.2) exclude: remove 1.3 and 3.7.0 from the version manifests

75a3fe5

archive(1.2) exclude: redirect 1.3 / 3.7.0 traffic to new website

53c27a6

archive(1.2) exclude: move 1.3 to unsupported versions in navbar, rem…

7b84279

…ove 1.3 and 3.7.0 from sitemap ignore patterns

pepopowitz added kind/cleanup Issues related with clean-up the documentation hold This issue is parked, do not merge. dx Documentation infrastructure typically handled by the Camunda DX team epic:archive-old-versions labels Aug 28, 2023

pepopowitz self-assigned this Aug 28, 2023

pepopowitz commented Aug 28, 2023

View reviewed changes

pepopowitz added 4 commits August 29, 2023 12:19

refactor: extract versionMappings to a versions.js file, where we'll …

128874d

…track more version things

refactor: extract unsupportedVersions to versions.js, and use it to g…

225d5d1

…enerate dropdown items whose label doesn't match URL suffix

refactor: update isolation scripts to target versionMappings in the n…

387d3ac

…ew file

docs: update release procedure to account for new versions.js file

0442e77

pepopowitz commented Aug 29, 2023

View reviewed changes

pepopowitz removed the hold This issue is parked, do not merge. label Aug 29, 2023

pepopowitz mentioned this pull request Aug 29, 2023

Archive v1.3/v3.7.0 #2189

Closed

pepopowitz added the hold This issue is parked, do not merge. label Aug 30, 2023

pepopowitz mentioned this pull request Sep 1, 2023

chore(deps-dev): bump jest from 29.5.0 to 29.6.4 #2521

Merged

pepopowitz mentioned this pull request Nov 1, 2023

archive(8.0) exclude: remove versions 8.0 and 3.8.0, part 1: reviewable steps #2843

Merged

10 tasks

pepopowitz closed this Aug 19, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

pepopowitz commented Aug 28, 2023 •

edited

Loading

pepopowitz Aug 28, 2023

akeller Aug 28, 2023

pepopowitz Aug 29, 2023 •

edited

Loading

pepopowitz Aug 29, 2023

pepopowitz Aug 29, 2023

pepopowitz Aug 29, 2023

pepopowitz Aug 29, 2023

akeller Aug 29, 2023

CLAassistant commented Oct 5, 2023 •

edited

Loading

akeller commented Dec 12, 2023

pepopowitz commented Dec 12, 2023

akeller commented Mar 13, 2024

akeller commented Aug 16, 2024

pepopowitz commented Aug 19, 2024

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

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

Conversation

pepopowitz commented Aug 28, 2023 • edited Loading

Description

Included in this PR

When should this change go live?

PR Checklist

pepopowitz Aug 28, 2023

Choose a reason for hiding this comment

How much effort do we want to put into this?

Possible solutions

akeller Aug 28, 2023

Choose a reason for hiding this comment

pepopowitz Aug 29, 2023 • edited Loading

Choose a reason for hiding this comment

pepopowitz Aug 29, 2023

Choose a reason for hiding this comment

pepopowitz Aug 29, 2023

Choose a reason for hiding this comment

pepopowitz Aug 29, 2023

Choose a reason for hiding this comment

pepopowitz Aug 29, 2023

Choose a reason for hiding this comment

akeller Aug 29, 2023

Choose a reason for hiding this comment

CLAassistant commented Oct 5, 2023 • edited Loading

akeller commented Dec 12, 2023

pepopowitz commented Dec 12, 2023

akeller commented Mar 13, 2024

akeller commented Aug 16, 2024

pepopowitz commented Aug 19, 2024

pepopowitz commented Aug 28, 2023 •

edited

Loading

pepopowitz Aug 29, 2023 •

edited

Loading

CLAassistant commented Oct 5, 2023 •

edited

Loading