X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/44d5226a2cedb7e585fd6ab5290902c69154238a..f9acac751d4cd22480e62cc63936b1208ca9fe48:/CONTRIBUTE diff --git a/CONTRIBUTE b/CONTRIBUTE index 0f7fe6855b..0e019d3159 100644 --- a/CONTRIBUTE +++ b/CONTRIBUTE @@ -1,178 +1,189 @@ -Copyright (C) 2006, 2007 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 +* Information for Emacs Developers. -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. +An "Emacs Developer" is someone who contributes a lot of code or +documentation to the Emacs repository. Generally, they have write +access to the Emacs git repository on Savannah +https://savannah.gnu.org/git/?group=emacs. -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. +** Write access to the Emacs repository. -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 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. - -Here are some style and legal conventions for contributors to Emacs: - - -* 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. - -Emacs has certain additional style and coding conventions. +Once you become a frequent contributor to Emacs, we can consider +giving you write access to the version-control repository. Request +access on the emacs-devel@gnu.org mailing list. -Ref: http://www.gnu.org/prep/standards_toc.html -Ref: GNU Coding Standards Info Manual -Ref: The "Tips" Appendix in the Emacs Lisp Reference. +** Using the Emacs repository +Emacs uses git for the source code repository. -* Copyright Assignment +See http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs to get +started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more +advanced information. -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. +Alternately, see admin/notes/git-workflow. -Contact us at emacs-devel@gnu.org to obtain the relevant forms. +If committing changes written by someone else, make the ChangeLog +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 -* Getting the Source Code +When using git, commit messages should use ChangeLog format, with the +following modifications: -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. +- Add a single short line explaining the change, then an empty line, + then unindented ChangeLog entries. -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). + 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. -Ref: http://savannah.gnu.org/projects/emacs +- 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. -* Submitting Patches +- 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. -Every patch must have several pieces of information before we -can properly evaluate it. +** ChangeLog notes -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. +- Emacs generally follows the GNU coding standards when it comes to + ChangeLogs: + http://www.gnu.org/prep/standards/html_node/Change-Logs.html . One + exception is that we still sometimes quote `like-this' (as the + standards used to recommend) rather than 'like-this' (as they do + now), because `...' is so widely used elsewhere in Emacs. -All subsequent discussion should also be sent to the mailing list. +- 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). -** Description + 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. -For bug fixes, a description of the bug and how your patch fixes this -bug. +- 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. -For new features, a description of the feature and your -implementation. +- Use the present tense; describe "what the change does", not "what + the change did". -** ChangeLog +- Preferred form for several entries with the same content: -A ChangeLog entry as plaintext (separate from the patch). + * help.el (view-lossage): + * kmacro.el (kmacro-edit-lossage): + * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys. -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. + (Rather than anything involving "ditto" and suchlike.) -Ref: "Change Log Concepts" node of the GNU Coding Standards Info -Manual, for how to write good log entries. +- If the commit fixes a bug, add a separate line -** The patch itself. + Fixes: bug#NNNN -Please use "Context Diff" format. + where NNNN is the bug number. -If you are accessing the CVS repository use - cvs update; cvs diff -cp -else, use - diff -cp OLD NEW +- In ChangeLog entries, there is no standard or recommended way to + identify revisions. -If your version of diff does not support these options, then get the -latest version of GNU Diff. + One way to identify revisions is by quoting their summary line. + Another is with an action stamp - an RFC3339 date followed by ! + followed by the committer's email - for example, + "2014-01-16T05:43:35Z!esr@thyrsus.com". Often, "my previous commit" + will suffice. -** Mail format. +- 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. -We prefer to get the patches as inline plain text. +** branches -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. +Development normally takes places on the trunk. +Sometimes specialized features are developed on separate branches +before possibly being merged to the trunk. -** Please reread your patch before submitting it. +Development is discussed on the emacs-devel mailing list. -** Do not mix changes. +Sometime before the release of a new major version of Emacs a "feature +freeze" is imposed on the trunk, to prepare for creating a release +branch. No new features may be added to the trunk after this point, +until the release branch is created. Announcements about the freeze +(and other important events) are made on the info-gnu-emacs mailing +list, and not anywhere else. -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 trunk branch is named "master" in git; release branches are named +"emacs-nn" where "nn" is the major version. +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 +branch later. -* Coding style and conventions. +However, if you know that the change will be difficult to merge to the +trunk (eg because the trunk code has changed a lot), you can apply the +change to both trunk and branch yourself. Indicate in the release +branch commit log that there is no need to merge the commit to the +trunk; start the commit message with "Backport:". gitmerge.el will +then exclude that commit from the merge to trunk. -** Mandatory reading: -The "Tips and Conventions" Appendix of the Emacs Lisp Reference. +** Other process information -** Avoid using `defadvice' or `eval-after-load' for Lisp code to be -included in Emacs. +See all the files in admin/notes/* . In particular, see +admin/notes/newfile, see admin/notes/repo. -** Remove all trailing whitespace in all source and text files. +*** git vs rename -** Use ?\s instead of ? in Lisp code for a space character. +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 -* Supplemental information for Emacs Developers. +- commit the rename without any changes -** 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. +- 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. -Bug reports for released versions are sent to bug-gnu-emacs@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 lists.gnu.org or gmane.org. +Bug reports and fixes, feature requests and implementations should be +sent to bug-gnu-emacs@gnu.org, the bug/feature list. This is coupled +to the tracker at http://debbugs.gnu.org . +You can subscribe to the mailing lists, or see the list archives, +by following links from http://savannah.gnu.org/mail/?group=emacs . ** 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.) +Any change that matters to end-users should have an entry in etc/NEWS. +Think about whether your change requires updating the documentation +(both manuals and doc-strings). If you know it does not, mark the NEWS +entry with "---". If you know that *all* the necessary documentation +updates have been made, mark the entry with "+++". Otherwise do not mark it. ** Understanding Emacs Internals. @@ -183,32 +194,13 @@ 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 - -See admin/notes/copyright. - -** 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. - - This file is part of GNU Emacs. -GNU Emacs is free software; you can redistribute it and/or modify +GNU Emacs is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 2, or (at your option) -any later version. +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. GNU Emacs is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of @@ -216,12 +208,9 @@ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License -along with GNU Emacs; see the file COPYING. If not, write to the -Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, -Boston, MA 02110-1301, USA. +along with GNU Emacs. If not, see . Local variables: mode: outline paragraph-separate: "[ ]*$" end: -