1 files changed, 97 insertions, 0 deletions
diff --git a/_doc/upmerge.rst b/_doc/upmerge.rst
new file mode 100644
index 0000000..1f93bf9
--- /dev/null
+++ b/_doc/upmerge.rst
@@ -0,0 +1,97 @@
+*************
+Upstrem Merge
+*************
+
+The process to merge ``ruamel.yaml``'s Mercurial repository to ours is
+non-trivial due to non-unique Mergurial-to-git imports and squash merges.
+
+Preparation
+===========
+
+We create a git import of the Upstream repository. Then we add a
+pseudo-merge node to it which represents our version of the code
+at the point where the last merge happened. The commit we want is most
+likely named "Upstream 0.xx.yy".
+
+So, first we get a git copy of an HG clone of the ``ruamel.yaml``
+repository::
+
+    # install Mercurial (depends on your distribution)
+
+    cd /your/src
+    mkdir -p ruyaml/git
+    cd ruyaml/git; git init
+    cd ../
+    hg clone http://hg.code.sf.net/p/ruamel-yaml/code hg
+
+Next we prepare our repository for merging. We need a ``hg-fast-export``
+script::
+
+    cd ..
+    git clone git@github.com:frej/fast-export.git
+
+We use that script to setup our git copy::
+
+    cd ../git
+    ../fast-export/hg-fast-export.sh -r ../hg --ignore-unnamed-heads
+
+Now let's create a third repository for the actual work::
+
+    cd ../
+    git clone git@github.com:pycontribs/ruyaml.git repo
+    cd repo
+    git remote add ../git ruamel
+    git fetch ruamel
+
+Create a branch for merging::
+
+    git checkout -b merge main
+
+This concludes setting things up.
+
+Incremental merge
+=================
+
+First, let's pull the remote changes (if any)::
+
+    cd /your/src/ruyaml/hg
+    hg pull
+    cd ../git
+    ../fast-export/hg-fast-export.sh -r ../hg --ignore-unnamed-heads
+    cd ../repo
+    git fetch --all
+    git checkout merge
+
+Next, we need a pseudo-merge that declares "we have merged all of Upstream
+up to *THAT* into *THIS*", where *THIS* is the latest Merge commit in our
+repository (typically named "Upstream 0.xx.yy") and *THAT* is the
+corresponding commit in the Ruamel tree (it should be tagged 0.xx.yy)::
+
+    git log --date-order --all --oneline
+    git reset --hard THIS
+    git merge -s ours THAT
+
+Now we'll "merge" the current Upstream sources::
+
+    git merge --squash ruamel/main
+
+This will create a heap of conflicts, but no commit yet.
+
+.. note::
+
+    The reason we do a squash-merge here is that otherwise git will
+    un-helpfully upload the complete history of ``ruamel.yaml`` to GitHub.
+    It's already there, of course, but due to the diverging git hashes that
+    doesn't help.
+
+The next step, obviously, is to fix the conflicts. (There will be a bunch.)
+If git complains about a deleted ``__init__.py``, the solution is to ``git
+rm -f __init__.py``.
+
+Then, commit your changes::
+
+    git commit -a -m "Merge Upstream 0.xx.yz"
+    git push -f origin merge
+
+Now check github. If everything is OK, congratulations, otherwise fix and
+push (no need to repeat the ``-f``).