Committers Guide & Upmerging Guide

Merging a pull request

  1. Ensure tests are passing and the PR is merge-able.

  2. Ensure the creating pull requests and getting them merged guideline is followed.

  3. Ensure the branch is correct (lowest applicable maintained branch).

  4. Ensure a proper commit message is written for the pull request according to commit message styleguide

  5. Use pull request title and body (first PR comment that is always available and automatically created) for proper commit message used for the change log.

  6. When merging the pull request, copy body text under the automatically inserted title in the “merge commit message”.

  7. Update status on related Github issue

The log fetches the pull request title and body directly from Github, which allows fixing it post merge. However the body should still be copied when merging, since it provides better details in the actual Git log and in the GH commit overview.


All committers can do a branch merge if necessary. An upmerge is done by first merging the lowest maintained branch into the next higher maintained branch (which should be current stable) and then merging the result into master (or the next higher branch if more branches are supported, until you hit master).

Before you start merging, you need to set the merge strategy to “ours” to enable merge configuration stored in .gitattributes used to avoid conflicts in built files:

git config merge.ours.driver true # optionally use the --global flag

In the following example the current stable is 2.0 and the old stable is 1.2:

git checkout 4.3
# makes sure that 4.3 is up to date
git pull
git checkout 5.0
# makes sure that 5.0 is up to date
git pull
git merge 4.3

Now you may need to resolve conflicts and finally commit the merge if an automatic merge was not possible.

git push 
git checkout master
git pull 
git merge 5.1

Again you may need to resolve conflicts and merge the commit.

Note: Once you hit the Flow branch version 6.0 or higher, you are adviced to run the psalm static analysis to check if the upmerge introduced new type issues or potentially solved old ones. This can be done with running
./bin/psalm --config=Packages/Framework/psalm.xml --update-baseline --show-info=false
(which could be automated)
In case new issues emerge, the best solution would be to fix those issues, or even discuss them with the team if they are more severe. However if a merge is in due need and fixing the psalm issues is not easily doable, the eject mechanism of the imanent travis failure is to run
./bin/psalm --config=Packages/Framework/psalm.xml --set-baseline=Packages/Framework/psalm-baseline.xml
which will lead to all existing errors to be ignored in all following psalm runs.

Commit the merge commit with the prefix MERGE like MERGE: Merge branch '1.2' into 2.0
to keep track of upmerges separately from PR and other branch merges.

If there are many conflicts you can use the recursive strategy with the ours option. This should be harmless in most cases but beware that this prefers the branch you are merging into. It might “drop” changes that should have gone in if the respective part was changed in both branches. This way of merging is mostly useful if changes that have a similar effect were merged manually to all branches (like a code style change or file header comment change). The upmerge should then be initiated right after those changes so you can be sure that nothing useful gets lost.

git merge -s recursive -X ours 1.2 
# recursive ours merge of 1.2 into the current branch

Upmerges leading to XLIFF conflicts: Only changes to “en” should be (up-)merged, those are pushed to Crowdin automatically. Then any updates to the translations are pulled from there automatically. Thus you should never upmerge any XLIFF changes that are not done to “en”…

Upmerging namespace changes (from Flow 3.3 to 4.0 or Neos 2.3 to 3.0) leads to “deleted by them:” issues.

To circumvent this issue, the rename threshold has to be raised.

git config merge.renamelimit 10000
git merge origin/2.3 -s recursive -X 'rename-threshold=1%'



Bonus tipp: sometimes you want to exclude certain changes during the merge (for example, change logs), so what you want is that the merge is prepare in your working copy, but not actually committed. That way you can review the changes and unstage some and then finish the merge by git commit.

Here’s how you do it (for example, merging 4.0 into 4.1):

git merge --no-commit --no-ff origin/4.0
1 Like