Document merge workflow for contributors and maintainers. [skip ci]

1 files changed, 37 insertions, 0 deletions

diff --git a/docs/markdown/Contributing.md b/docs/markdown/Contributing.md
index 7b5fe73..7559c00 100644
--- a/docs/markdown/Contributing.md
+++ b/docs/markdown/Contributing.md
@@ -18,6 +18,17 @@ Github](https://github.com/mesonbuild/meson/pulls). This causes them
 to be run through the CI system. All submissions must pass a full CI
 test run before they are even considered for submission.
 
+## Keeping pull requests up to date
+
+It is possible that while your pull request is being reviewed, other
+changes are committed to master that cause merge conflicts that must
+be resolved. The basic rule for this is very simple: keep your pull
+request up to date using rebase _only_.
+
+Do not merge head back to your branch. Any merge commits in your pull
+request make it not acceptable for merging into master and you must
+remove them.
+
 ## Acceptance and merging
 
 The kind of review and acceptance any merge proposal gets depends on
@@ -57,6 +68,32 @@ In a simplified list form the split would look like the following:
    - changes breaking backwards compatibility
    - support for new languages
 
+## Strategy for merging pull requests to trunk
+
+Meson's merge strategy should fullfill the following guidelines:
+
+- preserve as much history as possible
+
+- have as little junk in the repo as possible
+
+- everything in the "master lineage" should always pass all tests
+
+These goals are slightly contradictory so the correct thing to do
+often requires some judgement on part of the person doing the
+merge. Github provides three different merge options, The rules of
+thumb for choosing between them goes like this:
+
+ - single commit pull requests should always be rebased
+
+ - a pull request with one commit and one "fixup" commit (such as
+   testing something to see if it passes CI) should be squashed
+
+ - large branches with many commits should be merged with a merge
+   commit, especially if one of the commits does not pass all tests
+   (which happens in e.g. large and difficult refactorings)
+
+If in doubt, ask for guidance on IRC.
+
 ## Tests
 
 All new features must come with automatic tests that thoroughly prove