🛑 BLOCKED 🛑 Archive older versions to external static sites

[pepopowitz]

We should archive older versions of our docs, into separate static sites.

Why?

Each time we add a new version to our docs, it impacts our build time -- it's a bunch more files that docusaurus needs to turn into pages. The recommendation from docusaurus, and what their docs do, is to archive old versions to separate static sites. You can see this in their version selector, which contains a section of "archived versions":

Implementation considerations

• We should call older versions something other than "archived" in our UI.
  • Decision: we shall call them "unsupported."
• We support releases for 18 months, so anything older than that is fair game for archiving.
• Do we want to build old versions from source files, in case we need to update in the case of security exploits or other important reasons?
  • Decision: we will build them from source, with each unsupported version in its own branch, fully isolated from the other versions.
• If we keep the source, can we leave them in the repo but have docusaurus not build them for every build?
  • See above decision.
• Docusaurus does not hang on to old source, they remove it. They rely on the fact that Netlify creates immutable unique URLs for every build, and they capture a URL for older versions.

Progress

Tasks

Preview Give feedback

1. [DO NOT MERGE] Prototype: archived versions, the main end #2128
   +0
2. [DO NOT MERGE] Prototype: archived versions, the *archived* end #2129
   hold +1
3. assorted: Archive pre-work #2155
   dx epic:archive-old-versions kind/enhancement +3
   
4. feat: a set of bash scripts to do the least complex steps of archiving a version #2160
   dx epic:archive-old-versions kind/enhancement +3
   
5. feat(docs): describe the process for archiving an unsupported version of the docs #2181
   component:docs dx epic:archive-old-versions +3
   
6. Archive v0.25 #2183
   8 of 8
   dx epic:archive-old-versions kind/cleanup +3
   
7. chore: reorder automated archival steps #2223
   dx epic:archive-old-versions kind/enhancement +3
   
8. Archive v0.26 #2184
   9 of 9
   dx epic:archive-old-versions kind/cleanup +3
   
9. Archive v1.0 #2185
   10 of 10
   dx epic:archive-old-versions kind/cleanup +3
   
10. Archive v1.1 #2186
    8 of 8
    dx epic:archive-old-versions kind/cleanup +3
    
11. Archive v1.2 #2188
    8 of 8
    dx epic:archive-old-versions kind/cleanup +3
    
12. Archive v1.3/v3.7.0 #2189
    12 of 12
    dx epic:archive-old-versions hold kind/cleanup +4
    
13. Remove Search from unsupported versions #2475
    7 of 7
    component:docs dx epic:archive-old-versions kind/cleanup +4
    

[akeller]

This will likely get promoted to a Product Hub Epic.

[akeller]

Before I move this to an epic, I'd like to get this question answered:

We should look at docusaurus to see what they do with their archived versions. I know they aren't in the same repo...but maybe they are in their own repo somewhere?

I'll also socialize the "archived" language with legal and the C8 Stakeholder meeting.

[pepopowitz]

I updated the PR body, but re: docusaurus and how they handle archived sites, they explain it here. They don't hang on to the old source -- they capture the immutable URL from that specific release of the docs, and put that in the nav bar.

[pepopowitz]

What that means for us is....we can't look at docusaurus as a model for this. As far as I'm aware we don't have an immutable URL for every deployment. If we need to be able to update old versions, we'll need to come up with our own model for preserving old source, removing it from the current build, and being able to regenerate the old version docs.

[akeller]

We got a thumbs up from the C8 Stakeholder attendees this morning, but we'll need to do two things:

• Determine supported versions (we support 1.3 and 8.0, but moving forward we will support versions for 18 months)
• Decide on terminology ("Archive" wouldn't work for us)

Three things if you want to count "scheduling" this work, which is more of a question for you @pepopowitz. When would you like to consider this work?

[akeller]

Given the 30-45 min build times we saw getting the release out for 8.1/3.9.0, this will be critical by Q1. It's annoying now. I'll move this into an epic for future planning.

[akeller]

Please continue conversation on https://github.com/camunda/product-hub/issues/499.

[pepopowitz]

@akeller I'm reopening this, and attaching it as a line item for the product-hub issue. The product-hub issue became more broad, but this is still a specific tactical change we will want to prioritize & consider making.

[pepopowitz]

I'm closing this issue. There is one blocked version remaining, but it is tracked on its own. For all intents and purposes, this epic is complete.