refactor: simplify version mapping logic #1328
Conversation
pepopowitz
added
component:docs
src/mdx/expandVersionedUrl.js
Outdated
| const versionMappings = [ | ||
| // When cutting a new version, add a new mapping here! | ||
| { | ||
| token: "$optimize$", | ||
| rules: [ | ||
| // TODO: introduce these mappings, as versions are added for optimize. | ||
| { match: "/docs/", expandTo: "/optimize/next" }, | ||
| { match: "/versioned_docs/version-8.0/", expandTo: "/optimize" }, | ||
| // { match: "/versioned_docs/version-1.3/", expandTo: "/optimize/3.7.0" }, | ||
| ], | ||
| docsVersion: "8.0", | ||
| optimizeVersion: "3.8.0", | ||
| }, | ||
| { docsVersion: "1.3", optimizeVersion: "3.7.0" }, | ||
| ]; |
There was a problem hiding this comment.
This is the payoff of this PR. On the left side we would have had to align the source directories with URLs when adding a new version; on the right, all we have to do is add a new object that aligns the two versions.
There was a problem hiding this comment.
I spent some time playing with the idea of removing this mapping entirely -- instead looking at the version files defined for docusaurus, and aligning the two lists of version numbers to come up with this mapping.
I decided to pause on it because while I love the idea of not maintaining this additional list of versions, I think I can simplify the version release process a good amount even with this second list of versions. I might return to the idea in the future though.
There was a problem hiding this comment.
A great future topic for sure. If you want, you can already create an issue we can revisit later.
| const docsToken = { | ||
| token: "$docs$", | ||
| rules: [ | ||
| { match: "/optimize/", expandTo: "/docs/next" }, |
There was a problem hiding this comment.
I could add comments here if you think it'd be useful.
This first rule is for the "next" version, which will always have the same mapping....
There was a problem hiding this comment.
This seems clear enough not to need a comment.
| rules: [ | ||
| { match: "/optimize/", expandTo: "/docs/next" }, | ||
| { | ||
| match: `/optimize_versioned_docs/version-${currentVersions.optimizeVersion}`, |
There was a problem hiding this comment.
...This second rule maps the current version in the source to the non-versioned URL....
| match: `/optimize_versioned_docs/version-${currentVersions.optimizeVersion}`, | ||
| expandTo: "/docs", | ||
| }, | ||
| ...remainingVersions.map((version) => { |
There was a problem hiding this comment.
And for each of the remaining versions, both the source and target URLs have the version in them.
| }, | ||
| { docsVersion: "1.3", optimizeVersion: "3.7.0" }, |
There was a problem hiding this comment.
I haven't moved any docs for these versions yet, but having this mapping here shouldn't hurt anything (because no docs are using the $docs$/$optimize$ shortcuts in v1.3 yet.)
| @@ -21,6 +21,7 @@ describe("expandVersionedUrl", () => { | |||
| "/Users/monkeypants/camunda-platform-docs/optimize/what-is-optimize.md", | |||
| "/docs/next/some/thing", | |||
| ], | |||
|
|
|||
| [ | |||
| "/Users/monkeypants/camunda-platform-docs/optimize_versioned_docs/version-3.8.0/what-is-optimize.md", | |||
There was a problem hiding this comment.
These tests will fail when we cut a new version. I think that's fine for now -- we don't actually run them as part of CI anyway, and it's less important to me that the tests are robust and more important that versioning is easier.
src/mdx/expandVersionedUrl.js
Outdated
|
|
||
| /** @type {Array<VersionMapping>} */ | ||
| const versionMappings = [ | ||
| // When cutting a new version, add a new mapping here! |
Part of #1217
What is the purpose of the change
Refactors the version mapping logic (i.e. docs v8.0 <=> optimize v3.8.0) to simplify its external API.
At time of cutting new versions, this logic would have required detailed changes that were prone to mistakes. With this refactor, updating this file involves nothing more than specifying the new docs & optimize versions.
This PR also updates the tests associated with this logic based on the correct version mappings (I forgot to update them when I extracted v3.8.0 of Optimize!)
Are there related marketing activities
No
When should this change go live?
Should have no effect to production, but merging in the next couple days is probably best in terms of getting things ship-shape for the upcoming version release.
PR Checklist
/versioned_docsdirectory, or they are not for an already released version./docsdirectory, or they are not for future versions.