From bb21df9a15aeb32482959c57b84a9cf5ba6d4c23 Mon Sep 17 00:00:00 2001 From: Stephen Leake Date: Fri, 19 Dec 2014 11:18:50 -0600 Subject: [PATCH] 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 * lisp/startup.el (fancy-about-text): change buttons for etc/CONTRIBUTE to (info "(emacs)Contributing") --- CONTRIBUTE | 267 ++++++++++++++----------------------------------- ChangeLog | 19 ++++ doc/emacs/trouble.texi | 240 ++++++++++++++++++++++++++++++++++++++++---- lisp/startup.el | 8 +- 4 files changed, 317 insertions(+), 217 deletions(-) diff --git a/CONTRIBUTE b/CONTRIBUTE index dc6fd71..a190bd9 100644 --- a/CONTRIBUTE +++ b/CONTRIBUTE @@ -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. diff --git a/ChangeLog b/ChangeLog index ee109f7..8e74c02 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,22 @@ +2014-12-19 Stephen Leake + + 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-06 Stephen Leake * CONTRIBUTE: Improve; add explicit web references, move some info diff --git a/doc/emacs/trouble.texi b/doc/emacs/trouble.texi index 5f3cf92..bae9cad 100644 --- a/doc/emacs/trouble.texi +++ b/doc/emacs/trouble.texi @@ -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. + +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 +the Emacs Manual +@url{http://www.gnu.org/software/emacs/manual/emacs.html}. +@end ifhtml +@ifnothtml +@xref{Top, Emacs Manual,,emacs}. +@end ifnothtml +@end ifset +@ifclear WWW_GNU_ORG +@xref{Top, Emacs Manual,,emacs}. +@end ifclear + +@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 -For more information on how to contribute, see the +@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 -@url{http://gnu.org/software/emacs/CONTRIBUTE, etc/CONTRIBUTE} +the "Tips" Appendix in the Emacs Lisp Reference +@url{http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html}. @end ifhtml @ifnothtml -@file{etc/CONTRIBUTE} +@xref{Tips, "Tips" Appendix in the Emacs Lisp Reference, Tips +Appendix, elisp, Emacs Lisp Reference}. @end ifnothtml @end ifset @ifclear WWW_GNU_ORG -@file{etc/CONTRIBUTE} +@xref{Tips, "Tips" Appendix in the Emacs Lisp Reference, Tips +Appendix, elisp, Emacs Lisp Reference}. @end ifclear -file in the Emacs distribution. + +@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 diff --git a/lisp/startup.el b/lisp/startup.el index c04b16c..8e981bb 100644 --- a/lisp/startup.el +++ b/lisp/startup.el @@ -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") -- 2.1.1