1 files changed, 135 insertions, 0 deletions
diff --git a/admin/notes/git-workflow b/admin/notes/git-workflow
new file mode 100644
index 00000000000..d1d105a8a7a
--- /dev/null
+++ b/admin/notes/git-workflow
@@ -0,0 +1,135 @@
+(This is a draft.  The method here won't actually work yet, because
+neither git-new-workdir nor merge-changelog are in the Emacs
+distribution yet.)
+
+Setting up and using git for normal, simple bugfixing
+=====================================================
+
+If you haven't configured git before you should first do:
+
+git config --global user.name "Frank Chu"
+git config --global user.email "fchu@example.com"
+
+Initial setup
+=============
+
+Then we want to clone the repository.  We normally want to have both
+the current trunk and the emacs-24 branch.
+
+mkdir ~/emacs
+cd ~/emacs
+git clone <membername>@git.sv.gnu.org:/srv/git/emacs.git
+mv emacs trunk
+(cd trunk; git config push.default current)
+./trunk/admin/git-new-workdir trunk emacs-24
+cd emacs-24
+git checkout emacs-24
+git config push.default current
+
+You now have both branches conveniently accessible, and you can do
+"git pull" in them once in a while to keep updated.
+
+
+Fixing bugs
+===========
+
+You edit the files in either branch, `M-x vc-dir', and check in your
+changes.  Then you need to push the data to the main repository.  This
+will usually fail, since somebody else has pushed other changes in the
+meantime.  To fix this, say
+
+git pull --rebase
+
+which will update your repository, and then re-apply your changes on
+top of that.  Then say
+
+git push
+
+
+Backporting to emacs-24
+=======================
+
+If you have applied a fix to the trunk, but then decide that it should
+be applied to the emacs-24 branch, too, then
+
+cd ~/emacs/trunk
+git log
+
+and find the commit you're looking for.  Then find the commit ID,
+which will look like
+
+commit 958b768a6534ae6e77a8547a56fc31b46b63710b
+
+cd ~/emacs/emacs-24
+git cherry-pick -xe 958b768a6534ae6e77a8547a56fc31b46b63710b
+
+and add "Backport:" to the commit string.  Then
+
+git push
+
+
+Merging emacs-24 to trunk/master
+================================
+
+It is recommended to use the file gitmerge.el in the admin directory
+for merging 'emacs-24' into 'master'.  It will take care of many
+things which would otherwise have to be done manually, like ignoring
+commits that should not land in master, fixing up ChangeLogs and
+automatically dealing with certain types of conflicts.  If you really
+want to, you can do the merge manually, but then you're on your own.
+If you still choose to do that, make absolutely sure that you *always*
+use the 'merge' command to transport commits from 'emacs-24' to
+'master'.  *Never* use 'cherry-pick'!  If you don't know why, then you
+shouldn't manually do the merge in the first place; just use
+gitmerge.el instead.
+
+How to use gitmerge.el:
+
+Enter the Emacs repository, checkout 'master' and make sure it's
+up-to-date by doing a pull.  Then start Emacs with
+
+  emacs -l admin/gitmerge.el -f gitmerge
+
+You'll be asked for the branch to merge, which will default to
+'origin/emacs-24', which you should accept.  Merging a local tracking
+branch is discouraged, since it might not be up-to-date, or worse,
+contain commits from you which are not yet pushed upstream.
+
+You will now see the list of commits from 'emacs-24' which are not yet
+merged to 'master'.  You might also see commits that are already
+marked for "skipping", which means that they will be merged with a
+different merge strategy ('ours'), which will effectively ignore the
+commit's diff while still being seen as merged, so it won't turn up
+again in future merges.  Recognizing these kinds of commits is done
+with a simple regexp searching the log for strings like 'backport' or
+'merge', so you'll probably see false positives as well as false
+negatives.  Carefully go through the commits, investigate them by
+hitting 'l', 'd' and 'f', and mark or unmark them for skipping with
+'s'.  When you're done, hit 'm' to start the merge.
+
+You'll likely get conflicts during the process which cannot be dealt
+with automatically.  In that case, the merge will stop and show you
+the list of conflicted files.  Resolve those conflicts as usual using
+smerge and restart gitmerge (remember to enter the repository when
+doing that).  You don't have to 'add' the resolved files and 'commit'
+the resulting merge, but if you really want to, feel free to do that.
+Note you can also resume gitmerge in a new Emacs session, since the
+current state will be saved to disk.
+
+When everything's done, look hard at the resulting merge.  Skipping
+commits requires separate merges, so don't be surprised to see more
+than one merge commit.  If you're happy, push.
+
+Warnings about X11 forwarding
+=============================
+
+If you get warnings like
+
+Warning: No xauth data; using fake authentication data for X11 forwarding.
+X11 forwarding request failed on channel 0
+
+when pulling or pushing data, add the following to the start of
+~/.ssh/config:
+
+Host git.sv.gnu.org
+   ForwardX11 no