MR process: Maintenance Release Notes

[mattpen]

@zepumph and I made the following notes while working on the maintenance release for phetsims/chipper#746.

Process notes/questions

• When using the maintenance REPL in GitBash / Windows 10, TAB auto-complete and Ctrl+C do not work as expected. It would be super nice to get these working for Windows devs.
• Can we add history between sessions in the maintenance REPL? It would be convenient to be able to access previously typed commands across sessions.
• What happens if you need to maintenance release a fix for two separate problems in a single repo? Maybe this would never happen. (MK EDIT: Right now you basically have to wrap both changes into a single "patch")
• updateDependencies hangs up when the computer goes to sleep and needs to be restarted multiple times. It might be helpful to just add a link to https://support.apple.com/kb/PH25222?locale=en_US in documentation.
• Should we be able to check in .maintenance.json? This could be helpful for improving collaboration or saving progress when the process takes a long time. It could also be problematic if there are multiple batch releases in progress concurrently.
• The method 'Maintenance.linkList()' isn't immediately clear by name what is is doing, perhaps 'printLinkList' instead?" I was scared to call it originally with the thought that I would do some sort of action, like 'linking'.
• We should remove the reportThirdParty script from production deploys before the next batch release, or document a way to work around it.

Documentation changes/questions:

• Should we note that build-local.json is required, or at least mention that the developer should follow the standard developer guide first?
• Add a note that npm config set save false will help solve some git/npm issues, such as new lines at the end of package.json and extraneous package-lock.json files. Perhaps this is covered in the same point about referencing the standard dev guide.
• There is still a slight ambiguity whether REPO means the release branch repo or the patched repo. It would be easier to read if it was either something like "release_branch_repo" or "patch_repo" but never just "repo".
• Add reminder to setup your email for build-server notifications and note that a successful deployProduction on the dev's machine does not imply successful deploy.
• What is the difference between Step migrate things from chipper that should always be on master #1 and Step [build-server] adding new sims to rosetta fails #2 Question 2? "Ask on slack" doesn't seem like a reliable way to determine possible conflicts.
  • Perhaps it would be helpful to add a link to https://github.com/phetsims/QA/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+%22RC+test%22 in Step [build-server] adding new sims to rosetta fails #2.

I'd be happy to help with any of these changes. Assigning @ariel-phet for priority.

[mattpen]

What is the difference between Step #1 and Step #2 Question 2? "Ask on slack" doesn't seem like a reliable way to determine possible conflicts.

@jonathanolson said that Step #1 is for published branches and step #2 is for unpublished.

I think it would be super nice if Step #2 could be automated somehow.

[ariel-phet]

@mattpen I think the maintenance release process is important enough to our project that it continues to deserve attention. Marking as medium priority. Feel free to also discuss at dev meeting as well.

[zepumph]

Note that on windows subsystem for linux (ubuntu 18 LTS) the tab complete does work:

[jonathanolson]

I believe the above 4 issues and 2 commits encompass all of the listed changes, with the exception of:

There is still a slight ambiguity whether REPO means the release branch repo or the patched repo. It would be easier to read if it was either something like "release_branch_repo" or "patch_repo" but never just "repo".

This sounds like a good change to make. I presume it would be done in the code also (releaseRepo maybe?)

[jonathanolson]

@ariel-phet, the main documentation changes (with the exception above) have been made, and I've isolated actionable changes to the linked issues. Should I move forward with the changes, and if so with what priority?

[ariel-phet]

@jonathanolson yes, please move forward with the changes. Still medium priority, although maybe some can be taken care of with this iO fix?