diff options
| -rw-r--r-- | CONTRIBUTE | 182 | ||||
| -rw-r--r-- | ChangeLog | 9 | ||||
| -rw-r--r-- | INSTALL.REPO | 11 | ||||
| -rw-r--r-- | admin/notes/commits | 70 | ||||
| -rw-r--r-- | admin/notes/repo | 92 |
5 files changed, 160 insertions, 204 deletions
diff --git a/CONTRIBUTE b/CONTRIBUTE index b07b6c66af..9c904a798e 100644 --- a/CONTRIBUTE +++ b/CONTRIBUTE @@ -12,36 +12,65 @@ 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. -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. +For documentation on Emacs (to understand how to implement your desired change), refer to: -You may also want to submit your change so that can be considered for -inclusion in a future version of Emacs (see below). +- the Emacs Manual + http://www.gnu.org/software/emacs/manual/emacs.html + (info "(Emacs)Top") -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, check if existing bug reports -are fixed in newer versions of Emacs, contribute to the Emacs web -pages, or develop a package that works with Emacs. +- the Emacs Lisp Reference Manual + http://www.gnu.org/software/emacs/manual/elisp.html + (info "(elisp)Top") + +- http://www.gnu.org/software/emacs + +- http://www.emacswiki.org/ + +There are many ways to contribute to Emacs: + +- implement a new feature, and submit a patch (see "Submitting + Patches" below). + +- answer questions on the Emacs user mailing list + https://lists.gnu.org/mailman/listinfo/help-gnu-emacs + +- write documentation, either on the wiki, or in the Emacs source + repository (see "Submitting Patches" below) + +- find and report bugs; use M-x report-emacs-bug + +- check if existing bug reports are fixed in newer versions of Emacs + http://debbugs.gnu.org/cgi/pkgreport.cgi?which=pkg&data=emacs + +- develop a package that works with Emacs, and publish it on your own or in Gnu ELPA. Here are some style and legal conventions for contributors to Emacs: * Coding Standards -Contributed code should follow the GNU Coding Standards. +Contributed code should follow the GNU Coding Standards +(http://www.gnu.org/prep/standards/ - may also be available in info on +your system). 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. +Emacs has additional style and coding conventions: + +- the "Tips" Appendix in the Emacs Lisp Reference + http://www.gnu.org/software/emacs/manual/html_node/elisp/Tips.html + (info "(elisp)Tips"). -Ref: http://www.gnu.org/prep/standards/ -Ref: GNU Coding Standards Info Manual -Ref: The "Tips" Appendix in the Emacs Lisp Reference. +- Avoid using `defadvice' or `eval-after-load' for Lisp code to be + included in Emacs. +- Remove all trailing whitespace in all source and text files. + +- Emacs has no convention on whether to use tabs in source code, but + please don't change whitespace in the files you edit. + +- Use ?\s instead of ? in Lisp code for a space character. * Copyright Assignment @@ -75,19 +104,18 @@ patches) over all your contributions. * Getting the Source Code -The latest version of the Emacs source code can be downloaded from the -Savannah web site. It is important to write your patch based on the -latest version. If you start from an older version, your patch may be -outdated (so that maintainers will have a hard time applying it), or -changes in Emacs may have made your patch unnecessary. +The current working version of the Emacs source code is stored in a +git repository on the Savannah web site +(http://savannah.gnu.org/projects/emacs). It is important to write +your patch based on the current working version. If you start from an +older version, your patch may be outdated (so that maintainers will +have a hard time applying it), or changes in Emacs may have made your +patch unnecessary. After you have downloaded the repository source, you should read the file INSTALL.REPO for build instructions (they differ to some extent from a normal build). -Ref: http://savannah.gnu.org/projects/emacs - - * Submitting Patches Every patch must have several pieces of information before we @@ -112,11 +140,12 @@ For new features, a description of the feature and your implementation. A ChangeLog entry as plaintext (separate from the patch). See the existing ChangeLog files for format and content. Note that, -unlike some other projects, we do require ChangeLogs also for +unlike some other projects, we do require ChangeLogs for documentation, i.e. Texinfo files. Ref: "Change Log Concepts" node of the GNU Coding Standards Info Manual, for how to write good log entries. +http://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html When using git, commit messages should use ChangeLog format, with a single short line explaining the change, then an empty line, then @@ -154,27 +183,106 @@ Making cosmetic formatting changes (indentation, etc) makes it harder to see what you have really changed. -* Coding style and conventions. +* Supplemental information for Emacs Developers. -** Mandatory reading: +An "Emacs Developer" is someone who contributes a lot of code or +documentation to the Emacs repository. -The "Tips and Conventions" Appendix of the Emacs Lisp Reference. +** Write access to the Emacs repository. -** Avoid using `defadvice' or `eval-after-load' for Lisp code to be -included in 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. -** Remove all trailing whitespace in all source and text files. +** Using the Emacs repository -** Use ?\s instead of ? in Lisp code for a space character. +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. -* Supplemental information for Emacs Developers. +Alternately, see admin/notes/git-workflow. -** Write access to the Emacs repository. +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. -Once you become a frequent contributor to Emacs, we can consider -giving you write access to the version-control repository. +** Changelog notes + +- Preferred form for several entries with the same content: + + * help.el (view-lossage): + * kmacro.el (kmacro-edit-lossage): + * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys. + + (Rather than anything involving "ditto" and suchlike.) + +- 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. + +- 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. + +- In ChangeLog files, there is no standard or recommended way to + identify revisions. + + 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 make separate change log 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. + +** 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. This freeze is announced on the +emacs-devel mailing list, and not anywhere else. + +For example, "emacs-23" for Emacs 23.2 and later, "EMACS_23_1_RC" for +23.1, "EMACS_22_BASE" for 22.x, and "EMACS_21_1_RC" for 21.x. + +You must follow emacs-devel to know exactly what kinds of changes are +allowed on what branch at any time. Announcements about the freeze +(and other important events) will contain "ANNOUNCE" in the subject. + +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. + +The exception is, if you know that the change will be difficult to +merge to the trunk (eg because the trunk code has changed a lot). In +that case, it's helpful if 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:". This is helpful for the person merging the release +branch to the trunk (it is handled automatically by gitmerge.el). + + +** Other process information +See all the files in admin/notes/* . In particular, see +admin/notes/newfile, see admin/notes/repo. ** Emacs Mailing lists. @@ -189,7 +297,7 @@ by following links from http://savannah.gnu.org/mail/?group=emacs . ** Document your changes. -Any change that matters to end-users should have a NEWS entry. +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 @@ -1,3 +1,12 @@ +2014-12-05 Stephen Leake <stephen_leake@stephe-leake.org> + + * CONTRIBUTE: improve, move some info from admin/notes/* here. + +2014-12-05 Stephen Leake <stephen_leake@stephe-leake.org> + + * etc/CONTRIBUTE: renamed to ./CONTRIBUTE, preparatory to further + changes/cleanup + 2014-12-05 Paul Eggert <eggert@cs.ucla.edu> * .gitignore: Remove redundant pattern (subsumed by _*). diff --git a/INSTALL.REPO b/INSTALL.REPO index 83b6f2f413..67dceb8c6e 100644 --- a/INSTALL.REPO +++ b/INSTALL.REPO @@ -1,10 +1,5 @@ Building and Installing Emacs from the Repository -Simply run 'make'. This should work if your files are freshly checked -out from the repository, and if you have the proper tools installed. -If it doesn't work, or if you have special build requirements, the -following information may be helpful. - Building Emacs from the source-code repository requires some tools that are not needed when building from a release. You will need: @@ -34,6 +29,12 @@ can invoke './configure -C'. After configuring, build Emacs as follows: If you want to install Emacs, type 'make install' instead of 'make' in the last command. +After your first build, you can usually just run 'make' after any +updates from the Savannah repository or local edits; the makefile +contains logic to re-run configure as needed. However, if the autoconf +input files have changed, or in some other situations, you will need +to run 'make bootstrap' (more below). + Occasionally the file 'lisp/loaddefs.el' (and similar automatically generated files, such as 'esh-groups.el', and '*-loaddefs.el' in some subdirectories of 'lisp/', e.g., 'mh-e/' and 'calendar/') will need to be diff --git a/admin/notes/commits b/admin/notes/commits deleted file mode 100644 index f33c6905d4..0000000000 --- a/admin/notes/commits +++ /dev/null @@ -1,70 +0,0 @@ -HOW TO COMMIT CHANGES TO EMACS - -Most of these points are from: - -http://lists.gnu.org/archive/html/emacs-devel/2009-03/msg00555.html -From: Miles Bader -Subject: commit style redux -Date: Tue, 31 Mar 2009 12:21:20 +0900 - -(0) Each commit should correspond to a single change (whether spread - over multiple files or not). Do not mix different changes in the - same commit (eg adding a feature in one file, fixing a bug in - another should be two commits, not one). - -(1) Commit all changed files at once with a single log message (which - in CVS will result in an identical log message for all committed - files), not one-by-one. This is pretty easy using vc-dir now. - -(2) Make the log message describe the entire changeset, perhaps - including relevant changelog entries (I often don't bother with - the latter if it's a trivial sort of change). - - Many modern source-control systems vaguely distinguish the first - line of the log message to use as a short summary for abbreviated - history listing (in arch this was explicitly called the summary, - but many other systems have a similar concept). So it's nice if - you can format the log entry like: - - SHORTISH ONE-LINE SUMMARY - - MULTIPLE-LINE DETAILED DESCRIPTION POSSIBLY INCLUDING (OR - CONSISTING OF) CHANGELOG ENTRIES - - [Even with CVS this style is useful, because web CVS browsing - interfaces often include the first N words of the log message of - the most recent commit as a short "most recent change" - description.] - -(3) Don't phrase log messages assuming the filename is known, because - in non-file-oriented systems (everything modern other than CVS), - the log listing tends to be treated as global information, and the - connection with specific files is less explicit. - - For instance, currently I often see log messages like "Regenerate"; - for modern source-control systems with a global log, it's better to - have something like "Regenerate configure". - -(4) (Added in 2014) In commit comments, and ChangeLog files, it is best - to use ways of identifying revisions that are not dependent on a - particular version control system. (At time of writing Emacs is - about to move to its fourth VCS and another move in the future is - not impossible.) An excellent way to identify commits 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. - -Followup discussion: -http://lists.gnu.org/archive/html/emacs-devel/2010-01/msg00897.html -http://lists.gnu.org/archive/html/emacs-devel/2010-02/msg00401.html - - -PREVIOUS GUIDELINES FOR CVS - -For historical interest only, here is the old-style advice for CVS logs: -http://lists.gnu.org/archive/html/emacs-devel/2007-12/msg01208.html - -From: Eli Zaretskii -Subject: Re: Log messages in CVS -Date: Sat, 29 Dec 2007 16:06:29 +0200 diff --git a/admin/notes/repo b/admin/notes/repo index 97b4349ed6..2d4cc2a55c 100644 --- a/admin/notes/repo +++ b/admin/notes/repo @@ -1,70 +1,5 @@ NOTES ON COMMITTING TO EMACS'S REPOSITORY -*- outline -*- -* Commit metainformation - -** Commit in the author's name - -If installing changes written by someone else, commit them in their -name, not yours. - -** Commit message format - -Commit messages should follow the conventions used in all modern -distributed version-control systems. That is, they should consist of - -- A self-contained topic line, preferably no more than 75 chars long. - -- If other content follows the topic line, there should be a blank - line separating the two. - -- Follow the blank line with ChangeLog-like entries for the specific - changes you made, if any. (As long as Emacs maintains ChangeLog - files, just copy the entries you made in them to the commit message - after the blank line.) - -- Preferred form for several entries with the same content: - - * help.el (view-lossage): - * kmacro.el (kmacro-edit-lossage): - * edmacro.el (edit-kbd-macro): Fix docstring, lossage is now 300 keys. - - (Rather than anything involving "ditto" and suchlike.) - -- 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. - http://lists.gnu.org/archive/html/emacs-devel/2014-05/msg00514.html - -** Unnecessary metainformation - -There is no need to make separate change log 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. - -* Commit to the right branch - -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. No new features may be -added after this point. This is usually some months before the release. - -Shortly before the release, a release branch is created, and the -trunk is then free for development. - -For example, "emacs-23" for Emacs 23.2 and later, "EMACS_23_1_RC" for -23.1, "EMACS_22_BASE" for 22.x, and "EMACS_21_1_RC" for 21.x. - -Consult emacs-devel for exactly what kinds of changes are allowed -on what branch at any time. - ** elpa This branch does not contain a copy of Emacs, but of the Emacs Lisp @@ -72,25 +7,6 @@ package archive (elpa.gnu.org). See admin/notes/elpa for further explanation, and the README file in the branch for usage instructions. -* Install changes only on one branch, let them get merged elsewhere if needed. - -In particular, install bug-fixes only on the release branch (if there -is one) and let them get synced to the trunk; do not install them by -hand on the trunk as well. E.g. if there is an active "emacs-24" branch -and you have a bug-fix appropriate for the next emacs-24.x release, -install it only on the emacs-24 branch, not on the trunk as well. - -Installing things manually into more than one branch makes merges more -difficult. - -http://lists.gnu.org/archive/html/emacs-devel/2010-03/msg01124.html - -The exception is, if you know that the change will be difficult to -merge to the trunk (eg because the trunk code has changed a lot). -In that case, it's helpful if you can apply the change to both trunk -and branch yourself (when committing the branch change, indicate -in the commit log that it should not be merged to the trunk; see below). - * Installing changes from your personal branches. If your branch has only a single commit, or many different real @@ -129,14 +45,6 @@ variable in admin/merge-gnulib before running it. If you remove a gnulib module, or if a gnulib module removes a file, then remove the corresponding files by hand. -* Backporting a bug-fix from the trunk to a branch (e.g. "emacs-24"). - -Indicate in the commit log that there is no need to merge the commit -to the trunk, e.g. start the commit message with "Backport:". This is -helpful for the person merging the release branch to the trunk. - -http://lists.gnu.org/archive/html/emacs-devel/2010-05/msg00262.html - * How to merge changes from emacs-24 to trunk [The section on git merge procedure has not yet been written] |