Copyright (C) 2006-2024 Free Software Foundation, Inc. See the end of the file for license conditions. * How developers contribute to GNU Emacs Here is how software developers can contribute to Emacs. (Non-developers: see https://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html or run the shell command 'info "(emacs)Contributing"'.) ** The Emacs repository Emacs development uses Git on Savannah for its main repository. To configure Git for Emacs development, you can run the following: git config --global user.name 'Your Name' git config --global user.email 'your.name@example.com' git config --global transfer.fsckObjects true The following shell commands then build and run Emacs from scratch: git clone https://git.savannah.gnu.org/git/emacs.git cd emacs ./autogen.sh ./configure make src/emacs For more details, see https://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs and https://www.emacswiki.org/emacs/GitForEmacsDevs or see the file admin/notes/git-workflow. ** Getting involved with development Discussion about Emacs development takes place on emacs-devel@gnu.org. You can subscribe to the emacs-devel@gnu.org mailing list. If you want to get only the important mails (for things like feature freezes), choose to receive only the 'emacs-announce' topic (although so far this feature has not been well or consistently used). See https://lists.gnu.org/mailman/listinfo/emacs-devel for mailing list instructions and archives. You can develop and commit changes in your own copy of the repository, and discuss proposed changes on the mailing list. Frequent contributors to Emacs can request write access there. Bug reports and fixes, feature requests and patches/implementations should be sent to bug-gnu-emacs@gnu.org, the bug/feature list. This is coupled to the https://debbugs.gnu.org tracker. It is best to use the command 'M-x report-emacs-bug RET' to report issues to the tracker (described below). Be prepared to receive comments and requests for changes in your patches, following your submission. The Savannah info page https://savannah.gnu.org/mail/?group=emacs describes how to subscribe to the mailing lists, or see the list archives. 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, and makes sure the format and whitespace are not munged in transit by the various mail agents. To send just one such patch without additional remarks, it is also possible to use a command like git send-email --to=bug-gnu-emacs@gnu.org 0001-DESCRIPTION.patch However, we prefer the 'git format-patch' method with attachment, as doing so delivers patches in the correct and easily-recognizable format more reliably, and makes the job of applying the patches easier and less error-prone. It also allows sending patches whose author is someone other than the email sender. Once the cumulative amount of your submissions exceeds a dozen or so lines of non-trivial changes, we will need you to assign to the FSF the copyright for your contributions. (To see how many lines were non-trivially changed, count only added and modified lines in the patched code. Consider an added or changed line non-trivial if it includes at least one identifier, string, or substantial comment.) In most cases, to start the assignment process you should download https://git.savannah.gnu.org/cgit/gnulib.git/plain/doc/Copyright/request-assign.future and return the completed information to the address at the top. (There are other assignment options, but they are much less commonly used.) If you have questions about the assignment process, you can ask the address listed on the form, and/or emacs-devel@gnu.org. ** Issue tracker (a.k.a. "bug tracker") The Emacs issue tracker at https://debbugs.gnu.org lets you 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. If a message to the bug tracker contains a patch, please include the string "[PATCH]" in the subject of the message in order to let the bug tracker tag the bug properly. GNU ELPA has a 'debbugs' package that allows accessing the tracker database from Emacs. Bugs needs regular attention. A large backlog of bugs is disheartening to the developers, and a culture of ignoring bugs is harmful to users, who expect software that works. Bugs have to be regularly looked at and acted upon. Not all bugs are critical, but at the least, each bug needs to be regularly re-reviewed to make sure it is still reproducible. The process of going through old or new bugs and acting on them is called bug triage. This process is described in the file admin/notes/bug-triage. ** Documenting your changes Any change that matters to end-users should have an entry in etc/NEWS. Try to start each NEWS entry with a sentence that summarizes the entry and takes just one line -- this will allow reading NEWS in Outline mode after hiding the body of each entry. When adding a new user option that allows changing behavior, please document its default value. Similarly, changes to the default value of an existing user option should be announced. Doc-strings should be updated together with the code. New defcustom's and defface's should always have a ':version' tag stating the first Emacs version in which they will appear. Likewise with defcustom's or defface's whose value is changed -- update their ':version' tag. Think about whether your change requires updating the manuals. If you know it does not, mark the NEWS entry with "---" before the entry. If you know that *all* the necessary documentation updates have been made as part of your changes or those by others, mark the entry with "+++". Otherwise, do not mark it. If your change requires updating the manuals to document new functions/commands/variables/faces, then use the proper Texinfo command to index them; for instance, use @vindex for variables and @findex for functions/commands. For the full list of predefined indices, see https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Predefined-Indices.html or run the shell command 'info "(texinfo)Predefined Indices"'. We prefer American English both in doc strings and in the manuals. That includes both spelling (e.g., "behavior", not "behaviour") and the convention of leaving 2 spaces between sentences. For more specific tips on Emacs's doc style, see https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html Use 'checkdoc' to check for documentation errors before submitting a patch. ** Testing your changes 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). Emacs uses ERT, Emacs Lisp Regression Testing, for testing. See https://www.gnu.org/software/emacs/manual/html_node/ert/ or run 'info "(ert)"' for more information on writing and running tests. If your test lasts longer than some few seconds, mark it in its 'ert-deftest' definition with ":tags '(:expensive-test)". To run tests on the entire Emacs tree, run "make check" from the top-level directory. Most tests are in the directory "test/". From the "test/" directory, run "make " to run the tests for .el(c). See "test/README" for more information. If you're making changes that involve the Emacs build system, please test 'out-of-tree' builds as well, i.e.: mkdir emacs-build cd emacs-build ../path-to-emacs-sources/configure make ** Commit messages Ordinarily, a changeset you commit should contain a description of the changes in its commit message and should not touch the repository's ChangeLog files. Here is an example commit message (indented): 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. Occasionally, commit messages are collected and prepended to a generated ChangeLog file, where they can be corrected. It saves time to get them right the first time, so here are guidelines for formatting them: - Start with a single unindented summary line explaining the change; do not end this line with a period. If possible, try to keep the summary line to 50 characters or fewer; this is for compatibility with certain Git commands that print that line in width-constrained contexts. If the summary line starts with a semicolon and a space "; ", the commit message will be skipped and not added to the generated ChangeLog file. Use this for minor commits that do not need to be mentioned in the ChangeLog file, such as changes in etc/NEWS, typo fixes, etc. - After the summary line, there should be an empty line. - Unindented ChangeLog entries normally come next. However, if the commit couldn't be properly summarized in the brief summary line, you can put one or more paragraphs (after the empty line and before the individual ChangeLog entries) that further describe(s) the commit. - Lines in ChangeLog entries should preferably be not longer than 63 characters, and must not exceed 78 characters, unless they consist of a single word of at most 140 characters; this 78/140 limit is enforced by a commit hook. - If only a single file is changed, the summary line can be the normal first line of a ChangeLog entry (starting with the asterisk). Then there will be no individual ChangeLog entries beyond the one in the summary line. - If the commit has more than one author, the commit message should contain separate lines to mention the other authors, like the following: Co-authored-by: Joe Schmoe - 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 - 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)". - When citing URLs, prefer https: to http: when either will do. In particular, gnu.org and fsf.org URLs should start with "https:". - Commit messages should contain only printable UTF-8 characters. However, we ask that non-ASCII characters be used only if strictly necessary, not just for aesthetic purposes. - Commit messages should not contain the "Signed-off-by:" lines that are used in some other projects. - Any lines of the commit message that start with "; " are omitted from the generated ChangeLog. - 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 following ChangeLog entries. - Emacs follows the GNU coding standards for ChangeLog entries: see https://www.gnu.org/prep/standards/html_node/Change-Logs.html or run 'info "(standards)Change Logs"'. One exception is that commits still sometimes quote `like-this' (as the standards used to recommend) rather than 'like-this' or ‘like this’ (as they do now), as `...' is so widely used elsewhere in Emacs. - Some commenting rules in the GNU coding standards 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). See https://www.gnu.org/prep/standards/html_node/Comments.html or run 'info "(standards)Comments"'. American English is preferred in Emacs; that includes spelling and leaving 2 blanks between sentences. The ChangeLog entries are preserved indefinitely, and have a reasonable chance of being read in the future, so it's better that they have good presentation. - Use the present tense; describe "what the change does", not "what the change did". - Preferred form for several entries with the same content: * lisp/menu-bar.el (clipboard-yank, clipboard-kill-ring-save) (clipboard-kill-region): * lisp/eshell/esh-io.el (eshell-virtual-targets) (eshell-clipboard-append): Replace option gui-select-enable-clipboard with select-enable-clipboard; renamed October 2014. (Bug#25145) (Rather than anything involving "ditto" and suchlike.) - 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 doing only that. One way to identify revisions is by quoting their summary line. Prefixing the summary with the commit date can give useful context (use 'git show -s "--pretty=format:%cd \"%s\"" --date=short HASH' to produce that). Often, "my previous commit" will suffice. - There is no need to mention files such as NEWS and MAINTAINERS, or to indicate regeneration of files such as 'lib/gnulib.mk', in the ChangeLog entry. "There is no need" means you don't have to, but you can if you want to. ** Generating ChangeLog entries - If you use Emacs VC, you can use 'C-c C-w' to generate formatted blank ChangeLog entries from the diff being committed, then use 'M-q' to combine and fill them. See 'info "(emacs) Log Buffer"'. - If you use the third-party package Magit, you can use 'magit-generate-changelog' from the commit message buffer. See also 'magit-add-change-log-entry' and 'magit-add-change-log-entry-other-window'. - Alternatively, you can use Emacs functions for ChangeLog files; see https://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html or run 'info "(emacs)Change Log Commands"'. To format ChangeLog entries with Emacs VC, 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 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. - Instead of Emacs VC, 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. ** Committing your changes. When you commit changes, Git invokes several scripts that test the commit for validity, and may abort the commit if some of the tests fail. These scripts live in the '.git/hooks/' subdirectory of the top-level directory of the repository, and they perform the following tests: - commit log message must not be empty; - the first line of the commit log message doesn't start with whitespace characters; - the second line of the commit log message must be empty; - commit log message should include only valid printable ASCII and UTF-8 characters; - commit log message lines must be shorter than 79 characters, unless a line consists of a single long word, in which case that word can be up to 140 characters long; - there shouldn't be any "Signed-off-by:" tags in the commit log message, and "git commit" should not be invoked with the '-s' option (which automatically adds "Signed-off-by:"); - if the commit adds new files, the file names must not begin with '-' and must consist of ASCII letters, digits, and characters of the set [-+./_]; - the changes don't include unresolved merge conflict markers; - the changes don't introduce whitespace errors: trailing whitespace, lines that include nothing but whitespace characters, and indented lines where a SPC character is immediately followed by a TAB in the line's initial indentation ** Committing changes by others If committing changes written by someone else, commit in their name, not yours. You can use 'git commit --author="AUTHOR"' to specify a change's author. When using Emacs VC to commit, the author can be specified in the log-edit buffer by adding an "Author: AUTHOR" header line (set 'log-edit-setup-add-author' non-nil to have this header line added automatically). Note that the validity checks described in the previous section are still applied, so you will have to correct any problems they uncover in the changes submitted by others. ** Branches Future development normally takes place on the master branch. Sometimes specialized features are developed on other branches before possibly being merged to the master. Release branches are named "emacs-NN" where NN is the major version number, and are mainly intended for more-conservative changes such as bug fixes. Typically, collective development is active on the master branch and possibly on the current release branch. Periodically, the current release branch is merged into the master, using the gitmerge function described in admin/notes/git-workflow. If you are fixing a bug that exists in the current release, you should generally commit it to the release branch; it will be merged to the master branch later by the gitmerge function. However, when the release branch is for Emacs version NN.2 and later, or when it is for Emacs version NN.1 that is in the very last stages of its pretest, that branch is considered to be in a feature freeze: only bug fixes that are "safe" or are fixing major problems should go to the release branch, the rest should be committed to the master branch. This is so to avoid destabilizing the next Emacs release. If you are unsure whether your bug fix is "safe" enough for the release branch, ask on the emacs-devel mailing list. Documentation fixes (in doc strings, in manuals, in NEWS, and in comments) should always go to the release branch, if the documentation to be fixed exists and is relevant to the release-branch codebase. Doc fixes are always considered "safe" -- even when a release branch is in feature freeze, it can still receive doc fixes. However, this rule is limited to fixing real problems in the documentation; cleanups and stylistic changes are excluded. When you know that the change will be difficult to merge to the master (e.g., because the code on master has changed a lot), you can apply the change to both master 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, say in the release branch commit message that there is no need to merge the commit to master, by starting the commit message with "Backport:". The gitmerge function excludes these commits from the merge to the master. Some changes should not be merged to master at all, for whatever reason. These should be marked by including something like "Do not merge to master" or anything that matches gitmerge-skip-regexp (see admin/gitmerge.el) in the commit message. ** Some packages in Emacs are maintained externally Sometimes a package that ships as part of GNU Emacs is maintained as a separate project, with its own upstream repository, its own maintainer group, its own development conventions, etc. The upstream project's code is periodically merged into Emacs (exactly when and how such merges happen depends on the package). So when you are making a contribution -- such as fixing a bug or proposing an enhancement -- to one of these externally maintained packages, you sometimes need to deal with that package at its upstream source. In the section "Externally maintained packages" in "admin/MAINTAINERS" we maintain a list of such packages. ** GNU ELPA This repository does not contain the Emacs Lisp package archive (elpa.gnu.org). See admin/notes/elpa for how to access the GNU ELPA repository. ** Understanding Emacs internals The best way to understand Emacs internals is to read the code. Some source files, such as xdisp.c, have extensive comments describing the design and implementation. The following resources may also help: https://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html https://www.gnu.org/software/emacs/manual/html_node/elisp/GNU-Emacs-Internals.html or run 'info "(elisp)Tips"' or 'info "(elisp)GNU Emacs Internals"'. 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, use the UTF-8 encoding unless it cannot do the job for some good reason. Although it is generally a good idea to add 'coding:' cookies to non-ASCII source files, cookies are not needed in UTF-8-encoded *.el files intended for use only with Emacs version 24.5 and later. *** Useful files in the admin/ directory See all the files in 'admin/notes/*'. In particular, see 'admin/notes/newfile' and 'admin/notes/repo'. 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. *** git vs rename 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. - Commit the rename without any changes. - Make other changes. - Merge the feature branch to the master branch, instead of 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 it under the terms of the GNU General Public License as published by 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 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. If not, see . Local variables: mode: outline paragraph-separate: "[ ]*$" coding: utf-8 end: