Fix shr.el/image build problem

[gnu-emacs] / CONTRIBUTE

diff --git a/CONTRIBUTE b/CONTRIBUTE
index 476b3610cd5d4da38555bcb00c63e656213cf564..9d5d775a5e08ea174a7a982c24323141a4a28793 100644 (file)
--- a/CONTRIBUTE
+++ b/CONTRIBUTE
@@ -1,58 +1,73 @@
-This file contains information on Emacs developer processes.
+* How developers contribute to GNU Emacs

 
 

-For information on contributing to Emacs as a non-developer, see
-(info "(emacs)Contributing") or
+Here is how software developers can contribute to Emacs.  (Non-developers: see

 http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html
 http://www.gnu.org/software/emacs/manual/html_node/emacs/Contributing.html

+or run the shell command 'info "(emacs)Contributing"'.)

 
 

-* Information for Emacs Developers.
+** The Emacs repository

 
 

-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.
+Emacs development uses Git on Savannah for its main repository.
+Briefly, the following shell commands build and run Emacs from scratch:

 
 

-** Write access to the Emacs repository.
+       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

 
 

-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.
+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.

 
 

-** Using the Emacs repository
+** Getting involved with development

 
 

-Emacs uses git for the source code repository.
+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.

 
 

-See http://www.emacswiki.org/emacs/GitQuickStartForEmacsDevs to get
-started, and http://www.emacswiki.org/emacs/GitForEmacsDevs for more
-advanced information.
+** Committing changes by others

 
 

-Alternately, see admin/notes/git-workflow.
-
-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 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.

 
 ** Commit messages
 
 
 ** Commit messages
 

-When a release is prepared, the commit messages are used to generate
-the ChangeLog file.  So a typical patch does not touch any of the
-ChangeLog files in the repository, but contains the ChangeLog entries
-in its message.  Here is an example commit message (indented):
+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;
 
        Deactivate shifted region
 
        Do not silently extend a region that is not highlighted;

-       this can happen after a shift.
+       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.
        * 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.

-       Fixes: bug#19003

 
 

-The general format is as follows.
+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.

 
 

-- Start with a single unindented summary line explaining the change,
-  then an empty line, then unindented ChangeLog entries.
+- 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
 
 - 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


@@ -65,28 +80,47 @@ The general format is as follows.
   file first line (starting with the asterisk).  Then there is no
   individual files section.
 
   file first line (starting with the asterisk).  Then there is no
   individual files section.
 

-- 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.
+- 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.
 
 
 - 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.
 

-- 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.
+- 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 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).
+- 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
 
   They are preserved indefinitely, and have a reasonable chance of
   being read in the future, so it's better that they have good


@@ -103,53 +137,33 @@ The general format is as follows.
 
   (Rather than anything involving "ditto" and suchlike.)
 
 
   (Rather than anything involving "ditto" and suchlike.)
 

-- If the commit has authors other than yourself, the commit message
-  should contain a separate line 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
-
-- If the commit fixes a bug, append a separate line
-
-       Fixes: bug#NNNN
-
-  where NNNN is the bug number.
-
-- In ChangeLog entries, there is no standard or recommended way to
-  identify revisions.
+- 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,
 
   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"
+  "2014-01-16T05:43:35Z!esr@thyrsus.com".  Often, "my previous commit"

   will suffice.
 
   will suffice.
 

-- There is no need to mention files such as NEWS, MAINTAINERS, and
-  FOR-RELEASE, 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 a commit message's first line starts with "; ", the message is
-  ignored when generating ChangeLog history files via 'make ChangeLog'
-  or via 'make change-history'.  You can use "; " for minor commits
-  that do not need separate ChangeLog entries, as well as commits that
-  only modify files that don't need these entries at all.
+- 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
 
 
 ** Generating ChangeLog entries
 

-- 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.
+- 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 into your *vc-log* buffer.
 
 - 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
+  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
   does by default), they will be filled in for you automatically.
 
 - Alternatively, you can use the vc-dwim command to maintain commit


@@ -159,74 +173,78 @@ The general format is as follows.
   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.
 
   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.
 

-** branches
+** Branches

 
 

-Development normally takes places on the trunk.
-Sometimes specialized features are developed on separate branches
-before possibly being merged to the trunk.
-
-Development is discussed on the emacs-devel mailing list.
-
-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.
-
-The trunk branch is named "master" in git; release branches are named
-"emacs-nn" where "nn" is the major version.
+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
 
 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.
+branch later by the gitmerge function.

 
 However, if you know that the change will be difficult to merge to the
 
 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.
-
+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.

 
 ** Other process information
 
 
 ** Other process information
 

-See all the files in admin/notes/* . In particular, see
-admin/notes/newfile, see admin/notes/repo.
-
-*** 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 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 and fixes, feature requests and implementations should be
 sent to bug-gnu-emacs@gnu.org, the bug/feature list.  This is coupled
 ** Emacs Mailing lists.
 
 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 .
+to the http://debbugs.gnu.org tracker.

 
 

-You can subscribe to the mailing lists, or see the list archives,
-by following links from http://savannah.gnu.org/mail/?group=emacs .
+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
 
 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.
+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.

 
 

-** Document your changes.
+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.
 
 
 Any change that matters to end-users should have an entry in etc/NEWS.
 


@@ -235,36 +253,83 @@ 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
 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.
+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.
+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.

 
 

-** Test your changes.
+** Testing your changes

 
 Please test your changes before committing them or sending them to the
 
 Please test your changes before committing them or sending them to the

-list.
+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.

 
 

-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.
+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
 
 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
-<filename>" to run the tests for <filename>.el(c).  See
-"test/automated/Makefile" for more information.
+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.

 
 

-** Understanding Emacs Internals.
+** 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 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.
 
 
 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.
+

 
 \f
 This file is part of GNU Emacs.
 
 \f
 This file is part of GNU Emacs.


@@ -285,4 +350,5 @@ along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.
 Local variables:
 mode: outline
 paragraph-separate: "[         \f]*$"
 Local variables:
 mode: outline
 paragraph-separate: "[         \f]*$"

+coding: utf-8

 end:
 end: