Overall the doc looks very good. I think there is one process point to address, and if people agree with it then I think it should make its way into the document:
Before the fork to pipe_best happens, developers with work in progress should have a chance to push any local changes in their branches to meas_worst, so that their branches will also exist in pipe_best after the fork.
(one of the reasons it ended up being easy for me to integrate my changes was that I had pushed all my branches to daf_butlerUtils before leaving for vacation, before the fork to obs_base happened).
The person who will do the rename should find developers with work in progress (I put details about how to do that below) and work out a time to do the change, giving them a chance to push all their latest work
This is a subtle difference from our normal workflow where I've heard it put: "first to master wins", which is ok by me given the usual caveats about publishing API changes and doing RFC's and whatnot. The difference in this case is that other devs should be allowed the chance to send all the latest work in their branches along with the fork.
I think there's 2 ways I know of to figure out who may have work in progress:
The first is to look for active branches on github:
1. go to the package home page on github
2. click on the 'code' tab (if needed, I think it's the default tab)
3. click on the sub tab that shows the number of branches e.g. it will say something like "101 branches"
4. click on the 'active' tab to see active branches and who owns them.
The other way is to search for the component in lira:
search for issues with status "in progress" and where the component matches the package name
If we adopt this process, then the section "Merging in work that had started on the old package" changes to
1. Before meas_worst is forked, push your meas_worst changes to github on your branch.
2. After the rename is complete, clone pipe_best: git clone https://github.com/lsst-dm/pipe_best (it would also work to instead do 'rebuild pipe_best', which will clone pipe_best into the 'lsstsw/build' directory)
3. Checkout your branch; it should exist in pipe_best. If it does not, or if it is not up-to-date with your latest changes in meas_worst, you may have to follow the `syncing a fork`_ instructions.
4. Rebase to pipe_best master: git rebase master
5. Fix any conflicts. There may be a few, if you modified lines around statements that were changed during the rename.
6. Commit and push your branch to pipe_best, and continue your work.