# HG changeset patch # User Kim F. Storm # Date 1152404557 0 # Node ID a99d8ae1c5d91f4a88ed7abafc24739f42615773 # Parent 23f3ba5373bc246954be15ee6bee1bf1d323d75f Use outline format. Add section on copyright years (from admin/notes/years). diff -r 23f3ba5373bc -r a99d8ae1c5d9 CONTRIBUTE --- a/CONTRIBUTE Sun Jul 09 00:22:22 2006 +0000 +++ b/CONTRIBUTE Sun Jul 09 00:22:37 2006 +0000 @@ -25,112 +25,180 @@ Here are some style and legal conventions for contributors to Emacs: -o Coding Standards +* Coding Standards + +Contributed code should follow the GNU Coding Standard. - Contributed code should follow the GNU Coding Standard. - If it doesn't, we'll need to find someone to fix the code - before we can use it. +If it doesn't, we'll need to find someone to fix the code before we +can use it. - Emacs has certain additional style and coding conventions. +Emacs has certain additional style and coding conventions. - Ref: http://www.gnu.org/prep/standards_toc.html - Ref: GNU Coding Standards Info Manual +Ref: http://www.gnu.org/prep/standards_toc.html +Ref: GNU Coding Standards Info Manual +Ref: The "Tips" Appendix in the Emacs Lisp Reference. -o Copyright Assignment +* Copyright Assignment - We can accept small changes without legal papers, and for - medium-size changes a copyright disclaimer is ok too. To - accept substantial contributions from you, we need a copyright - assignment form filled out and filed with the FSF. +We can accept small changes without legal papers, and for medium-size +changes a copyright disclaimer is ok too. To accept substantial +contributions from you, we need a copyright assignment form filled out +and filed with the FSF. - Contact us at emacs-devel@gnu.org to obtain the relevant - forms. +Contact us at emacs-devel@gnu.org to obtain the relevant forms. -o Getting the Source Code +* Getting the Source Code - The latest version of Emacs can be downloaded using CVS or - Arch from the Savannah web site. It is important to write - your patch based on this version; if you start from an older - version, your patch may be outdated when you write it, and - maintainers will have hard time applying it. +The latest version of Emacs can be downloaded using CVS or Arch from +the Savannah web site. It is important to write your patch based on +this version; if you start from an older version, your patch may be +outdated when you write it, and maintainers will have hard time +applying it. - After you have downloaded the CVS source, you should read the - file INSTALL.CVS for build instructions (they differ to some - extent from a normal build). +After you have downloaded the CVS source, you should read the file +INSTALL.CVS for build instructions (they differ to some extent from a +normal build). - Ref: http://savannah.gnu.org/projects/emacs +Ref: http://savannah.gnu.org/projects/emacs -o Submitting Patches +* Submitting Patches + +Every patch must have several pieces of information before we +can properly evaluate it. - 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 emacs-pretest-bug@gnu.org or emacs-devel@gnu.org. - * For bug fixes, a description of the bug and how your patch - fixes this bug. +All subsequent discussion should also be sent to the mailing list. + +** Description - * For new features, a description of the feature and your - implementation. +For bug fixes, a description of the bug and how your patch fixes this +bug. + +For new features, a description of the feature and your +implementation. - * A ChangeLog entry as plaintext (separate from the patch); - see the various ChangeLog files for format and content. Note - that, unlike some other projects, we do require ChangeLogs - also for documentation, i.e. Texinfo files. +** ChangeLog + +A ChangeLog entry as plaintext (separate from the patch). + +See the various ChangeLog files for format and content. Note that, +unlike some other projects, we do require ChangeLogs also 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. +Ref: "Change Log Concepts" node of the GNU Coding Standards Info +Manual, for how to write good log entries. + +** The patch itself. + +Please use "Context Diff" format. - * The patch itself. If you are accessing the CVS repository - use "cvs update; cvs diff -cp"; else, use "diff -cp OLD NEW". - If your version of diff does not support these options, then - get the latest version of GNU Diff. +If you are accessing the CVS repository use + cvs update; cvs diff -cp +else, use + diff -cp OLD NEW + +If your version of diff does not support these options, then get the +latest version of GNU Diff. - * We accept the patches as plain text (preferred for the - compilers themselves), MIME attachments (preferred for the - web pages), or as uuencoded gzipped text. +** Mail format. + +We prefer to get the patches as inline plain text. - When you have all these pieces, bundle them up in a mail message - and send it to emacs-pretest-bug@gnu.org or emacs-devel@gnu.org. - All subsequent discussion should also be sent to the mailing - list. +Please be aware of line wrapping which will make the patch unreadable +and useless for us. To avoid that, you can use MIME attachments or, +as a last resort, uuencoded gzipped text. + +** 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. -o Please reread your patch before submitting it. +* Coding style and conventions. + +** Mandatory reading: + +The "Tips and Conventions" Appendix of the Emacs Lisp Reference. + +** 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. + +** Use ?\s instead of ? in Lisp code for a space character. -o If you send several unrelated changes together, we will - ask you to separate them so we can consider each of the changes - by itself. +* Supplemental information for Emacs Developers. + +** Write access to Emacs' CVS repository. + +Once you become a frequent contributor to Emacs, we can consider +giving you write access to the CVS repository. + + +** Emacs Mailing lists. + +Discussion about Emacs development takes place on emacs-devel@gnu.org. + +Bug reports for released versions are sent to emacs-bugs@gnu.org. + +Bug reports for development versions are sent to emacs-pretest-bug@gnu.org. + +You can subscribe to the mailing lists at savannah.gnu.org/projects/emacs. + +You can find the mailing lists archives at mail.gnu.org or gmane.org. -o Supplemental information for Emacs Developers: +** Document your changes. - Once you become a frequent contributor to Emacs, we can - consider giving you write access to the CVS repository. +Think carefully about whether your change requires updating the +documentation. If it does, you can either do this yourself or add an +item to the NEWS file. - Discussion about Emacs development takes place on - emacs-devel@gnu.org. +If you document your change in NEWS, please mark the NEWS entry with +the documentation status of the change: if you submit the changes for +the manuals, mark it with "+++"; if it doesn't need to be documented, +mark it with "---"; if it needs to be documented, but you didn't +submit documentation changes, leave the NEWS entry unmarked. (These +marks are checked by the Emacs maintainers to make sure every change +was reflected in the manuals.) - Think carefully about whether your change requires updating the - documentation. If it does, you can either do this yourself or - add an item to the NEWS file. + +** Understanding Emacs Internals. + +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. + +The file etc/DEBUG describes how to debug Emacs bugs. - If you document your change in NEWS, please mark the NEWS - entry with the documentation status of the change: if you - submit the changes for the manuals, mark it with "+++"; if it - doesn't need to be documented, mark it with "---"; if it needs - to be documented, but you didn't submit documentation changes, - leave the NEWS entry unmarked. (These marks are checked by - the Emacs maintainers to make sure every change was reflected - in the manuals.) + + +* How to Maintain Copyright Years for GNU Emacs + +** Our lawyer says it is ok if we add, to each file that has been in Emacs +since Emacs 21 came out in 2001, all the subsequent years. We don't +need to check whether *that file* was changed in those years. +It's sufficient that *Emacs* was changed in those years (and it was!). + +** For those files that have been added since then, we should add +the year it was added to Emacs, and all subsequent years." - 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. +** For the refcards under etc/, it's ok to simply use the latest year +(typically in a `\def\year{YEAR}' expression) for the rendered copyright +notice, while maintaining the full list of years in the copyright notice +in the comments. - The file etc/DEBUG describes how to debug Emacs bugs. + +Local variables: +mode: outline +paragraph-separate: "[ ]*$" +end: - Avoid using `defadvice' or `eval-after-load' for Lisp - code to be included in Emacs.