RFR: Section on project maintenance [v3]

[David Simms]

On Wed, 21 Sep 2022 20:15:00 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> * New section on project maintenance
>> * New infographics on push/defer during rampdown
>> * Moved JDK Release Process section to follow the Release Note section
>> * Minor fixes
>
> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update after Ludvig's review

src/guide/project-maintenance.md line 38:

> 36: 
> 37: We start by updating the local fork with the latest changes from the main project repository. Note that we then create a new branch in which the merge will happen.
> 38: 

Merging from what ever is latest is not usually a good idea, mainline code is not "clean" for any given commit. Merging JDK tags ensures you have a known quantity, those tagged commits are known to compile and test. 

Check which tags have not been merged: `git tag -l "$PREFIX*" --no-merged` (e.g. `PREFIX="jdk-24"`) and merge up to said tag: `git merge $TAG`

Before merging, you may want to check what is incoming, and get an idea of the size of the merge and look for any incoming changes that you suspect may cause issues (`git log --topo-order --pretty=oneline --reverse ..$CHANGE`).

src/guide/project-maintenance.md line 42:

> 40: 
> 41: Once you have a working version of your merged code (make sure you test it properly) you're ready to create the commit and push. Please note that `git commit` is only needed if there were conflicts. If the changes were successfully merged by `git merge`, you're already ready to push.
> 42: 

Testing needs to be done even when there are no textual conflicts, i.e. rename can result in a compile or test error, without any conflict. One could argue that "merge --no-commit" could be used and have logical errors fixed in the same commit. A subsequent "Fix logical merge errors" commit, is in fact, more useful, as it clearly shows the project specific adjustments needed for incoming changes.

The two paragraphs above omit the case where further commits are needed to fix both compilation and test problems due to logical merge problems, and that's okay to have further commits. Hiding a large amount of reworking project code to fit with upstream in a single merge commit will make it hard for further errors post integration to be identified.

### Sharing the work

Conflicts can take place in areas requiring specialized knowledge that the person performing the merge needs help with from other contributors. Backing up the original conflicts (`git status | grep "both modified:" | while read B M FILE; do cp -v $FILE $DEST ; done`), will help if you find yourself "in too deep", and need assistance from other contributors. You can add and later remove these backups, along with a readme describing the merge status, to the actual merge branch to aid communication (i.e. you may not be able to compile certain components).

Here are two methods of collaborating on a merge...

### Parking a merge with conflicts in place

"Park" the conflicts, unresolved, in a personal fork, and let others do the further work (by sending you a patch, or opening your personal fork up to push from other contributors). Do this by keeping a list of unresolved conflicts (perhaps checking in said list to describe the merge state), and then marking them resolve in git, committing and pushing them to you personal fork (`git add $UNRESOLVED_FILES; git commit; git push`).

**Pros:** all unresolved conflicts are stated and can be worked on by multiple parties, all at once.
**Cons:** broken branch in terms of compile and test, may require temporary workaround patches to be passed around to complete work on specific unresolved components.

### Incremental Merging

An alternative to "parking a merge with conflicts in place", is to incrementally merge up to the troublesome point. For example:

1. Perform the initial merge: `git merge $TAG`, find yourself in trouble, identify which change is causing the issue.
2. Abort, `git merge --abort`
3. Find the troublesome change, `git log --topo-order --pretty=oneline --reverse $(current_branch)..$TAG`
4. Merge up to the previous change, commit and push.
5. Ask others to continue the merge from the troubled change forward, how far forward is up you: A) just that troublesome change, or B) the rest of the merge up to the `$TAG`.
6. Rinse and repeat: there may appear further conflicts requiring other contributors help.

**Pros:** all commits in the merge branch compile and test, you always have a working branch.
**Cons:** there is an unknown extra amount of merge work, multiple iterations create more work...you may find yourself resolving the same files multiple times (e.g. back-out commits)

### Further commits

Again, further commits are fine...merge PR itself will describe any special actions that were taken in case further failures turn up after merge integration. Ultimately these commits will be squashed when integrating the project back into mainline.

src/guide/project-maintenance.md line 52:

> 50: Make sure the name of the PR starts with "Merge". You may have noticed that when you integrate a "normal" PR into an OpenJDK repository, all commits that have been done in that PR will be squashed into a single commit. For normal changes this is a good thing as each PR normally corresponds to a single JBS issue, but for a merge it would be highly undesirable to squash all the different commits that you pull in from mainline. A PR with a name that starts with "Merge" won't be squashed. That means that all the changes that you brought over will remain separate changes.
> 51: 
> 52: Wether a merge requires a review or not is up to your project lead to decide. Many projects don't require this so the GitHub bots will allow you to push the merge as soon as the [GHA](#github-actions)s are done. (They actually allow you to push even before the GHAs are done, but that's in general not a good idea.)

Wether => Whether

src/guide/project-maintenance.md line 53:

> 51: 
> 52: Wether a merge requires a review or not is up to your project lead to decide. Many projects don't require this so the GitHub bots will allow you to push the merge as soon as the [GHA](#github-actions)s are done. (They actually allow you to push even before the GHAs are done, but that's in general not a good idea.)
> 53: 

What was merged ? Recommend adding summary, e.g: `/summary Merge tag 'jdk-22+9'"`

-------------

PR: https://git.openjdk.org/guide/pull/92