RFR: Section on project maintenance [v3]

[Jesper Wilhelmsson]

On Thu, 22 Sep 2022 07:51:26 GMT, David Simms <dsimms at openjdk.org> wrote:

>> 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 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.

I've included this addition mostly intact. Just did some minor changes to make it fit in.

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

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