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.
2024-12-24 10:38:38 +00:00 · 2016-02-14 19:24:38 -08:00 · 2016-02-14 19:24:38 -08:00 · f8bf1b35bf
commit f8bf1b35bf
parent f3aaca3552
2 changed files with 126 additions and 123 deletions
--- a/213
+++ b/213
@ -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
-(info "(emacs)Contributing") or
+Here is how software developers can contribute to Emacs.  (Non-developers: see
 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
-documentation to the Emacs repository.  Generally, they have write
-access to the Emacs git repository on Savannah
-https://savannah.gnu.org/git/?group=emacs.
+Emacs development uses Git on Savannah for its main repository.
+Briefly, the following shell commands build and run Emacs from scratch:

-** 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
-giving you write access to the version-control repository.  Request
-access on the emacs-devel@gnu.org mailing list.  Also, be sure to
-subscribe to the emacs-devel@gnu.org mailing list and include the
-"emacs-announce" topic, so that you get the announcements about
-feature freeze and other important events.
+For more details, see
+http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs and
+http://www.emacswiki.org/emacs/GitForEmacsDevs or see the file
+admin/notes/git-workflow.

-** 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
-started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more
-advanced information.
+** Committing changes by others

-Alternately, see admin/notes/git-workflow.
-
-If committing changes written by someone else, make the commit in
-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.
+If committing changes written by someone else, commit in their name,
+not yours.  You can use 'git commit --author="AUTHOR"' to specify a
+change's author.

 ** Commit messages

-Emacs development no longer stores descriptions of new changes in
-ChangeLog files.  Instead, a single ChangeLog file is generated from
-the commit messages when a release is prepared.  So changes you commit
-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):
+Ordinarily, a change you commit should contain a log entry in its
+commit message and should not touch the repository's ChangeLog files.
+Here is an example 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
-messages:
+Occasionally, commit messages are collected and prepended to a
+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
-  ChangeLogs:
-  http://www.gnu.org/prep/standards/html_node/Change-Logs.html or
-  "(info (standards)Change Logs").  One exception is that we still
-  sometimes quote `like-this' (as the standards used to recommend)
-  rather than 'like-this' (as they do now), because `...' is so widely
-  used elsewhere in Emacs.
+- Emacs generally follows the GNU coding standards for ChangeLogs: see
+  http://www.gnu.org/prep/standards/html_node/Change-Logs.html
+  or run 'info "(standards)Change Logs"'.  One exception is that
+  commits still sometimes quote `like-this' (as the standards used to
+  recommend) rather than 'like-this' or ‘like this’ (as they do now),
+  as `...' is so widely used elsewhere in Emacs.

- Some of the rules in the GNU coding standards section 5.2
-  "Commenting Your Work" also apply to ChangeLog entries: they must be
-  in English, and be complete sentences starting with a capital and
-  ending with a period (except the summary line should not end in a
-  period).
+- Some commenting rules in the GNU coding standards also apply
+  to ChangeLog entries: they must be in English, and be complete
+  sentences starting with a capital and ending with a period (except
+  the summary line should not end in a period).  See
+  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
-  ChangeLog entries; see (info "(emacs)Change Log Commands") or
-  http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html.
+- You can use Emacs functions to write ChangeLog entries; see
+  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.
-Sometimes specialized features are developed on separate branches
-before possibly being merged to the trunk.
-
-Development is discussed on the emacs-devel mailing list.
-
-The trunk branch is named "master" in git; release branches are named
-"emacs-nn" where "nn" is the major version.
+Future development normally takes place on the master branch.
+Sometimes specialized features are developed on other branches before
+possibly being merged to the master.  Release branches are named
+"emacs-NN" where NN is the major version number, and are mainly
+intended for more-conservative changes such as bug fixes.  Typically,
+collective development is active on the master branch and possibly on
+the current release branch.  Periodically, the current release branch
+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
-master (eg because the code on master has changed a lot), you can
+However, if you know that the change will be difficult to merge to the
+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
-merge the commit to master; start the commit message with "Backport:".
-gitmerge.el will then exclude that commit from the merge to trunk.
+say in the release branch commit message that there is no need to merge
+the commit to master, by starting the commit message with "Backport:".
+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,
-by following links from http://savannah.gnu.org/mail/?group=emacs .
+The Savannah info page 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
-presented by that page allows to view bug reports and search the
-database for bugs matching several criteria.  Messages posted to the
-bug-gnu-emacs@gnu.org mailing list, mentioned above, are recorded by
-the tracker with the corresponding bugs/issues.
+The Emacs issue tracker at http://debbugs.gnu.org lets you view bug
+reports and search the database for bugs matching several criteria.
+Messages posted to the bug-gnu-emacs@gnu.org mailing list, mentioned
+above, are recorded by 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
-https://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
-for documentation errors before submitting a patch.
+For more specific tips on Emacs's doc style, see
+http://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
+Use 'checkdoc' to check 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
-"(ert)") or https://www.gnu.org/software/emacs/manual/html_node/ert/
-for more information on writing and running tests.
+Emacs uses ERT, Emacs Lisp Regression Testing, for testing.  See
+http://www.gnu.org/software/emacs/manual/html_node/ert/
+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,
-but the nodes "Tips" and "GNU Emacs Internals" in the Appendix
-of the Emacs Lisp Reference Manual may also help.  Some source files,
-such as xdisp.c, have large commentaries describing the design and
-implementation in more detail.
+The best way to understand Emacs internals is to read the code.  Some
+source files, such as xdisp.c, have extensive comments describing the
+design and implementation.  The following resources may also help:
+
+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
-good idea to add a 'coding' cookie to the file to state its encoding.
-Please use the UTF-8 encoding unless it cannot do the job for some
-good reason.  As of Emacs 24.4, it is no longer necessary to have
-explicit 'coding' cookies in *.el files if they are encoded in UTF-8,
-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.
+If you introduce non-ASCII characters into Emacs source files, use the
+UTF-8 encoding unless it cannot do the job for some good reason.
+Although it is generally a good idea to add 'coding:' cookies to
+non-ASCII source files, cookies are not needed in UTF-8-encoded *.el
+files intended for use only with Emacs version 24.5 and later.

 *** 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
-  one.  The commit message on this merge should summarize the renames
-  and all the changes.
+- Merge the feature branch to the master branch, instead of squashing
+  the commits into one.  The commit message on this merge should
+  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:
--- a/admin/notes/git-workflow
+++ b/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
-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
+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.
@ -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
-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,
@ -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