X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/6f82a6d0b7379202e688518538179bdf2b5c4c50..c534076ccd2f07aaeb8e22e1c825f40bbefd9e82:/CONTRIBUTE diff --git a/CONTRIBUTE b/CONTRIBUTE index f54f45bb1a..e1fb74c8df 100644 --- a/CONTRIBUTE +++ b/CONTRIBUTE @@ -1,122 +1,204 @@ Contributing to Emacs -Emacs is a collaborative project and one which wants to encourage new -development. You may wish to fix Emacs bugs, improve testing, port -Emacs to a new platform, update documentation, add new Emacs features, -and the like. To help with this, there is a lot of documentation -available. In addition to the user guide and Lisp Reference Manual in -the Emacs distribution, the Emacs web pages also contain much -information. +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 how to develop Emacs changes, refer to the Emacs +Manual and the Emacs Lisp Reference Manual (both included in the Emacs +distribution). The web pages in http://www.gnu.org/software/emacs +contain additional information. You may also want to submit your change so that can be considered for inclusion in a future version of Emacs (see below). -If you don't feel up to hacking Emacs, there are still plenty of ways to -help! You can answer questions on the mailing lists, write -documentation, find bugs, create a Emacs related website (contribute to -the official Emacs web site), or create a Emacs related software -package. We welcome all of the above and feel free to ask on the Emacs -mailing lists if you are looking for feedback or for people to review a -work in progress. +If you don't feel up to hacking Emacs, there are many other ways to +help. You can answer questions on the mailing lists, write +documentation, find and report bugs, contribute to the Emacs web +pages, or develop a package that works with Emacs. -Ref: http://www.gnu.org/software/emacs/ +Here are some style and legal conventions for contributors to Emacs: -Finally, there are certain legal requirements and style issues which -all contributors need to be aware of: +* Coding Standards -o Coding Standards +Contributed code should follow the GNU Coding Standard. - All contributions must conform to the GNU Coding Standard. - Submissions which do not conform to the standards will be - returned with a request to reformat the changes. +If it doesn't, we'll need to find someone to fix the code before we +can use it. - Emacs has certain additional coding requirements. +Emacs has certain additional style and coding conventions. - Ref: http://www.gnu.org/prep/standards_toc.html - Ref: 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 - Before we can accept code 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 via the Emacs mailing list to obtain the relevant - forms. +Contact us at emacs-devel@gnu.org to obtain the relevant forms. - Small changes can be accepted without a copyright assignment - form on file. +* Getting the Source Code -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. - The latest version of Emacs can be downloaded using CVS or Arch - from the Savannah web site. It is important that you submit - your patch using this version, as any bug in a released version - of Emacs may already be fixed. It also makes it easier for - others to test your patch. - - 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 Standards Info Manual +** 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 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 read 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. - A patch containing several unrelated changes reformats will be - returned with a request to send them separately. - +Ref: "Change Log Concepts" node of the GNU Coding Standards Info +Manual, for how to write good log entries. -o Supplemental information for Emacs Developers: +** The patch itself. - If you wish to contribute to Emacs on a regular basis then you - may be given write access to the CVS repository. - - Discussion about Emacs development takes place on - emacs-devel@gnu.org. +Please use "Context Diff" 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. +If you are accessing the CVS repository use + cvs update; cvs diff -cp +else, use + diff -cp OLD NEW - 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. +If your version of diff does not support these options, then get the +latest version of GNU Diff. - The file DEBUG describes how to debug Emacs. +** Mail format. + +We prefer to get the patches as inline plain text. + +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. + + +* 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.