git config --global user.name "Frank Chu"
git config --global user.email "fchu@example.com"
+git config --global transfer.fsckObjects true
+
+(See the thread "Recommend these .gitconfig settings for git integrity."
+[https://lists.gnu.org/archive/html/emacs-devel/2016-01/threads.html#01802]
+for more details about why that last line is there.)
Initial setup
=============
Then we want to clone the repository. We normally want to have both
-the current trunk and the emacs-24 branch.
+the current master and the emacs-25 branch.
mkdir ~/emacs
cd ~/emacs
-git clone <membername>@git.sv.gnu.org:/srv/git/emacs.git
-mv emacs trunk
-./trunk/admin/git-new-workdir trunk emacs-24
-cd emacs-24
-git checkout emacs-24
+git clone <membername>@git.sv.gnu.org:/srv/git/emacs.git master
+(cd master; git config push.default current)
+./master/admin/git-new-workdir master emacs-25
+cd emacs-25
+git checkout emacs-25
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
+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 push
-Backporting to emacs-24
+Sending patches
+===============
+
+If you lack push access or would like feedback before pushing a patch,
+you commit your change locally and then send a patch file as a bug report
+as described in ../../CONTRIBUTE.
+
+
+Backporting to emacs-25
=======================
-If you have applied a fix to the trunk, but then decide that it should
-be applied to the emacs-24 branch, too, then
+If you have applied a fix to the master, but then decide that it should
+be applied to the emacs-25 branch, too, then
-cd ~/emacs/trunk
+cd ~/emacs/master
git log
and find the commit you're looking for. Then find the commit ID,
commit 958b768a6534ae6e77a8547a56fc31b46b63710b
-cd ~/emacs/emacs-24
+cd ~/emacs/emacs-25
git cherry-pick -xe 958b768a6534ae6e77a8547a56fc31b46b63710b
and add "Backport:" to the commit string. Then
git push
-Merging emacs-24 to trunk
-=========================
-
-This has yet to be written.
-
+Merging emacs-25 to the master
+==============================
+
+It is recommended to use the file gitmerge.el in the admin directory
+for merging 'emacs-25' 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-25' 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-25', 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-25' 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
=============================