123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375 |
- * How developers contribute to GNU Emacs
- Here is how software developers can contribute to Emacs. (Non-developers: see
- http://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.
- Briefly, the following shell commands build and run Emacs from scratch:
- git config --global user.name 'Your Name'
- git config --global user.email 'your.name@example.com'
- git config --global transfer.fsckObjects true
- git clone git://git.sv.gnu.org/emacs.git
- cd emacs
- ./autogen.sh
- ./configure
- make
- src/emacs
- For more details, see
- http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs and
- http://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, paying
- attention to postings with subject lines containing "emacs-announce",
- as these discuss important events like feature freezes. See
- http://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 http://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 http://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. 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'.
- ** Issue tracker (a.k.a. "bug tracker")
- The Emacs issue tracker at http://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.
- 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.
- Doc-strings should be updated together with the code.
- 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.
- 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 predefine indices, see
- http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Predefined-Indices.html
- or run the shell command 'info "(texinfo)Predefined Indices"'.
- For more specific tips on Emacs's doc style, see
- http://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
- http://www.gnu.org/software/emacs/manual/html_node/ert/
- or run 'info "(ert)"' for 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 <filename>" to run the tests for
- <filename>.el(c). See "test/README" for more information.
- ** Commit messages
- Ordinarily, a change you commit should contain a log entry 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
- 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 that line starts with a
- semicolon and a space "; ", the commit 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.
- - 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.
- - 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.
- - 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 <j.schmoe@example.org>
- - 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)".
- - Commit messages should contain only printable UTF-8 characters.
- - 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 file entries.
- - Emacs generally follows the GNU coding standards for ChangeLogs: see
- http://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
- http://www.gnu.org/prep/standards/html_node/Comments.html
- or run 'info "(standards)Comments"'.
- They 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 that.
- 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.
- - 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
- - You can use Emacs functions to write ChangeLog entries; see
- http://www.gnu.org/software/emacs/manual/html_node/emacs/Change-Log-Commands.html
- or run 'info "(emacs)Change Log Commands"'.
- - 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 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.
- - 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.
- ** 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.
- ** 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, be sure to
- commit it to the release branch; it will be merged to the master
- branch later by the gitmerge function.
- Documentation fixes (in doc strings, in manuals, 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.
- 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
- reasons. 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.
- ** 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:
- http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html
- http://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, see 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 <http://www.gnu.org/licenses/>.
- Local variables:
- mode: outline
- paragraph-separate: "[ ]*$"
- coding: utf-8
- end:
|