CONTRIBUTE cleanups and updates

* CONTRIBUTE: Mention URLs and info nodes more consistently,
avoiding possibly-confusing punctuation adjacent to a URL, and
giving full shell commands for 'info'.  Start with a brief but
complete how-to, for people who want to get started right away.
Then briefly discuss how to join the development process in the
typical order.  Omit needless words.  Update some of the
now-obsolete file names, info node names, and quoting styles.
Better document emacs-NN branches and how they are merged.
* admin/notes/git-workflow: Change emacs-24 to emacs-25,
and trunk to master.  This file still needs work.

CONTRIBUTE

@@ -1,48 +1,51 @@
-This file contains information on Emacs developer processes.
+* How developers contribute to GNU Emacs
 
-For information on contributing to Emacs as a non-developer, see
+Here is how software developers can contribute to Emacs.  (Non-developers: see
-(info "(emacs)Contributing") or
 http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
+or run the shell command 'info "(emacs)Contributing"'.)
 
-* Information for Emacs Developers.
+** The Emacs repository
 
-An "Emacs Developer" is someone who contributes a lot of code or
+Emacs development uses Git on Savannah for its main repository.
-documentation to the Emacs repository.  Generally, they have write
+Briefly, the following shell commands build and run Emacs from scratch:
-access to the Emacs git repository on Savannah
-https://savannah.gnu.org/git/?group=emacs.
 
-** Write access to the Emacs repository.
+	git config --global user.name 'Your Name'
+	git config --global user.email 'your.name@example.com'
+	git config --global transfer.fsckObjects true
+	git clone git://git.sv.gnu.org/emacs.git
+	cd emacs
+	./autogen.sh
+	./configure
+	make
+	src/emacs
 
-Once you become a frequent contributor to Emacs, we can consider
+For more details, see
-giving you write access to the version-control repository.  Request
+http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs and
-access on the emacs-devel@gnu.org mailing list.  Also, be sure to
+http://www.emacswiki.org/emacs/GitForEmacsDevs or see the file
-subscribe to the emacs-devel@gnu.org mailing list and include the
+admin/notes/git-workflow.
-"emacs-announce" topic, so that you get the announcements about
-feature freeze and other important events.
 
-** Using the Emacs repository
+** Getting involved with development
 
-Emacs uses Git for the source code repository.
+You can subscribe to the emacs-devel@gnu.org mailing list, paying
+attention to postings with subject lines containing "emacs-announce",
+as these discuss important events like feature freezes.  See
+http://lists.gnu.org/mailman/listinfo/emacs-devel for mailing list
+instructions and archives.  You can develop and commit changes in your
+own copy of the repository, and discuss proposed changes on the
+mailing list.  Frequent contributors to Emacs can request write access
+there.
 
-See http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs to get
+** Committing changes by others
-started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more
-advanced information.
 
-Alternately, see admin/notes/git-workflow.
+If committing changes written by someone else, commit in their name,
-
+not yours.  You can use 'git commit --author="AUTHOR"' to specify a
-If committing changes written by someone else, make the commit in
+change's author.
-their name, not yours.  Git distinguishes between the author
-and the committer; use the --author option on the commit command to
-specify the actual author; the committer defaults to you.
 
 ** Commit messages
 
-Emacs development no longer stores descriptions of new changes in
+Ordinarily, a change you commit should contain a log entry in its
-ChangeLog files.  Instead, a single ChangeLog file is generated from
+commit message and should not touch the repository's ChangeLog files.
-the commit messages when a release is prepared.  So changes you commit
+Here is an example commit message (indented):
-should not touch any of the ChangeLog files in the repository, but
-instead should contain the log entries in the commit message.  Here is
-an example of a commit message (indented):
 
 	Deactivate shifted region
 
@@ -53,12 +56,13 @@ an example of a commit message (indented):
 	* src/frame.c (Fhandle_switch_frame, Fselected_frame):
 	Deactivate the mark.
 
-Below are some rules and recommendations for formatting commit
+Occasionally, commit messages are collected and prepended to a
-messages:
+ChangeLog file, where they can be corrected.  It saves time to get
+them right the first time, so here are guidelines for formatting them:
 
 - Start with a single unindented summary line explaining the change;
   do not end this line with a period.  If that line starts with a
-  semi-colon and a space "; ", the log message will be ignored when
+  semicolon and a space "; ", the commit message will be ignored when
   generating the ChangeLog file.  Use this for minor commits that do
   not need separate ChangeLog entries, such as changes in etc/NEWS.
 
@@ -104,19 +108,19 @@ messages:
   the rationale for a change; that can be done in the commit message
   between the summary line and the file entries.
 
-- Emacs generally follows the GNU coding standards when it comes to
+- Emacs generally follows the GNU coding standards for ChangeLogs: see
-  ChangeLogs:
+  http://www.gnu.org/prep/standards/html_node/Change-Logs.html
-  http://www.gnu.org/prep/standards/html_node/Change-Logs.html or
+  or run 'info "(standards)Change Logs"'.  One exception is that
-  "(info (standards)Change Logs").  One exception is that we still
+  commits still sometimes quote `like-this' (as the standards used to
-  sometimes quote `like-this' (as the standards used to recommend)
+  recommend) rather than 'like-this' or ‘like this’ (as they do now),
-  rather than 'like-this' (as they do now), because `...' is so widely
+  as `...' is so widely used elsewhere in Emacs.
-  used elsewhere in Emacs.
 
-- Some of the rules in the GNU coding standards section 5.2
+- Some commenting rules in the GNU coding standards also apply
-  "Commenting Your Work" also apply to ChangeLog entries: they must be
+  to ChangeLog entries: they must be in English, and be complete
-  in English, and be complete sentences starting with a capital and
+  sentences starting with a capital and ending with a period (except
-  ending with a period (except the summary line should not end in a
+  the summary line should not end in a period).  See
-  period).
+  http://www.gnu.org/prep/standards/html_node/Comments.html
+  or run 'info "(standards)Comments"'.
 
   They are preserved indefinitely, and have a reasonable chance of
   being read in the future, so it's better that they have good
@@ -145,15 +149,15 @@ messages:
   will suffice.
 
 - There is no need to mention files such as NEWS and MAINTAINERS, or
-  to indicate regeneration of files such as 'configure', in the
+  to indicate regeneration of files such as 'lib/gnulib.mk', in the
   ChangeLog entry.  "There is no need" means you don't have to, but
   you can if you want to.
 
 ** Generating ChangeLog entries
 
-- You can use various Emacs functions to ease the process of writing
+- You can use Emacs functions to write ChangeLog entries; see
-  ChangeLog entries; see (info "(emacs)Change Log Commands") or
+  http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html
-  http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html.
+  or run 'info "(emacs)Change Log Commands"'.
 
 - If you use Emacs VC, one way to format ChangeLog entries is to create
   a top-level ChangeLog file manually, and update it with 'C-x 4 a' as
@@ -171,32 +175,33 @@ messages:
 
 ** Branches
 
-Development normally takes places on the trunk.
+Future development normally takes place on the master branch.
-Sometimes specialized features are developed on separate branches
+Sometimes specialized features are developed on other branches before
-before possibly being merged to the trunk.
+possibly being merged to the master.  Release branches are named
-
+"emacs-NN" where NN is the major version number, and are mainly
-Development is discussed on the emacs-devel mailing list.
+intended for more-conservative changes such as bug fixes.  Typically,
-
+collective development is active on the master branch and possibly on
-The trunk branch is named "master" in git; release branches are named
+the current release branch.  Periodically, the current release branch
-"emacs-nn" where "nn" is the major version.
+is merged into the master, using the gitmerge function described in
+admin/notes-git-workflow.
 
 If you are fixing a bug that exists in the current release, be sure to
 commit it to the release branch; it will be merged to the master
-branch later.
+branch later by the gitmerge function.
 
-However, if you know that the change will be difficult to merge to
+However, if you know that the change will be difficult to merge to the
-master (eg because the code on master has changed a lot), you can
+master (e.g., because the code on master has changed a lot), you can
 apply the change to both master and branch yourself.  It could also
 happen that a change is cherry-picked from master to the release
 branch, and so doesn't need to be merged back.  In these cases,
-indicate in the release branch commit log that there is no need to
+say in the release branch commit message that there is no need to merge
-merge the commit to master; start the commit message with "Backport:".
+the commit to master, by starting the commit message with "Backport:".
-gitmerge.el will then exclude that commit from the merge to trunk.
+The gitmerge function excludes these commits from the merge to the master.
 
 Some changes should not be merged to master at all, for whatever
 reasons.  These should be marked by including something like "Do not
 merge to master" or anything that matches gitmerge-skip-regexp (see
-gitmerge.el) in the log message.
+admin/gitmerge.el) in the commit message.
 
 ** Other process information
 
@@ -206,10 +211,11 @@ Discussion about Emacs development takes place on emacs-devel@gnu.org.
 
 Bug reports and fixes, feature requests and implementations should be
 sent to bug-gnu-emacs@gnu.org, the bug/feature list.  This is coupled
-to the tracker at http://debbugs.gnu.org .
+to the http://debbugs.gnu.org tracker.
 
-You can subscribe to the mailing lists, or see the list archives,
+The Savannah info page http://savannah.gnu.org/mail/?group=emacs
-by following links from http://savannah.gnu.org/mail/?group=emacs .
+describes how to subscribe to the mailing lists, or see the list
+archives.
 
 To email a patch you can use a shell command like 'git format-patch -1'
 to create a file, and then attach the file to your email.  This nicely
@@ -219,16 +225,15 @@ such patch without additional remarks, you can use a command like
 
 ** Issue tracker (a.k.a. "bug tracker")
 
-The Emacs issue tracker is at http://debbugs.gnu.org/.  The form
+The Emacs issue tracker at http://debbugs.gnu.org lets you view bug
-presented by that page allows to view bug reports and search the
+reports and search the database for bugs matching several criteria.
-database for bugs matching several criteria.  Messages posted to the
+Messages posted to the bug-gnu-emacs@gnu.org mailing list, mentioned
-bug-gnu-emacs@gnu.org mailing list, mentioned above, are recorded by
+above, are recorded by the tracker with the corresponding bugs/issues.
-the tracker with the corresponding bugs/issues.
 
 GNU ELPA has a 'debbugs' package that allows accessing the tracker
 database from Emacs.
 
-** Document your changes.
+** Documenting your changes
 
 Any change that matters to end-users should have an entry in etc/NEWS.
 
@@ -239,21 +244,21 @@ know it does not, mark the NEWS entry with "---".  If you know
 that *all* the necessary documentation updates have been made, mark
 the entry with "+++".  Otherwise do not mark it.
 
-Please see (info "(elisp)Documentation Tips") or
+For more specific tips on Emacs's doc style, see
-https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
+http://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
-for more specific tips on Emacs's doc style.  Use 'checkdoc' to check
+Use 'checkdoc' to check for documentation errors before submitting a patch.
-for documentation errors before submitting a patch.
 
-** Test your changes.
+** Testing your changes
 
 Please test your changes before committing them or sending them to the
 list.  If possible, add a new test along with any bug fix or new
 functionality you commit (of course, some changes cannot be easily
 tested).
 
-Emacs uses ERT, Emacs Lisp Regression Testing, for testing.  See (info
+Emacs uses ERT, Emacs Lisp Regression Testing, for testing.  See
-"(ert)") or https://www.gnu.org/software/emacs/manual/html_node/ert/
+http://www.gnu.org/software/emacs/manual/html_node/ert/
-for more information on writing and running tests.
+or run 'info "(ert)"' for for more information on writing and running
+tests.
 
 If your test lasts longer than some few seconds, mark it in its
 'ert-deftest' definition with ":tags '(:expensive-test)".
@@ -264,27 +269,26 @@ top-level directory.  Most tests are in the directory
 <filename>" to run the tests for <filename>.el(c).  See "test/README"
 for more information.
 
-** Understanding Emacs Internals.
+** Understanding Emacs internals
 
-The best way to understand Emacs Internals is to read the code,
+The best way to understand Emacs internals is to read the code.  Some
-but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
+source files, such as xdisp.c, have extensive comments describing the
-of the Emacs Lisp Reference Manual may also help.  Some source files,
+design and implementation.  The following resources may also help:
-such as xdisp.c, have large commentaries describing the design and
+
-implementation in more detail.
+http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html
+http://www.gnu.org/software/emacs/manual/html_node/elisp/GNU-Emacs-Internals.html
+
+or run 'info "(elisp)Tips"' or 'info "(elisp)GNU Emacs Internals"'.
 
 The file etc/DEBUG describes how to debug Emacs bugs.
 
 *** Non-ASCII characters in Emacs files
 
-If you introduce non-ASCII characters into Emacs source files, it is a
+If you introduce non-ASCII characters into Emacs source files, use the
-good idea to add a 'coding' cookie to the file to state its encoding.
+UTF-8 encoding unless it cannot do the job for some good reason.
-Please use the UTF-8 encoding unless it cannot do the job for some
+Although it is generally a good idea to add 'coding:' cookies to
-good reason.  As of Emacs 24.4, it is no longer necessary to have
+non-ASCII source files, cookies are not needed in UTF-8-encoded *.el
-explicit 'coding' cookies in *.el files if they are encoded in UTF-8,
+files intended for use only with Emacs version 24.5 and later.
-but other files need them even if encoded in UTF-8.  However, if
-an *.el file is intended for use with older Emacs versions (e.g. if
-it's also distributed via ELPA), having an explicit encoding
-specification is still a good idea.
 
 *** Useful files in the admin/ directory
 
@@ -306,15 +310,15 @@ changed heuristic to deduce that a file was renamed.  So if you are
 planning to make extensive changes to a file after renaming it (or
 moving it to another directory), you should:
 
-- create a feature branch
+- Create a feature branch.
 
-- commit the rename without any changes
+- Commit the rename without any changes.
 
-- make other changes
+- Make other changes.
 
-- merge the feature branch to trunk, _not_ squashing the commits into
+- Merge the feature branch to the master branch, instead of squashing
-  one.  The commit message on this merge should summarize the renames
+  the commits into one.  The commit message on this merge should
-  and all the changes.
+  summarize the renames and all the changes.
 
 
 
@@ -336,4 +340,5 @@ along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
 Local variables:
 mode: outline
 paragraph-separate: "[ 	]*$"
+coding: utf-8
 end:

admin/notes/git-workflow

@@ -19,17 +19,15 @@ 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
+git clone <membername>@git.sv.gnu.org:/srv/git/emacs.git master
-mv emacs trunk
+(cd master; git config push.default current)
-(cd trunk; git config push.default current)
+./master/admin/git-new-workdir master emacs-25
-./trunk/admin/git-new-workdir trunk emacs-24
+cd emacs-25
-cd emacs-24
+git checkout emacs-25
-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.
@@ -59,13 +57,13 @@ you commit your change locally and then send a patch file as a bug report
 as described in ../../CONTRIBUTE.
 
 
-Backporting to emacs-24
+Backporting to emacs-25
 =======================
 
-If you have applied a fix to the trunk, but then decide that it should
+If you have applied a fix to the master, but then decide that it should
-be applied to the emacs-24 branch, too, then
+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,
@@ -73,7 +71,7 @@ which will look like
 
 commit 958b768a6534ae6e77a8547a56fc31b46b63710b
 
-cd ~/emacs/emacs-24
+cd ~/emacs/emacs-25
 git cherry-pick -xe 958b768a6534ae6e77a8547a56fc31b46b63710b
 
 and add "Backport:" to the commit string.  Then
@@ -81,17 +79,17 @@ and add "Backport:" to the commit string.  Then
 git push
 
 
-Merging emacs-24 to trunk/master
+Merging emacs-25 to the 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
+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-24' to
+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.
@@ -104,11 +102,11 @@ 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
+'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-24' which are not yet
+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