Commit f8bf1b35 authored by Paul Eggert's avatar Paul Eggert

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.
parent f3aaca35
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. 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
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.
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:
......@@ -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
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment