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
* 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
+is one) and let them get synced to the master; do not install them by
+hand on the master 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.
+install it only on the emacs-24 branch, not on the master 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
+merge to the master (eg because the master code has changed a lot).
+In that case, it's helpful if you can apply the change to both master
and branch yourself (when committing the branch change, indicate
-in the commit log that it should not be merged to the trunk; see below).
+in the commit log that it should not be merged to the master, by
+including the phrase "Not to be merged to master", or any other phrase
+that matches "merge").
* Installing changes from your personal branches.
If your branch has only a single commit, or many different real
commits, it is fine to do a merge. If your branch has only a very
-small number of "real" commits, but several "merge from trunks", it is
-preferred that you take your branch's diff, apply it to the trunk, and
+small number of "real" commits, but several "merge from masters", it is
+preferred that you take your branch's diff, apply it to the master, and
commit directly, not merge. This keeps the history cleaner.
In general, when working on some feature in a separate branch, it is
-preferable not to merge from trunk until you are done with the
+preferable not to merge from master until you are done with the
feature. Unless you really need some change that was done on the
-trunk while you were developing on the branch, you don't really need
+master while you were developing on the branch, you don't really need
those merges; just merge once, when you are done with the feature, and
-Bazaar will take care of the rest. Bazaar is much better in this than
-CVS, so interim merges are unnecessary.
+Git will take care of the rest. Git is much better in this than CVS,
+so interim merges are unnecessary.
Or use shelves; or rebase; or do something else. See the thread for
yet another fun excursion into the exciting world of version control.
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.
+* How to merge changes from emacs-24 to master
-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]
-
-Inspect the change log entries (e.g. in case too many entries have been
-included or whitespace between entries needs fixing). If someone made
-multiple change log entries on different days in the branch, you may
-wish to collapse them all to a single entry for that author in the
-trunk (because in the trunk they all appear under the same date).
-Obviously, if there are multiple changes to the same file by different
-authors, don't break the logical ordering in doing this.
+[The section on git merge procedure has not yet been written.]
You may see conflicts in autoload md5sums in comments. Strictly
speaking, the right thing to do is merge everything else, resolve the
-conflict by choosing either the trunk or branch version, then run
-`make -C lisp autoloads' to update the md5sums to the correct trunk
+conflict by choosing either the master or branch version, then run
+'make -C lisp autoloads' to update the md5sums to the correct master
value before committing.
* Re-adding a file that has been removed from the repository
* Undoing a commit (uncommitting)
-If you have not pushed the commit, you may be able to use `git reset
+If you have not pushed the commit, you may be able to use 'git reset
--hard' with a hash argument to revert the your local repo copy to the
pre-commit state.
If you have pushed commit, resetting will be ineffective because it
-will only vanish the commit in your local copy. Instead, use `git
+will only vanish the commit in your local copy. Instead, use 'git
revert', giving it the commit ID as argument. This will create a
new commit that backs out the change. Then push that.
* Bisecting
This is a semi-automated way to find the revision that introduced a bug.
-Browse `git help bisect' for technical instructions.
+Browse 'git help bisect' for technical instructions.
+
+* Maintaining ChangeLog history
+
+Older ChangeLog entries are kept in history files named ChangeLog.1,
+ChangeLog.2, etc., and can be edited just as any other source files
+can. Newer ChangeLog entries are stored in the repository as commit
+messages, which cannot be edited directly.
+
+'make ChangeLog' copies newer ChangeLog entries into a file
+'ChangeLog' that is intended to be put into the distribution tarball.
+This ChangeLog file is not put into the repository.
+
+'make change-history' copies all newer ChangeLog entries into the
+start of the newest ChangeLog history file. These ChangeLog entries
+are thereafter considered to be old, so later uses of 'make ChangeLog'
+and/or 'make change-history' will no longer copy the entries. To
+alter ChangeLog history, run 'make change-history', then edit
+the ChangeLog history files manually and commit your changes.