Document process of merging nmdc-schema/main into berkeley-schema-fy24/main (in local slang: "backmerge")

[eecavanna]

Document process of merging nmdc-schema/main into berkeley-schema-fy24/main (in local slang: "backmerge", "back-merge", "back merge").

Although I don't expect myself to be the only author here, there are some things I already want to document about the process. I am creating this ticket to act as a temporary home for that documentation.

[eecavanna]

1. Create a branch in the fork

1. Go to https://github.com/microbiomedata/berkeley-schema-fy24/branches
2. Click the "New branch" button (upper right)
3. Fill in the form
4. Name the branch something like: stage-for-merging-upstream-into-fork
5. Set the source repo to: https://github.com/microbiomedata/berkeley-schema-fy24
6. Set the source branch to: main
7. Click "Create new branch"

2. Create a PR in the fork

1. Go to https://github.com/microbiomedata/berkeley-schema-fy24/pulls
2. Click the "New pull request" button (upper right)
3. Click the words "compare across forks" near the top of the page
4. Set the branches as follows:
   1. Base repository: microbiomedata/berkeley-schema-fy24
   2. Base (branch): stage-for-merging-upstream-into-fork (or whatever you called the newly-created branch)
   3. Head repository: microbiomedata/nmdc-schema
   4. Compare (branch): main
5. Click the "Create pull request" button
6. Fill in the title field:

   Merge `nmdc-schema/main` into copy of `berkeley-schema-fy24/main` (preparing for backmerge YYYY-MM-DD)
   

   Replace YYYY-MM-DD with today's date

7. Replace any contents of the PR description field with the following:

   This PR was created to serve as a place where people can resolve merge conflicts.
   

   Note: A formal PR template is not necessary in this case, since the base branch is not the main branch.

8. Next to the "Create pull request" button, click the 🔽 "down arrow" icon and select "Create draft pull request"
9. Add yourself to the "Assignees" list (at least, for now, so there is an owner documented)
10. Click the "Draft pull request" button

3. Resolve merge conflicts

Use the stage-for-merging-upstream-into-fork branch to resolve any merge conflicts. Once all merge conflicts have been resolved, merging stage-for-merging-upstream-into-fork into main (of the fork repo) will be straightforward, in my opinion.

4. Create another PR in the fork

1. Go to https://github.com/microbiomedata/nmdc-schema/pulls
2. Click the "New pull request" button (upper right)
3. Set the branches as follows:
   1. Base (branch): stage-for-merging-upstream-into-fork (or whatever you called the newly-created branch)
   2. Compare (branch): main
4. Click the "Create pull request" button
5. Fill in the title field:

   Merge `stage-for-merging-upstream-into-fork` into `main` (backmerge YYYY-MM-DD)
   

   Replace YYYY-MM-DD with today's date; and replace stage-for-merging-upstream-into-fork with the name of the branch you created earlier.

6. Fill in the PR template
7. Add yourself to the "Assignees" list
8. Click the "Create pull request" button

5. Merge the PR

Once the PR has accumulated the necessary approvals, merge it (by merging the PR).

6. Clean up

1. Delete the stage-for-merging-upstream-into-fork branch you created earlier

[eecavanna]

I will work with @turbomam on filling in section 3 of the above guide.

[eecavanna]

I think @mslarae13 also wants the following to be documented:

• Under what conditions someone will create a pre-release
• How to create a pre-release

[eecavanna]

We tested out these steps today. At step 3, we did not end up with a branch where we could collaborate; so, this didn't put is in any "better" position than before.

[eecavanna]

I think @mslarae13 also wants the following to be documented:

• Under what conditions someone will create a pre-release
• How to create a pre-release

Here is my proposal for this:

Any time the main branch of the berkeley-schema-fy24 repo has changed since the last time a pre-release was created, anyone that has sufficient access on GitHub can create a new pre-release of it, provided they follow all the relevant steps in the (internal) https://github.com/microbiomedata/infra-admin/blob/main/releases/nmdc-schema.md guide, plus they mark the "Pre-release" checkbox after doing the existing steps in the "Making a Release > Create a new GitHub Release" section of that guide.

In short, in the context of the Berkeley schema and the stage of the Roll Out we're in, my view is that "no change is too small to warrant a release" and "no time is too soon to do another release."

In even shorter; once you merge a PR or a group of PRs, create a new pre-release.

[eecavanna]

Document process of merging nmdc-schema/main into berkeley-schema-fy24/main (in local slang: "backmerge", "back-merge", "back merge").

My proposal for this original task is:

Given that @turbomam is the only person that happens to have done this process end-to-end so far, we wait until the next time he is going to go through the process, and then either he document it as he goes through it, or he pair up with me or someone else to document it (or at least note the steps) at that time.

[turbomam]

• @turbomam to add the following in backmerge conflict resolution
  • it doesn't appear possible to make a branch (for multiple people to access)
  • so the backmerge is best done with two or three people who have a combination of domain, modelling and GitHub skills
  • delete generated files before resolving conflicts
  • there are more schema files in berkeley-schema-fy24 than there are in nmdc-schema. be prepared to look for content that is duplicate in two files after the merge
  • schema conflicts should be worked though with the guidance of example data files and vice versa

[ssarrafan]

@turbomam @mslarae13 @eecavanna is this documentation task complete?

[eecavanna]

Not yet. I don't expect this to be finished this sprint/week.

Our most recent plan was to wait until the next time @turbomam performs the steps, and document them at that time.

Also, given that the fork-to-upstream merge is scheduled to happen on Monday, I don't know when @turbomam would be performing these steps next, if ever.

Once the Berkeley Schema Roll Out has concluded, I'm planning to work with @turbomam to make it so derivative files don't get stored in the repo; which I think would change (simplify) the process this ticket is about documenting.

[ssarrafan]

I'll move to sprint 48.

[ssarrafan]

Removing from sprint. No updates in a month. @turbomam @eecavanna @mslarae13

[mslarae13]

@eecavanna @turbomam

Is there still effort to do this?
I know there's been some documentation, and if we don't think we need this anymore, we can close as will not complete.

(Trying to wrap up this squad's project board)

[eecavanna]

I am in favor of closing it.

[eecavanna]

Once the Berkeley Schema Roll Out has concluded, I'm planning to work with @turbomam to make it so derivative files don't get stored in the repo; which I think would change (simplify) the process this ticket is about documenting.

I'm still planning to do what I described in that quote—just haven't gotten to it yet 🙁 . Related: #1960