MR process: adding patches after updateDependencies

[mattpen]

A problem arose while @jessegreenberg and I were working on the MR for phetsims/scenery#883.

We added the commits and repos that we thought were necessary for the patch and thought that we were ready for updateDependencies(). There was a build failure during the run for one of the sims and we realized that further commits were needed. We created a new commit and added it with addPatchSHA. We then called applyPatches which did not apply the commit as expected.

At this point @jonathanolson joined the process. It's not clear to me what the exact fix was, as I had to briefly step away from the call, but it involved some manual edits to the .maintenance.json file. @jonathanolson or @jessegreenberg may be able to describe it better.

This may have been related to (or at least compounded by) copy/paste problems in GitBash. JG was using Ctrl+C/Ctrl+V for copy/paste, which was adding extraneous \u0016 characters to the SHA strings.

One thing that may have helped is a step to build all patched repos before committing/pushing changes to dependencies.json.

[jessegreenberg]

This description is how I remember it as well.

This may have been related to (or at least compounded by) copy/paste problems in GitBash

I think this is very likely. We hit a problem twice where it was unable to checkout a SHA. The first time we fixed it by removing all SHAs from .maintenance.json and starting fresh. The second time it was fixed by manually removing two \u0016 characters that were added when I accidentally Ctrl+V a SHA into the command.

[zepumph]

I feel like the solution here, and what I have done in the past, is to actually just create a new patch that only applies to that repo. This way you have total control over that fix, without it mucking up the other sims that apply to the original patch. I think this is a relatively acceptable way to proceed, since I don't know how you would communicate to the maintenance process that one sim needs to be altered by a change, but not the other.

We created a new commit and added it with addPatchSHA. We then called applyPatches which did not apply the commit as expected.

Likely because the MR process though it had already correctly fixed that sim with the original patch.

I recommend updating documentation, perhaps a new "troubleshooting" section, which I would have other items to add to also, but no code changes to the MR tooling. @mattpen does this seem reasonable to you.

Also, I know it has been a long long time here, so feel free to just toss it back to me without understanding fully and move on with the important parts of life.

[zepumph]

I improved the doc about. Feel free to close or assign back to me.

[mattpen]

Thanks for improving the documentation @zepumph. It's been almost 5 years since this issue was opened and I haven't used the maintenance release process since then, so I don't have opinions on the best way to proceed.