Update `release-procedure.md`

[akeller]

Documentation now supports continuously releasing components and components with two different versioning strategies or paths. We should update the docs for both release procedures:

• Simple GitHub release for patch version
• Release for C8 minor version
• [Future] Release for Optimize minor version

[akeller]

The first two items were taken care of in #1281.

@pepopowitz do you have a separate issue for your Optimize work or is it reflected in #1116?

[pepopowitz]

It is in #1116!

Add documentation clarifying our multi-instance setup.

[pepopowitz]

But this is better defined & I'm going to link to it from #1116.

[pepopowitz]

Sharing some findings about what it takes to do a release with our new multi-instance setup, for posterity but also in hopes of coming to a conclusion on one of them:

Things that need to happen to cut a new version

1. Edit sidebars.js and optimize_sidebars.js to remove /next from the helper at the top of each file.
   • this is needed for docusaurus to generate the correct URLs in the new version's sidebar files.
   • this is a temporary step and will not be committed.
   • depending on a discussion further down, this might be something we choose to automate.
2. Create new versions via docusaurus:

   npm run docusaurus docs:version 8.1
   npm run docusaurus docs:version:optimize 3.9.0

3. Revert sidebars/optimize_sidebars changes from step 1
4. Update expandVersionedUrl so that mappings are all correct
   • This is clunky. It's a lot to expect people to get these mappings all correct -- it's not just adding new ones, it's also editing existing ones.
   • It also includes fixing tests that will be broken based on the mappings changing.
   • I can (and will) make this better before the release. If we only have to maintain a list of mappings (e.g. 8.1:3.9.0), it'll be easier, and we can just generate all the mappings in expandVersionedUrl from that. It would also remove the need to update tests.
5. Update the previous versions' sidebars.json/optimize_sidebars.json files to add version number to the cross-instance URLs.
   • this is not fun. This is why I wrote the helper functions at the top of the sidebars.js files in the first place; unfortunately docusaurus not supporting .js files for previous versions bites us here.
   • I could definitely write a regex to make this easier.
   • I could also script it! So that we could run npm run cutVersions 8.1 3.9.0 and it would edit all the URLs in the previous-version-sidebars/previous-version-optimize_sidebars.
   • If I'm scripting that step....I might as well include the other steps, too????

@akeller it's this last step, 5, where I start to worry about the slippery slope. I personally think it would be valuable to have a script to do this all for us, because when I win the lottery I don't want others to have to do this all manually. But, we can cut new versions without scripting anything, if we want to do the manual work. Do you have any thoughts on the value of me trying to capture this process in a single script vs just documenting all the manual steps?

[pepopowitz]

oh, and then there's htaccess rules. I didn't account for that here, but I suspect we'll need to add some for some URLs that have moved in the new version. I anticipate tracking these down to be easiest after we push up the initial PR to cut new versions. Let CI find them for us!

[akeller]

because when I win the lottery I don't want others to have to do this all manually

The amount of empathy in this statement! 💞

Thank you for this great summary of the steps and overall situation. I think the 2nd line in step 2 was what I was trying to communicate this morning but saying (or asking) poorly. It looks like we cut a release for C8 AND we cut a release, separately for Optimize.

As I feel like I've been asking more often recently, how big is this or about how long do you think it would take to script? From my perspective, this looks annoying to do manually and we know we'll need to do it at least twice a year (October and April). Could you script this between now and Oct 10 and feel confident to run it then? If not, let's agree to manual now and planning to script it in the future (and also not let you win the lottery). This would mean it would be required work in Q1.

Which leads me to my next question, would you be able to ignore this (the scripting aspect) between now and Q1? Or would it keep you up at night?

[pepopowitz]

The amount of empathy in this statement! 💞

😂

• I definitely think this is something I could write by October 10th. I actually think I could get it done before you are out next week.
• I don't think it would keep me awake. I do think this is an ideal time to write it, because the release presents a very important and time-sensitive motivation.
• I don't have plans to buy lottery tickets by October 10th.

Given your response was not "omg steve stop wasting your time," I feel good moving forward with trying to automate this process as much as possible for this upcoming release.

[akeller]

🟢 let's gooooooooo 🚀