Minor edits in CONTRIBUTE
* CONTRIBUTE: Rearrange instructions about log messages. Use "Git" capitalized all over. Use 2 spaces between sentences.
This commit is contained in:
Eli Zaretskii
parent
934968a2ad
commit
c4e0ba5155
1 changed files with 64 additions and 53 deletions
117
CONTRIBUTE
117
CONTRIBUTE
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue