Commit c4e0ba51 authored by Eli Zaretskii's avatar Eli Zaretskii

Minor edits in CONTRIBUTE

* CONTRIBUTE: Rearrange instructions about log messages.
Use "Git" capitalized all over.
Use 2 spaces between sentences.
parent 934968a2
......@@ -7,19 +7,22 @@ http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
* Information for Emacs Developers.
An "Emacs Developer" is someone who contributes a lot of code or
documentation to the Emacs repository. Generally, they have write
documentation to the Emacs repository. Generally, they have write
access to the Emacs git repository on Savannah
https://savannah.gnu.org/git/?group=emacs.
** Write access to the Emacs repository.
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.
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.
** Using the Emacs repository
Emacs uses git for the source code repository.
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
......@@ -28,16 +31,18 @@ advanced information.
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
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
When a release is prepared, the commit messages are used to generate
the ChangeLog file. So a typical patch does not touch any of the
ChangeLog files in the repository, but contains the ChangeLog entries
in its message. Here is an example commit message (indented):
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):
Deactivate shifted region
......@@ -48,10 +53,17 @@ in its message. Here is an example commit message (indented):
* src/frame.c (Fhandle_switch_frame, Fselected_frame):
Deactivate the mark.
The general format is as follows.
Below are some rules and recommendations for formatting commit
messages:
- Start with a single unindented summary line explaining the change,
then an empty line, then unindented ChangeLog entries.
- 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
generating the ChangeLog file. Use this for minor commits that do
not need separate ChangeLog entries, such as changes in etc/NEWS.
- After the summary line, there should be an empty line, then
unindented ChangeLog entries.
- Limit lines in commit messages to 78 characters, unless they consist
of a single word of at most 140 characters; this is enforced by a
......@@ -64,22 +76,37 @@ The general format is as follows.
file first line (starting with the asterisk). Then there is no
individual files section.
- Explaining the rationale for a design choice is best done in comments
in the source code. However, sometimes it is useful to describe just
the rationale for a change; that can be done in the commit message
between the summary line and the file entries.
- If the commit has authors other than yourself, the commit message
should contain a separate line like the following:
Co-authored-by: Joe Schmoe <j.schmoe@example.org>
- If the commit is a tiny change that is exempt from copyright paperwork,
the commit message should contain a separate line like the following:
Copyright-paperwork-exempt: yes
- The commit message should contain "Bug#NNNNN" if it is related to
bug number NNNNN in the debbugs database. This string is often
parenthesized, as in "(Bug#19003)".
- Commit messages should contain only printable UTF-8 characters.
- Commit messages should not contain the "Signed-off-by:" lines that
are used in some other projects.
- Explaining the rationale for a design choice is best done in comments
in the source code. However, sometimes it is useful to describe just
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 . 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://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.
- Some of the rules in the GNU coding standards section 5.2
"Commenting Your Work" also apply to ChangeLog entries: they must be
......@@ -102,27 +129,15 @@ The general format is as follows.
(Rather than anything involving "ditto" and suchlike.)
- If the commit has authors other than yourself, the commit message
should contain a separate line like the following:
Co-authored-by: Joe Schmoe <j.schmoe@example.org>
- If the commit is a tiny change that is exempt from copyright paperwork,
the commit message should contain a separate line like the following:
Copyright-paperwork-exempt: yes
- The commit message should contain "Bug#NNNNN" if it is related to
bug number NNNNN in the debbugs database. This string is often
parenthesized, as in "(Bug#19003)".
- In ChangeLog entries, there is no standard or recommended way to
identify revisions.
- There is no standard or recommended way to identify revisions in
ChangeLog entries. Using Git SHA1 values limits the usability of
the references to Git, and will become much less useful if Emacs
switches to a different VCS. So we recommend against that.
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"
"2014-01-16T05:43:35Z!esr@thyrsus.com". Often, "my previous commit"
will suffice.
- There is no need to mention files such as NEWS, MAINTAINERS, and
......@@ -130,12 +145,6 @@ The general format is as follows.
'configure', in the ChangeLog entry. "There is no need" means you
don't have to, but you can if you want to.
- If a commit message's first line starts with "; ", the message is
ignored when generating ChangeLog history files via 'make ChangeLog'
or via 'make change-history'. You can use "; " for minor commits
that do not need separate ChangeLog entries, as well as commits that
only modify files that don't need these entries at all.
** Generating ChangeLog entries
- You can use various Emacs functions to ease the process of writing
......@@ -156,7 +165,7 @@ The general format is as follows.
with Emacs commands like 'C-x 4 a', and commit the change using the
shell command 'vc-dwim --commit'. Type 'vc-dwim --help' for more.
** branches
** Branches
Development normally takes places on the trunk.
Sometimes specialized features are developed on separate branches
......@@ -167,9 +176,9 @@ 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. Announcements about the freeze
(and other important events) are made on the info-gnu-emacs mailing
list, and not anywhere else.
until the release branch is created. Announcements about the freeze
(and other important events) are made on the emacs-devel mailing
list under the "emacs-announce" topic, and not anywhere else.
The trunk branch is named "master" in git; release branches are named
"emacs-nn" where "nn" is the major version.
......@@ -188,13 +197,13 @@ then exclude that commit from the merge to trunk.
** Other process information
See all the files in admin/notes/* . In particular, see
See all the files in admin/notes/* . In particular, see
admin/notes/newfile, see admin/notes/repo.
*** git vs rename
git does not explicitly represent a file renaming; it uses a percent
changed heuristic to deduce that a file was renamed. So if you are
Git does not explicitly represent a file renaming; it uses a percent
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:
......@@ -205,7 +214,7 @@ moving it to another directory), you should:
- 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
one. The commit message on this merge should summarize the renames
and all the changes.
** Emacs Mailing lists.
......@@ -232,7 +241,7 @@ Doc-strings should be updated together with the code.
Think about whether your change requires updating the manuals. If you
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.
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
......@@ -258,7 +267,9 @@ top-level directory. Most tests are in the directory
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.
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 file etc/DEBUG describes how to debug Emacs bugs.
......
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