procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Move user-level information from CONTRIBUTE to doc/emacs/trouble.texi

Browse source 
Fixes bug#19299

* CONTRIBUTE: Move user-level information to doc/emacs/trouble.texi
  (commit messages): new, gathered from comments on emacs-devel
  (Changelog notes): add reference to GNU coding standards section 5.2;
  doc 'present tense', bug fix format
  (branches): freeze announcements are made on info-gnu-emacs mailing
  list
  (git vs rename): new

* doc/emacs/trouble.texi: Move user-level information from CONTRIBUTE here

* lisp/startup.el (fancy-about-text): change buttons for etc/CONTRIBUTE
  to (info "(emacs)Contributing")
This commit is contained in:
Stephen Leake 2014-12-23 13:11:45 -06:00
parent 061f310c4a
commit fcb978e240
4 changed files with 317 additions and 217 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

267
CONTRIBUTE
View file

@ -1,196 +1,14 @@
Copyright (C) 2006-2014 Free Software Foundation, Inc.
See end for license conditions.
This file contains information on Emacs developer processes.
For information on contributing to Emacs as a non-developer, see
(info "(emacs)Contributing") or
http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
Contributing to Emacs
Emacs is a collaborative project and we encourage contributions from
anyone and everyone. If you want to contribute in the way that will
help us most, we recommend (1) fixing reported bugs and (2)
implementing the feature ideas in etc/TODO. However, if you think of
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 Emacs (to understand how to implement your
desired change), refer to:
- the Emacs Manual
http://www.gnu.org/software/emacs/manual/emacs.html
(info "(Emacs)Top")
- 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 (see admin/notes/elpa).
Here are some style and legal conventions for contributors to Emacs:
* 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 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").
- 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;
please don't change whitespace in the files you edit.
- Use ?\s instead of ? in Lisp code for a space character.
* Copyright Assignment
The FSF (Free Software Foundation) is the copyright holder for GNU Emacs.
The FSF is a nonprofit with a worldwide mission to promote computer
user freedom and to defend the rights of all free software users.
For general information, see the website http://www.fsf.org/ .
Generally speaking, for non-trivial contributions to GNU Emacs we
require that the copyright be assigned to the FSF. For the reasons
behind this, see: http://www.gnu.org/licenses/why-assign.html .
Copyright assignment is a simple process. Residents of some countries
can do it entirely electronically. We can help you get started, and
answer any questions you may have (or point you to the people with the
answers), at the emacs-devel@gnu.org mailing list.
(Please note: general discussion about why some GNU projects ask
for a copyright assignment is off-topic for emacs-devel.
See gnu-misc-discuss instead.)
A copyright disclaimer is also a possibility, but we prefer an assignment.
Note that the disclaimer, like an assignment, involves you sending
signed paperwork to the FSF (simply saying "this is in the public domain"
is not enough). Also, a disclaimer cannot be applied to future work, it
has to be repeated each time you want to send something new.
We can accept small changes (roughly, fewer than 15 lines) without
an assignment. This is a cumulative limit (e.g. three separate 5 line
patches) over all your contributions.
* Getting the Source Code
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).
* Submitting Patches
Every patch must have several pieces of information before we
can properly evaluate it.
When you have all these pieces, bundle them up in a mail message and
send it to the developers. Sending it to bug-gnu-emacs@gnu.org
(which is the bug/feature list) is recommended, because that list
is coupled to a tracking system that makes it easier to locate patches.
If your patch is not complete and you think it needs more discussion,
you might want to send it to emacs-devel@gnu.org instead. If you
revise your patch, send it as a followup to the initial topic.
** Description
For bug fixes, a description of the bug and how your patch fixes it.
For new features, a description of the feature and your implementation.
** ChangeLog
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 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
unindented ChangeLog entries. (Essentially, a commit message should
be a duplicate of what the patch adds to the ChangeLog files. We are
planning to automate this better, to avoid the duplication.) You can
use the Emacs functions log-edit-add-to-changelog or
log-edit-insert-changelog to ease this process.
** The patch itself.
If you are accessing the Emacs repository, make sure your copy is
up-to-date (e.g. with 'git pull'). You can commit your changes
to a private branch and generate a patch from the master version
by using
git format-patch master
Or you can leave your changes uncommitted and use
git diff
With no repository, you can use
diff -u OLD NEW
** Mail format.
We prefer to get the patches as plain text, either inline (be careful
your mail client does not change line breaks) or as MIME attachments.
** Please reread your patch before submitting it.
** Do not mix changes.
If you send several unrelated changes together, we will ask you to
separate them so we can consider each of the changes by itself.
** Do not make formatting changes.
Making cosmetic formatting changes (indentation, etc) makes it harder
to see what you have really changed.
* Supplemental information for Emacs Developers.
* Information for Emacs Developers.
An "Emacs Developer" is someone who contributes a lot of code or
documentation to the Emacs repository.
documentation to the Emacs repository. Generally, they have write
access to the Emacs git repository on Savannah.
** Write access to the Emacs repository.
@ -213,6 +31,31 @@ 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.
** commit messages
When using git, commit messages should use ChangeLog format, with the
following modifications:
- Add a single short line explaining the change, then an empty line,
then unindented ChangeLog entries.
You can use various Emacs functions to ease this process; see (info
"(emacs)Change Log Commands") or
http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html.
- The summary line is limited to 72 characters (enforced by a commit
hook). If you have trouble making that a good summary, add a
paragraph below it, before the individual file descriptions.
- If only a single file is changed, the summary line can be the normal
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.
** Changelog notes
- Emacs generally follows the GNU coding standards when it comes to
@ -222,11 +65,25 @@ specify the actual author; the committer defaults to you.
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
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).
It is tempting to relax this rule for commit messages, since they
are somewhat transient. However, they are preserved indefinitely,
and have a reasonable chance of being read in the future, so it's
better that they have good presentation.
- 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.
- Use the present tense; describe "what the change does", not "what
the change did".
- Preferred form for several entries with the same content:
* help.el (view-lossage):
@ -235,7 +92,13 @@ specify the actual author; the committer defaults to you.
(Rather than anything involving "ditto" and suchlike.)
- In ChangeLog files, there is no standard or recommended way to
- If the commit fixes a bug, add a separate line
Fixes: bug#NNNN
where NNNN is the bug number.
- In ChangeLog entries, there is no standard or recommended way to
identify revisions.
One way to identify revisions is by quoting their summary line.
@ -244,7 +107,7 @@ specify the actual author; the committer defaults to you.
"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
- There is no need to make separate ChangeLog 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.
@ -266,9 +129,8 @@ emacs-devel mailing list, and not anywhere else.
The trunk branch is named "master" in git; release branches are named
"emacs-nn" where "nn" is the major version.
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.
Announcements about the freeze (and other important events) are made
on the info-gnu-emacs mailing list.
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
@ -287,6 +149,23 @@ then exclude that commit from the merge to trunk.
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
planning to make extensive changes to a file after renaming it (or
moving it to another directory), you should:
- create a feature branch
- commit the rename without any 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.
** Emacs Mailing lists.
Discussion about Emacs development takes place on emacs-devel@gnu.org.

19
ChangeLog
View file

@ -1,3 +1,22 @@
2014-12-19 Stephen Leake <stephen_leake@stephe-leake.org>
Move user-level information from CONTRIBUTE to doc/emacs/trouble.texi
Fixes bug#19299
* CONTRIBUTE: Move user-level information to doc/emacs/trouble.texi
(commit messages): new, gathered from comments on emacs-devel
(Changelog notes): add reference to GNU coding standards section 5.2;
doc 'present tense', bug fix format
(branches): freeze announcements are made on info-gnu-emacs mailing
list
(git vs rename): new
* doc/emacs/trouble.texi: Move user-level information from CONTRIBUTE here
* lisp/startup.el (fancy-about-text): change buttons for etc/CONTRIBUTE
to (info "(emacs)Contributing")
2014-12-14 Paul Eggert <eggert@cs.ucla.edu>
Spelling fixes

240
doc/emacs/trouble.texi
View file

@ -1060,19 +1060,44 @@ but using it will take extra work. Maintaining GNU Emacs is a lot of
work in the best of circumstances, and we can't keep up unless you do
your best to help.
Every patch must have several pieces of information before we
can properly evaluate it.
When you have all these pieces, bundle them up in a mail message and
send it to the developers. Sending it to
@email{bug-gnu-emacs@@gnu.org} (which is the bug/feature list) is
recommended, because that list is coupled to a tracking system that
makes it easier to locate patches. If your patch is not complete and
you think it needs more discussion, you might want to send it to
@email{emacs-devel@@gnu@@gnu.org} instead. If you revise your patch,
send it as a followup to the initial topic.
We prefer to get the patches as plain text, either inline (be careful
your mail client does not change line breaks) or as MIME attachments.
@itemize @bullet
@item
Send an explanation with your changes of what problem they fix or what
improvement they bring about. For a fix for an existing bug, it is
Include an explanation with your changes of what problem they fix or what
improvement they bring about.
@itemize
@item
For a fix for an existing bug, it is
best to reply to the relevant discussion on the @samp{bug-gnu-emacs}
list, or the bug entry in the GNU Bug Tracker at
@url{http://debbugs.gnu.org}. Explain why your change fixes the bug.
@item
Always include a proper bug report for the problem you think you have
fixed. We need to convince ourselves that the change is right before
installing it. Even if it is correct, we might have trouble
understanding it if we don't have a way to reproduce the problem.
For a new feature, include a description of the feature and your
implementation.
@item
For a new bug, include a proper bug report for the problem you think
you have fixed. We need to convince ourselves that the change is
right before installing it. Even if it is correct, we might have
trouble understanding it if we don't have a way to reproduce the
problem.
@end itemize
@item
Include all the comments that are appropriate to help people reading the
@ -1104,6 +1129,8 @@ right away. That gives us the option of installing it immediately if it
is important.
@item
The patch itself.
Use @samp{diff -c} to make your diffs. Diffs without context are hard
to install reliably. More than that, they are hard to study; we must
always study a patch to decide whether we want to install it. Unidiff
@ -1114,6 +1141,12 @@ If you have GNU diff, use @samp{diff -c -F'^[_a-zA-Z0-9$]+ *('} when
making diffs of C code. This shows the name of the function that each
change occurs in.
If you are using the Emacs repository, make sure your copy is
up-to-date (e.g. with @code{git pull}). You can commit your changes
to a private branch and generate a patch from the master version by
using @code{git format-patch master}. Or you can leave your changes
uncommitted and use @code{git diff}.
@item
Avoid any ambiguity as to which is the old version and which is the new.
Please make the old version the first argument to diff, and the new
@ -1138,8 +1171,16 @@ feel that the purpose needs explaining, it probably does---but put the
explanation in comments in the code. It will be more useful there.
Please look at the change log entries of recent commits to see what
sorts of information to put in, and to learn the style that we use.
@xref{Change Log}.
sorts of information to put in, and to learn the style that we use. Note that,
unlike some other projects, we do require change logs for
documentation, i.e. Texinfo files.
@xref{Change Log},
@ifset WWW_GNU_ORG
see
@url{http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html},
@end ifset
@xref{Change Log Concepts, Change Log Concepts,
Change Log Concepts, gnu-coding-standards, GNU Coding Standards}.
@item
When you write the fix, keep in mind that we can't install a change that
@ -1160,11 +1201,52 @@ Please help us keep up with the workload by designing the patch in a
form that is clearly safe to install.
@end itemize
@c FIXME: Include the node above?
@node Contributing
@section Contributing to Emacs Development
@cindex contributing to Emacs
Emacs is a collaborative project and we encourage contributions from
anyone and everyone.
There are many ways to contribute to Emacs:
@itemize
@item
find and report bugs; @xref{Bugs}.
@item
answer questions on the Emacs user mailing list
@url{https://lists.gnu.org/mailman/listinfo/help-gnu-emacs}.
@item
write documentation, either on the wiki, or in the Emacs source
repository (@pxref{Sending Patches}).
@item
check if existing bug reports are fixed in newer versions of Emacs
@url{http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs}.
@item
fix existing bug reports
@url{http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs}.
@item
@c etc/TOOD not in WWW_GNU_ORG
implement a feature listed in the @file{etc/TODO} file in the Emacs
distribution, and submit a patch.
@item
implement a new feature, and submit a patch.
@item
develop a package that works with Emacs, and publish it on your own
or in Gnu ELPA (@url{https://elpa.gnu.org/}).
@item
port Emacs to a new platform, but that is not common nowadays.
@end itemize
If you would like to work on improving Emacs, please contact the maintainers at
@ifnothtml
@email{emacs-devel@@gnu.org}.
@ -1186,24 +1268,148 @@ you have not yet started work, it is useful to contact
before you start; it might be possible to suggest ways to make your
extension fit in better with the rest of Emacs.
When implementing a feature, please follow the Emacs coding standards;
@xref{Coding Standards}. In addition, non-trivial contributions
require a copyright assignment to the FSF; @xref{Copyright Assignment}.
The development version of Emacs can be downloaded from the
repository where it is actively maintained by a group of developers.
See the Emacs project page
@url{http://savannah.gnu.org/projects/emacs/} for details.
@url{http://savannah.gnu.org/projects/emacs/} for access details.
For more information on how to contribute, see the
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
@file{INSTALL.REPO} for build instructions (they differ to some extent
from a normal build).
If you would like to make more extensive contributions, see the
@file{./CONTRIBUTE} file in the Emacs distribution for information on
how to be an Emacs developer.
For documentation on Emacs (to understand how to implement your
desired change), refer to:
@itemize
@item
@ifset WWW_GNU_ORG
@ifhtml
@url{http://gnu.org/software/emacs/CONTRIBUTE, etc/CONTRIBUTE}
the Emacs Manual
@url{http://www.gnu.org/software/emacs/manual/emacs.html}.
@end ifhtml
@ifnothtml
@file{etc/CONTRIBUTE}
@xref{Top, Emacs Manual,,emacs}.
@end ifnothtml
@end ifset
@ifclear WWW_GNU_ORG
@file{etc/CONTRIBUTE}
@xref{Top, Emacs Manual,,emacs}.
@end ifclear
file in the Emacs distribution.
@item
@ifset WWW_GNU_ORG
@ifhtml
the Emacs Lisp Reference Manual
@url{http://www.gnu.org/software/emacs/manual/elisp.html}.
@end ifhtml
@ifnothtml
@xref{Top, Emacs Lisp Reference Manual,,elisp}.
@end ifnothtml
@end ifset
@ifclear WWW_GNU_ORG
@xref{Top, Emacs Lisp Reference Manual,,elisp}.
@end ifclear
@item
@url{http://www.gnu.org/software/emacs}
@item
@url{http://www.emacswiki.org/}
@end itemize
@menu
* Coding Standards:: Gnu Emacs coding standards
* Copyright Assignment:: assigning copyright to the FSF
@end menu
@node Coding Standards
@subsection Coding Standards
@cindex coding standards
Contributed code should follow the GNU Coding Standards
@url{http://www.gnu.org/prep/standards/}. This 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 additional style and coding conventions:
@itemize
@item
@ifset WWW_GNU_ORG
@ifhtml
the "Tips" Appendix in the Emacs Lisp Reference
@url{http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html}.
@end ifhtml
@ifnothtml
@xref{Tips, "Tips" Appendix in the Emacs Lisp Reference, Tips
Appendix, elisp, Emacs Lisp Reference}.
@end ifnothtml
@end ifset
@ifclear WWW_GNU_ORG
@xref{Tips, "Tips" Appendix in the Emacs Lisp Reference, Tips
Appendix, elisp, Emacs Lisp Reference}.
@end ifclear
@item
Avoid using @code{defadvice} or @code{eval-after-load} for Lisp code
to be included in Emacs.
@item
Remove all trailing whitespace in all source and text files.
@item
Emacs has no convention on whether to use tabs in source code; please
don't change whitespace in the files you edit.
@item
Use @code{?\s} instead of @code{? } in Lisp code for a space character.
@end itemize
@node Copyright Assignment
@subsection Copyright Assignment
@cindex copyright assignment
The FSF (Free Software Foundation) is the copyright holder for GNU Emacs.
The FSF is a nonprofit with a worldwide mission to promote computer
user freedom and to defend the rights of all free software users.
For general information, see the website @url{http://www.fsf.org/}.
Generally speaking, for non-trivial contributions to GNU Emacs we
require that the copyright be assigned to the FSF. For the reasons
behind this, see @url{http://www.gnu.org/licenses/why-assign.html}.
Copyright assignment is a simple process. Residents of some countries
can do it entirely electronically. We can help you get started, and
answer any questions you may have (or point you to the people with the
answers), at the @email{emacs-devel@@gnu.org} mailing list.
(Please note: general discussion about why some GNU projects ask
for a copyright assignment is off-topic for emacs-devel.
See gnu-misc-discuss instead.)
A copyright disclaimer is also a possibility, but we prefer an assignment.
Note that the disclaimer, like an assignment, involves you sending
signed paperwork to the FSF (simply saying "this is in the public domain"
is not enough). Also, a disclaimer cannot be applied to future work, it
has to be repeated each time you want to send something new.
We can accept small changes (roughly, fewer than 15 lines) without
an assignment. This is a cumulative limit (e.g. three separate 5 line
patches) over all your contributions.
@node Service
@section How To Get Help with GNU Emacs
@ -1211,8 +1417,8 @@ file in the Emacs distribution.
@cindex help-gnu-emacs mailing list
@cindex gnu.emacs.help newsgroup
If you need help installing, using or changing GNU Emacs, there are two
ways to find it:
If you need help installing, using or changing GNU Emacs, there are
two ways to find it:
@itemize @bullet
@item

8
lisp/startup.el
View file

@ -1463,9 +1463,7 @@ Each element in the list should be a list of strings or pairs
(goto-char (point-min))))
"\tMany people have contributed code included in GNU Emacs\n"
:link ("Contributing"
,(lambda (_button)
(view-file (expand-file-name "CONTRIBUTE" data-directory))
(goto-char (point-min))))
,(lambda (_button) (info "(emacs)Contributing")))
"\tHow to contribute improvements to Emacs\n"
"\n"
:link ("GNU and Freedom" ,(lambda (_button) (describe-gnu-project)))
@ -2039,9 +2037,7 @@ Type \\[describe-distribution] for information on "))
(insert-button "Contributing"
'action
(lambda (_button)
(view-file (expand-file-name "CONTRIBUTE" data-directory))
(goto-char (point-min)))
(lambda (_button) (info "(emacs)Contributing"))
'follow-link t)
(insert "\tHow to contribute improvements to Emacs\n\n")