From 05230057480fda26723ceef3497235ed0a8d0cca Mon Sep 17 00:00:00 2001 From: "Kim F. Storm" Date: Sun, 9 Jul 2006 00:22:37 +0000 Subject: Use outline format. Add section on copyright years (from admin/notes/years). --- CONTRIBUTE | 216 ++++++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 142 insertions(+), 74 deletions(-) (limited to 'CONTRIBUTE') diff --git a/CONTRIBUTE b/CONTRIBUTE index 8b69ccd0983..e1fb74c8df6 100644 --- a/CONTRIBUTE +++ b/CONTRIBUTE @@ -25,112 +25,180 @@ pages, or develop a package that works with Emacs. Here are some style and legal conventions for contributors to Emacs: -o Coding Standards +* Coding Standards - 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. +Contributed code should follow the GNU Coding Standard. - Emacs has certain additional style and coding conventions. +If it doesn't, we'll need to find someone to fix the code before we +can use it. - Ref: http://www.gnu.org/prep/standards_toc.html - Ref: GNU Coding Standards Info Manual +Emacs has certain additional style and coding conventions. +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 - 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. +* Copyright Assignment - Contact us at emacs-devel@gnu.org to obtain the relevant - forms. +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. -o 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. +* Getting the Source Code - 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). +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. - Ref: http://savannah.gnu.org/projects/emacs +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 -o Submitting Patches - Every patch must have several pieces of information before we - can properly evaluate it. +* Submitting Patches - * For bug fixes, a description of the bug and how your patch - fixes this bug. +Every patch must have several pieces of information before we +can properly evaluate it. - * For new features, a description of the feature and your - implementation. +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. - * 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. +All subsequent discussion should also be sent to the mailing list. - Ref: "Change Log Concepts" node of the GNU Coding Standards - Info Manual, for how to write good log entries. +** Description - * 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. +For bug fixes, a description of the bug and how your patch fixes this +bug. - * We accept the patches as plain text (preferred for the - compilers themselves), MIME attachments (preferred for the - web pages), or as uuencoded gzipped text. +For new features, a description of the feature and your +implementation. - 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. +** ChangeLog +A ChangeLog entry as plaintext (separate from the patch). -o Please reread your patch before submitting it. +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. -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. +** The patch itself. +Please use "Context Diff" format. -o Supplemental information for Emacs Developers: +If you are accessing the CVS repository use + cvs update; cvs diff -cp +else, use + diff -cp OLD NEW - Once you become a frequent contributor to Emacs, we can - consider giving you write access to the CVS repository. +If your version of diff does not support these options, then get the +latest version of GNU Diff. - Discussion about Emacs development takes place on - emacs-devel@gnu.org. +** Mail format. - 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. +We prefer to get the patches as inline plain text. - 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.) +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. - 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. +** Please reread your patch before submitting it. - The file etc/DEBUG describes how to debug Emacs bugs. +** 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. + + +* 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. + + +* 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. + + +** Document your changes. + +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. + +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.) + + +** 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. + + + +* 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." + +** 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. + + +Local variables: +mode: outline +paragraph-separate: "[ ]*$" +end: - Avoid using `defadvice' or `eval-after-load' for Lisp - code to be included in Emacs. -- cgit v1.2.1