Document how to split up remote_dev branch into curated commits which correspond to planned master MRs

COMPLETED: See documentation here: https://gitlab.com/gitlab-org/remote-development/gitlab-remote-development-docs/-/blob/main/doc/integration-branch-process.md

Original description

See this comment: gitlab-org/cluster-integration/gitlab-agent!805 (comment 1339859442)+

Summary (rephrased from above comment):

Ideally, we want to clean up everything while it is still on the remote_dev branch, and have it in a completed and final state, and curate it (via interactive rebase) to a single, clean commits which can be cherry-picked when we start the master MRs.

In other words: Keep the remote_dev branch curated out to a clean set of separate commits which represent the individual MRs that we will merge to master.

This will also ensure that we have all the sequential dependencies figured out before we start the work on the master MRs.

Then:

  1. As we continue to make changes on the master MRs (based on review feedback), we can cherry-pick-and-squash those changes back into the corresponding commits on the remote_dev branch
  2. As we continue to make changes on the remote_dev branch (via new MRs off the remote_dev branch for continued greenfield feature development), we can ensure those are also incorporated into individual curated commits, either squashed to an existing one, or to a new one if it's a new cohesive piece of work that will have a dedicated master MR.
  3. Master MRs will NOT be squashed!. Any changes on master MRs which are needed due to review feedback will be kept in separate commits, which can be cherry-picked back to the appropriate place on the remote_dev branch. Then, once the master MR is merged, all of the corresponding commits that were merged as part of the MR should auto-magically disappear the next time we rebase the remote_dev branch (because they are identical commits).
  4. We should ultimately end up with nothing on the remote_dev branches at all. All code should be merged as part of MRs or deleted. Any TODO comments should have a corresponding issue opened, put the issue URL in the TODO (per our doc guidelines), and then merge the TODOs to master in an MR (or just delete them if we are OK with just the issue).

This is effectively just being very disciplined and methodical about the up-front planning about exactly what is going to go into each of the various master MRs.

We can decide whether we want the sub-issues for the master MRs to live under Remote Development Beta - Review and merge rail... (&10258 - closed), or whether they should be organized by category under sub-epics of Remote Development • Workspaces Beta (&10122 - closed). I believe the latter would be easier, to keep everything organized by topic/repo. EDIT: I changed my mind, I think it's best to keep them under Remote Development Beta - Review and merge rail... (&10258 - closed), because the MRs will not necessarily break down along feature/function lines, because of cross-feature dependencies.

Edited by Chad Woolley