X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/9ee365d565205366d61d9b50dd2a15ef903be983..95f69f2c5999be4b9444861b6d4ae1bd3ab87f83:/CONTRIBUTE diff --git a/CONTRIBUTE b/CONTRIBUTE index 0f7fe6855b..9061007fc9 100644 --- a/CONTRIBUTE +++ b/CONTRIBUTE @@ -1,214 +1,322 @@ -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). +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. Also, be sure to +subscribe to the emacs-devel@gnu.org mailing list and include the +"emacs-announce" topic, so that you get the announcements about +feature freeze and other important events. -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. +** Using the Emacs repository -Here are some style and legal conventions for contributors to Emacs: +Emacs uses Git for the source code repository. +See http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs to get +started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more +advanced information. -* Coding Standards +Alternately, see admin/notes/git-workflow. -Contributed code should follow the GNU Coding Standard. +If committing changes written by someone else, make the commit 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. -If it doesn't, we'll need to find someone to fix the code before we -can use it. +** Commit messages -Emacs has certain additional style and coding conventions. +Emacs development no longer stores descriptions of new changes in +ChangeLog files. Instead, a single ChangeLog file is generated from +the commit messages when a release is prepared. So changes you commit +should not touch any of the ChangeLog files in the repository, but +instead should contain the log entries in the commit message. Here is +an example of a commit message (indented): -Ref: http://www.gnu.org/prep/standards_toc.html -Ref: GNU Coding Standards Info Manual -Ref: The "Tips" Appendix in the Emacs Lisp Reference. + Deactivate shifted region + Do not silently extend a region that is not highlighted; + this can happen after a shift (Bug#19003). + * doc/emacs/mark.texi (Shift Selection): Document the change. + * lisp/window.el (handle-select-window): + * src/frame.c (Fhandle_switch_frame, Fselected_frame): + Deactivate the mark. -* Copyright Assignment +Below are some rules and recommendations for formatting commit +messages: -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. +- Start with a single unindented summary line explaining the change; + do not end this line with a period. If that line starts with a + semi-colon and a space "; ", the log message will be ignored when + generating the ChangeLog file. Use this for minor commits that do + not need separate ChangeLog entries, such as changes in etc/NEWS. -Contact us at emacs-devel@gnu.org to obtain the relevant forms. +- After the summary line, there should be an empty line, then + unindented ChangeLog entries. +- Limit lines in commit messages to 78 characters, unless they consist + of a single word of at most 140 characters; this is enforced by a + commit hook. It's nicer to limit the summary line to 50 characters; + this isn't enforced. If the change can't be summarized so briefly, + add a paragraph after the empty line and before the individual file + descriptions. -* Getting the Source Code +- 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. -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. +- If the commit has more than one author, the commit message should + contain separate lines to mention the other authors, like the + following: -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). + Co-authored-by: Joe Schmoe -Ref: http://savannah.gnu.org/projects/emacs +- If the commit is a tiny change that is exempt from copyright paperwork, + the commit message should contain a separate line like the following: + Copyright-paperwork-exempt: yes -* Submitting Patches +- The commit message should contain "Bug#NNNNN" if it is related to + bug number NNNNN in the debbugs database. This string is often + parenthesized, as in "(Bug#19003)". + +- Commit messages should contain only printable UTF-8 characters. -Every patch must have several pieces of information before we -can properly evaluate it. +- Commit messages should not contain the "Signed-off-by:" lines that + are used in some other projects. -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. +- Any lines of the commit message that start with "; " are omitted + from the generated ChangeLog. -All subsequent discussion should also be sent to the mailing list. +- 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. -** Description +- Emacs generally follows the GNU coding standards when it comes to + ChangeLogs: + http://www.gnu.org/prep/standards/html_node/Change-Logs.html or + "(info (standards)Change Logs"). 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. -For bug fixes, a description of the bug and how your patch fixes this -bug. +- 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). -For new features, a description of the feature and your -implementation. + They are preserved indefinitely, and have a reasonable chance of + being read in the future, so it's better that they have good + presentation. -** ChangeLog +- Use the present tense; describe "what the change does", not "what + the change did". -A ChangeLog entry as plaintext (separate from the patch). +- Preferred form for several entries with the same content: -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. + * lisp/help.el (view-lossage): + * lisp/kmacro.el (kmacro-edit-lossage): + * lisp/edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300. -Ref: "Change Log Concepts" node of the GNU Coding Standards Info -Manual, for how to write good log entries. + (Rather than anything involving "ditto" and suchlike.) -** The patch itself. +- There is no standard or recommended way to identify revisions in + ChangeLog entries. Using Git SHA1 values limits the usability of + the references to Git, and will become much less useful if Emacs + switches to a different VCS. So we recommend against that. -Please use "Context Diff" format. + 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. -If you are accessing the CVS repository use - cvs update; cvs diff -cp -else, use - diff -cp OLD NEW +- There is no need to mention files such as NEWS and MAINTAINERS, or + to indicate regeneration of files such as 'configure', in the + ChangeLog entry. "There is no need" means you don't have to, but + you can if you want to. -If your version of diff does not support these options, then get the -latest version of GNU Diff. +** Generating ChangeLog entries -** Mail format. +- You can use various Emacs functions to ease the process of writing + ChangeLog entries; see (info "(emacs)Change Log Commands") or + http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html. -We prefer to get the patches as inline plain text. +- If you use Emacs VC, one way to format ChangeLog entries is to create + a top-level ChangeLog file manually, and update it with 'C-x 4 a' as + usual. Do not register the ChangeLog file under git; instead, use + 'C-c C-a' to insert its contents into into your *vc-log* buffer. + Or if 'log-edit-hook' includes 'log-edit-insert-changelog' (which it + does by default), they will be filled in for you automatically. -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. +- Alternatively, you can use the vc-dwim command to maintain commit + messages. When you create a source directory, run the shell command + 'git-changelog-symlink-init' to create a symbolic link from + ChangeLog to .git/c/ChangeLog. Edit this ChangeLog via its symlink + with Emacs commands like 'C-x 4 a', and commit the change using the + shell command 'vc-dwim --commit'. Type 'vc-dwim --help' for more. -** Please reread your patch before submitting it. +** Branches -** Do not mix changes. +Development normally takes places on the trunk. +Sometimes specialized features are developed on separate branches +before possibly being merged to the trunk. -If you send several unrelated changes together, we will ask you to -separate them so we can consider each of the changes by itself. +Development is discussed on the emacs-devel mailing list. +The trunk branch is named "master" in git; release branches are named +"emacs-nn" where "nn" is the major version. -* Coding style and conventions. +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. -** Mandatory reading: +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. It could also happen that a +change is cherry-picked from master to the release branch, and so +doesn't need to be merged back. In these cases, 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. -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. +** Other process information -** Remove all trailing whitespace in all source and text files. +** Emacs Mailing lists. -** Use ?\s instead of ? in Lisp code for a space character. +Discussion about Emacs development takes place on emacs-devel@gnu.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 . -* Supplemental information for Emacs Developers. +You can subscribe to the mailing lists, or see the list archives, +by following links from http://savannah.gnu.org/mail/?group=emacs . -** Write access to Emacs' CVS repository. +To email a patch you can use a shell command like 'git format-patch -1' +to create a file, and then attach the file to your email. This nicely +packages the patch's commit message and changes. To send just one +such patch without additional remarks, you can use a command like +'git send-email --to=bug-gnu-emacs@gnu.org 0001-DESCRIPTION.patch'. -Once you become a frequent contributor to Emacs, we can consider -giving you write access to the CVS repository. +** Issue tracker (a.k.a. "bug tracker") +The Emacs issue tracker is at http://debbugs.gnu.org/. The form +presented by that page allows to view bug reports and search the +database for bugs matching several criteria. Messages posted to the +bug-gnu-emacs@gnu.org mailing list, mentioned above, are recorded by +the tracker with the corresponding bugs/issues. -** Emacs Mailing lists. - -Discussion about Emacs development takes place on emacs-devel@gnu.org. +GNU ELPA has a 'debbugs' package that allows accessing the tracker +database from Emacs. -Bug reports for released versions are sent to bug-gnu-emacs@gnu.org. +** Document your changes. -Bug reports for development versions are sent to emacs-pretest-bug@gnu.org. +Any change that matters to end-users should have an entry in etc/NEWS. -You can subscribe to the mailing lists at savannah.gnu.org/projects/emacs. +Doc-strings should be updated together with the code. -You can find the mailing lists archives at lists.gnu.org or gmane.org. +Think about whether your change requires updating the manuals. 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. +Please see (info "(elisp)Documentation Tips") or +https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html +for more specific tips on Emacs's doc style. Use 'checkdoc' to check +for documentation errors before submitting a patch. -** Document your changes. +** Test 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. +Please test your changes before committing them or sending them to the +list. If possible, add a new test along with any bug fix or new +functionality you commit (of course, some changes cannot be easily +tested). -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.) +Emacs uses ERT, Emacs Lisp Regression Testing, for testing. See (info +"(ert)") or https://www.gnu.org/software/emacs/manual/html_node/ert/ +for more information on writing and running tests. +To run tests on the entire Emacs tree, run "make check" from the +top-level directory. Most tests are in the directory +"test/automated". From the "test/automated" directory, run "make +" to run the tests for .el(c). See +"test/automated/Makefile" for more information. ** 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. +of the Emacs Lisp Reference Manual may also help. Some source files, +such as xdisp.c, have large commentaries describing the design and +implementation in more detail. The file etc/DEBUG describes how to debug Emacs bugs. +*** Non-ASCII characters in Emacs files + +If you introduce non-ASCII characters into Emacs source files, it is a +good idea to add a 'coding' cookie to the file to state its encoding. +Please use the UTF-8 encoding unless it cannot do the job for some +good reason. As of Emacs 24.4, it is no longer necessary to have +explicit 'coding' cookies in *.el files if they are encoded in UTF-8, +but other files need them even if encoded in UTF-8. However, if +an *.el file is intended for use with older Emacs versions (e.g. if +it's also distributed via ELPA), having an explicit encoding +specification is still a good idea. + +*** Useful files in the admin/ directory +See all the files in admin/notes/* . In particular, see +admin/notes/newfile, see admin/notes/repo. -* How to Maintain Copyright Years for GNU Emacs +The file admin/MAINTAINERS records the areas of interest of frequent +Emacs contributors. If you are making changes in one of the files +mentioned there, it is a good idea to consult the person who expressed +an interest in that file, and/or get his/her feedback for the changes. +If you are a frequent contributor and have interest in maintaining +specific files, please record those interests in that file, so that +others could be aware of that. -See admin/notes/copyright. +*** git vs rename -** 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!). +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: -** For those files that have been added since then, we should add -the year it was added to Emacs, and all subsequent years. +- create a feature branch -** 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. +- 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. 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 +324,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: -