Improve CONTRIBUTE and related files.

* CONTRIBUTE: improve; add explicit web references, move some info from
  admin/notes/* here.

* INSTALL.REPO: You can't "just run make" after a clean checkout.

* admin/notes/commits: deleted; merged into ./CONTRIBUTE

* admin/notes/repo: move commit, branch info into ./CONTRIBUTE

5 files changed, 160 insertions, 204 deletions

diff --git a/CONTRIBUTE b/CONTRIBUTE
index b07b6c66af..9c904a798e 100644
--- a/CONTRIBUTE
+++ b/CONTRIBUTE
@@ -12,36 +12,65 @@ new features to add, please suggest them too -- we might like your
 idea.  Porting to new platforms is also useful, when there is a new
 platform, but that is not common nowadays.
 
-For documentation on how to develop Emacs changes, refer to the Emacs
-Manual and the Emacs Lisp Reference Manual (both included in the Emacs
-distribution).  The web pages in http://www.gnu.org/software/emacs
-contain additional information.
+For documentation on Emacs (to understand how to implement your desired change), refer to:
 
-You may also want to submit your change so that can be considered for
-inclusion in a future version of Emacs (see below).
+- the Emacs Manual
+  http://www.gnu.org/software/emacs/manual/emacs.html
+  (info "(Emacs)Top")
 
-If you don't feel up to hacking Emacs, there are many other ways to
-help.  You can answer questions on the mailing lists, write
-documentation, find and report bugs, check if existing bug reports
-are fixed in newer versions of Emacs, contribute to the Emacs web
-pages, or develop a package that works with Emacs.
+- the Emacs Lisp Reference Manual
+  http://www.gnu.org/software/emacs/manual/elisp.html
+  (info "(elisp)Top")
+
+- http://www.gnu.org/software/emacs
+
+- http://www.emacswiki.org/
+
+There are many ways to contribute to Emacs:
+
+- implement a new feature, and submit a patch (see "Submitting
+  Patches" below).
+
+- answer questions on the Emacs user mailing list
+  https://lists.gnu.org/mailman/listinfo/help-gnu-emacs
+
+- write documentation, either on the wiki, or in the Emacs source
+  repository (see "Submitting Patches" below)
+
+- find and report bugs; use M-x report-emacs-bug
+
+- check if existing bug reports are fixed in newer versions of Emacs
+  http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs
+
+- develop a package that works with Emacs, and publish it on your own or in Gnu ELPA.
 
 Here are some style and legal conventions for contributors to Emacs:
 
 
 * Coding Standards
 
-Contributed code should follow the GNU Coding Standards.
+Contributed code should follow the GNU Coding Standards
+(http://www.gnu.org/prep/standards/ - may also be available in info on
+your system).
 
 If it doesn't, we'll need to find someone to fix the code before we
 can use it.
 
-Emacs has certain additional style and coding conventions.
+Emacs has additional style and coding conventions:
+
+- the "Tips" Appendix in the Emacs Lisp Reference
+  http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html
+  (info "(elisp)Tips").
 
-Ref: http://www.gnu.org/prep/standards/
-Ref: GNU Coding Standards Info Manual
-Ref: The "Tips" Appendix in the Emacs Lisp Reference.
+- Avoid using `defadvice' or `eval-after-load' for Lisp code to be
+  included in Emacs.
 
+- Remove all trailing whitespace in all source and text files.
+
+- Emacs has no convention on whether to use tabs in source code, but
+  please don't change whitespace in the files you edit.
+
+- Use ?\s instead of ?  in Lisp code for a space character.
 
 * Copyright Assignment
 
@@ -75,19 +104,18 @@ patches) over all your contributions.
 
 * Getting the Source Code
 
-The latest version of the Emacs source code can be downloaded from the
-Savannah web site.  It is important to write your patch based on the
-latest version.  If you start from an older version, your patch may be
-outdated (so that maintainers will have a hard time applying it), or
-changes in Emacs may have made your patch unnecessary.
+The current working version of the Emacs source code is stored in a
+git repository on the Savannah web site
+(http://savannah.gnu.org/projects/emacs).  It is important to write
+your patch based on the current working version.  If you start from an
+older version, your patch may be outdated (so that maintainers will
+have a hard time applying it), or changes in Emacs may have made your
+patch unnecessary.
 
 After you have downloaded the repository source, you should read the file
 INSTALL.REPO for build instructions (they differ to some extent from a
 normal build).
 
-Ref: http://savannah.gnu.org/projects/emacs
-
-
 * Submitting Patches
 
 Every patch must have several pieces of information before we
@@ -112,11 +140,12 @@ For new features, a description of the feature and your implementation.
 A ChangeLog entry as plaintext (separate from the patch).
 
 See the existing ChangeLog files for format and content.  Note that,
-unlike some other projects, we do require ChangeLogs also for
+unlike some other projects, we do require ChangeLogs for
 documentation, i.e. Texinfo files.
 
 Ref: "Change Log Concepts" node of the GNU Coding Standards Info
 Manual, for how to write good log entries.
+http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html
 
 When using git, commit messages should use ChangeLog format, with a
 single short line explaining the change, then an empty line, then
@@ -154,27 +183,106 @@ Making cosmetic formatting changes (indentation, etc) makes it harder
 to see what you have really changed.
 
 
-* Coding style and conventions.
+* Supplemental information for Emacs Developers.
 
-** Mandatory reading:
+An "Emacs Developer" is someone who contributes a lot of code or
+documentation to the Emacs repository.
 
-The "Tips and Conventions" Appendix of the Emacs Lisp Reference.
+** Write access to the Emacs repository.
 
-** Avoid using `defadvice' or `eval-after-load' for Lisp code to be
-included in 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.
 
-** Remove all trailing whitespace in all source and text files.
+** Using the Emacs repository
 
-** Use ?\s instead of ?  in Lisp code for a space character.
+Emacs uses git for the source code repository.
 
+See http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs to get
+started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more
+advanced information.
 
-* Supplemental information for Emacs Developers.
+Alternately, see admin/notes/git-workflow.
 
-** Write access to the Emacs repository.
+If committing changes written by someone else, make the ChangeLog
+entry 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.
 
-Once you become a frequent contributor to Emacs, we can consider
-giving you write access to the version-control repository.
+** Changelog notes
+
+- Preferred form for several entries with the same content:
+
+   * help.el (view-lossage):
+   * kmacro.el (kmacro-edit-lossage):
+   * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys.
+
+  (Rather than anything involving "ditto" and suchlike.)
+
+- Emacs generally follows the GNU coding standards when it comes to
+  ChangeLogs:
+  http://www.gnu.org/prep/standards/html_node/Change-Logs.html .  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.
+
+- There are multiple ChangeLogs in the emacs source; roughly one per
+  high-level directory. The ChangeLog entry for a commit belongs in the
+  lowest ChangeLog that is higher than or at the same level as any file
+  changed by the commit.
+
+- In ChangeLog files, there is no standard or recommended way to
+  identify revisions.
+
+  One way to identify revisions is by quoting their summary line.
+  Another is with an action stamp - an RFC3339 date followed by !
+  followed by the committer's email - for example,
+  "2014-01-16T05:43:35Z!esr@thyrsus.com". Often, "my previous commit"
+  will suffice.
+
+- There is no need to make separate change log entries for files such
+  as NEWS, MAINTAINERS, and FOR-RELEASE, or to indicate regeneration
+  of files such as 'configure'.  "There is no need" means you don't
+  have to, but you can if you want to.
+
+** 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.
+
+Sometime before the release of a new major version of Emacs a "feature
+freeze" is imposed on the trunk, to prepare for creating a release
+branch.  No new features may be added to the trunk after this point,
+until the release branch is created. This freeze is announced on the
+emacs-devel mailing list, and not anywhere else.
+
+For example, "emacs-23" for Emacs 23.2 and later, "EMACS_23_1_RC" for
+23.1, "EMACS_22_BASE" for 22.x, and "EMACS_21_1_RC" for 21.x.
+
+You must follow emacs-devel to know exactly what kinds of changes are
+allowed on what branch at any time. Announcements about the freeze
+(and other important events) will contain "ANNOUNCE" in the subject.
+
+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.
+
+The exception is, if you know that the change will be difficult to
+merge to the trunk (eg because the trunk code has changed a lot).  In
+that case, it's helpful if you can apply the change to both trunk and
+branch yourself.  Indicate in the release branch commit log that there
+is no need to merge the commit to the trunk; start the commit message
+with "Backport:".  This is helpful for the person merging the release
+branch to the trunk (it is handled automatically by gitmerge.el).
+
+
+** Other process information
 
+See all the files in admin/notes/* . In particular, see
+admin/notes/newfile, see admin/notes/repo.
 
 ** Emacs Mailing lists.
 
@@ -189,7 +297,7 @@ by following links from http://savannah.gnu.org/mail/?group=emacs .
 
 ** Document your changes.
 
-Any change that matters to end-users should have a NEWS entry.
+Any change that matters to end-users should have an entry in etc/NEWS.
 
 Think about whether your change requires updating the documentation
 (both manuals and doc-strings).  If you know it does not, mark the NEWS
diff --git a/ChangeLog b/ChangeLog
index 166e0e9611..ba0880c618 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2014-12-05  Stephen Leake  <stephen_leake@stephe-leake.org>
+
+	* CONTRIBUTE: improve, move some info from admin/notes/* here.
+
+2014-12-05  Stephen Leake  <stephen_leake@stephe-leake.org>
+
+	* etc/CONTRIBUTE: renamed to ./CONTRIBUTE, preparatory to further
+	changes/cleanup
+
 2014-12-05  Paul Eggert  <eggert@cs.ucla.edu>
 
 	* .gitignore: Remove redundant pattern (subsumed by _*).
diff --git a/INSTALL.REPO b/INSTALL.REPO
index 83b6f2f413..67dceb8c6e 100644
--- a/INSTALL.REPO
+++ b/INSTALL.REPO
@@ -1,10 +1,5 @@
 	     Building and Installing Emacs from the Repository
 
-Simply run 'make'.  This should work if your files are freshly checked
-out from the repository, and if you have the proper tools installed.
-If it doesn't work, or if you have special build requirements, the
-following information may be helpful.
-
 Building Emacs from the source-code repository requires some tools
 that are not needed when building from a release.  You will need:
 
@@ -34,6 +29,12 @@ can invoke './configure -C'.  After configuring, build Emacs as follows:
 If you want to install Emacs, type 'make install' instead of 'make' in
 the last command.
 
+After your first build, you can usually just run 'make' after any
+updates from the Savannah repository or local edits; the makefile
+contains logic to re-run configure as needed. However, if the autoconf
+input files have changed, or in some other situations, you will need
+to run 'make bootstrap' (more below).
+
 Occasionally the file 'lisp/loaddefs.el' (and similar automatically
 generated files, such as 'esh-groups.el', and '*-loaddefs.el' in some
 subdirectories of 'lisp/', e.g., 'mh-e/' and 'calendar/') will need to be
diff --git a/admin/notes/commits b/admin/notes/commits
deleted file mode 100644
index f33c6905d4..0000000000
--- a/admin/notes/commits
+++ /dev/null
@@ -1,70 +0,0 @@
-HOW TO COMMIT CHANGES TO EMACS
-
-Most of these points are from:
-
-http://lists.gnu.org/archive/html/emacs-devel/2009-03/msg00555.html
-From: 	 Miles Bader
-Subject: commit style redux
-Date: 	 Tue, 31 Mar 2009 12:21:20 +0900
-
-(0) Each commit should correspond to a single change (whether spread
-    over multiple files or not).  Do not mix different changes in the
-    same commit (eg adding a feature in one file, fixing a bug in
-    another should be two commits, not one).
-
-(1) Commit all changed files at once with a single log message (which
-    in CVS will result in an identical log message for all committed
-    files), not one-by-one.  This is pretty easy using vc-dir now.
-
-(2) Make the log message describe the entire changeset, perhaps
-    including relevant changelog entries (I often don't bother with
-    the latter if it's a trivial sort of change).
-
-    Many modern source-control systems vaguely distinguish the first
-    line of the log message to use as a short summary for abbreviated
-    history listing (in arch this was explicitly called the summary,
-    but many other systems have a similar concept).  So it's nice if
-    you can format the log entry like:
-
-        SHORTISH ONE-LINE SUMMARY
-
-        MULTIPLE-LINE DETAILED DESCRIPTION POSSIBLY INCLUDING (OR
-        CONSISTING OF) CHANGELOG ENTRIES
-
-    [Even with CVS this style is useful, because web CVS browsing
-    interfaces often include the first N words of the log message of
-    the most recent commit as a short "most recent change"
-    description.]
-
-(3) Don't phrase log messages assuming the filename is known, because
-    in non-file-oriented systems (everything modern other than CVS),
-    the log listing tends to be treated as global information, and the
-    connection with specific files is less explicit.
-
-    For instance, currently I often see log messages like "Regenerate";
-    for modern source-control systems with a global log, it's better to
-    have something like "Regenerate configure".
-
-(4) (Added in 2014) In commit comments, and ChangeLog files, it is best
-    to use ways of identifying revisions that are not dependent on a
-    particular version control system.  (At time of writing Emacs is
-    about to move to its fourth VCS and another move in the future is
-    not impossible.)  An excellent way to identify commits is by
-    quoting their summary line.  Another is with an action stamp - an
-    RFC3339 date followed by ! followed by the committer's email - for
-    example, "2014-01-16T05:43:35Z!esr@thyrsus.com". Often, "my
-    previous commit" will suffice.
-
-Followup discussion:
-http://lists.gnu.org/archive/html/emacs-devel/2010-01/msg00897.html
-http://lists.gnu.org/archive/html/emacs-devel/2010-02/msg00401.html
-
-
-PREVIOUS GUIDELINES FOR CVS
-
-For historical interest only, here is the old-style advice for CVS logs:
-http://lists.gnu.org/archive/html/emacs-devel/2007-12/msg01208.html
-
-From: Eli Zaretskii
-Subject: Re: Log messages in CVS
-Date: Sat, 29 Dec 2007 16:06:29 +0200
diff --git a/admin/notes/repo b/admin/notes/repo
index 97b4349ed6..2d4cc2a55c 100644
--- a/admin/notes/repo
+++ b/admin/notes/repo
@@ -1,70 +1,5 @@
 NOTES ON COMMITTING TO EMACS'S REPOSITORY    -*- outline -*-
 
-* Commit metainformation
-
-** Commit in the author's name
-
-If installing changes written by someone else, commit them in their
-name, not yours.
-
-** Commit message format
-
-Commit messages should follow the conventions used in all modern
-distributed version-control systems. That is, they should consist of
-
-- A self-contained topic line, preferably no more than 75 chars long.
-
-- If other content follows the topic line, there should be a blank
-  line separating the two.
-
-- Follow the blank line with ChangeLog-like entries for the specific
-  changes you made, if any.  (As long as Emacs maintains ChangeLog
-  files, just copy the entries you made in them to the commit message
-  after the blank line.)
-
-- Preferred form for several entries with the same content:
-
-   * help.el (view-lossage):
-   * kmacro.el (kmacro-edit-lossage):
-   * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys.
-
-  (Rather than anything involving "ditto" and suchlike.)
-
-- Emacs generally follows the GNU coding standards when it comes to ChangeLogs:
-  http://www.gnu.org/prep/standards/html_node/Change-Logs.html
-  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.
-  http://lists.gnu.org/archive/html/emacs-devel/2014-05/msg00514.html
-
-** Unnecessary metainformation
-
-There is no need to make separate change log entries for files such as
-NEWS, MAINTAINERS, and FOR-RELEASE, or to indicate regeneration of
-files such as 'configure'.  "There is no need" means you don't have
-to, but you can if you want to.
-
-* Commit to the right branch
-
-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.
-
-Sometime before the release of a new major version of Emacs
-a "feature freeze" is imposed on the trunk.  No new features may be
-added after this point.  This is usually some months before the release.
-
-Shortly before the release, a release branch is created, and the
-trunk is then free for development.
-
-For example, "emacs-23" for Emacs 23.2 and later, "EMACS_23_1_RC" for
-23.1, "EMACS_22_BASE" for 22.x, and "EMACS_21_1_RC" for 21.x.
-
-Consult emacs-devel for exactly what kinds of changes are allowed
-on what branch at any time.
-
 ** elpa
 
 This branch does not contain a copy of Emacs, but of the Emacs Lisp
@@ -72,25 +7,6 @@ package archive (elpa.gnu.org).  See admin/notes/elpa for further
 explanation, and the README file in the branch for usage
 instructions.
 
-* Install changes only on one branch, let them get merged elsewhere if needed.
-
-In particular, install bug-fixes only on the release branch (if there
-is one) and let them get synced to the trunk; do not install them by
-hand on the trunk as well.  E.g. if there is an active "emacs-24" branch
-and you have a bug-fix appropriate for the next emacs-24.x release,
-install it only on the emacs-24 branch, not on the trunk as well.
-
-Installing things manually into more than one branch makes merges more
-difficult.
-
-http://lists.gnu.org/archive/html/emacs-devel/2010-03/msg01124.html
-
-The exception is, if you know that the change will be difficult to
-merge to the trunk (eg because the trunk code has changed a lot).
-In that case, it's helpful if you can apply the change to both trunk
-and branch yourself (when committing the branch change, indicate
-in the commit log that it should not be merged to the trunk; see below).
-
 * Installing changes from your personal branches.
 
 If your branch has only a single commit, or many different real
@@ -129,14 +45,6 @@ variable in admin/merge-gnulib before running it.
 If you remove a gnulib module, or if a gnulib module
 removes a file, then remove the corresponding files by hand.
 
-* Backporting a bug-fix from the trunk to a branch (e.g. "emacs-24").
-
-Indicate in the commit log that there is no need to merge the commit
-to the trunk, e.g. start the commit message with "Backport:".  This is
-helpful for the person merging the release branch to the trunk.
-
-http://lists.gnu.org/archive/html/emacs-devel/2010-05/msg00262.html
-
 * How to merge changes from emacs-24 to trunk
 
 [The section on git merge procedure has not yet been written]