Copyright © 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Bill Wohler
The MH-E Developers Guide is free documentation; 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 MH-E Developers Guide 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.
The GNU GENERAL PUBLIC LICENSE appears as an appendix to this document. You may also request a copy by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
So you want to be an MH-E developer. This document describes the steps you need to take to get there. First, it captures the philosophy of the development team. There is then a section for each feature in the SourceForge site, where MH-E development is hosted.
In other words, this is the single sheet of music that all the MH-E developers are playing.
And remember, this is your document. If you think something is bogus, start a movement on the mh-e-devel@lists.sourceforge.net mailing list. One of the tenets of the philosophy is rough consensus. If you can get a rough consensus that agrees with your point of view, then the document shall be changed accordingly.
A project admin is the one who can effect changes at the SourceForge site, accept news items, bugs, patches and so on. The project admin is currently Bill Wohler <wohler@newt.com>.
A developer is one who is given the right to check in changes into the CVS repositories and be assigned bug reports. Users on the mh-e-devel@lists.sourceforge.net mailing list who do not have CVS access contribute by submitting patches to the Patch Manager (see Patch Manager).
There are a few minor prerequisites to get out of the way if you wish to contribute to the MH-E project. The first is to get an account at SourceForge, the second is to get an account at Savannah, the third is to get on the mh-e-devel mailing list, and the fourth is to get on the emacs-devel mailing list. The latter is optional for all except the project admin.
Developers should be familiar with the Emacs Lisp Manual as well as the Emacs Manual.
If you think that you want to become an MH-E developer, please contact the project admin1. Generally speaking, if you have contributed to the MH-E mailing lists and comp.mail.mh newsgroup over the years, you will be given CVS privileges as soon as you have submitted your papers (see below). If you are new, the project admin may ask you to prove your mettle by contributing to the mh-e-devel@lists.sourceforge.net mailing list and submitting patches. Do submit your paperwork anyway, since the legal process will most likely take longer than it takes for us to get to know you.
You will need to sign papers with the Free Software Foundation to gain access to the CVS repositories at SourceForge and at Savannah. The repositories at Savannah contain the MH-E source code, images, and documentation. The repository at SourceForge contains everything else such as the web pages and files for unit testing and releasing.
First, please read Information For Maintainers of GNU Software. The section, Legal Matters, in particular will help you understand the following step.
As stated above, you must first submit a assignment of copyright to the Free Software Foundation to gain access to the CVS repositories. It would be best if you could fill out the request-assign.future form included below. I've entered Emacs rather than MH-E as the name of the package since that is recommended for Emacs developers (since MH-E developers are Emacs developers). Note that your answers will be incorporated into a longer, official form that will be mailed to you. This you will have to sign and return to the Free Software Foundation.
If you have any questions or would like to know whether you are already listed in copyright.list, please send a note to the project admin2.
Please email the following information to assign@gnu.org, and we
will send you the assignment form for your past and future changes.
**PLEASE USE YOUR FULL NAME AS THE SUBJECT LINE OF THE MESSAGE.***
[What is the name of the program or package you're contributing to?]
Emacs
[Did you copy any files or text written by someone else in these changes?
Even if that material is free software, we need to know about it.]
[Do you have an employer who might have a basis to claim to own
your changes? Do you attend a school which might make such a claim?]
[For the copyright registration, what country are you a citizen of?]
[What year were you born?]
[Please write your email address here.]
[Please write your snail address here.]
[Which files have you changed so far, and which new files have you written
so far?]
Once you have SourceForge and Savannah logins and the legal matters out of the way, you need to request MH-E and Emacs developer status. To gain MH-E developer status, send an email to the project admin3 with your SourceForge login. To gain Emacs developer status, go to the My Group Membership page, search for Emacs in the Request for Inclusion section, check the box next to Emacs, and mention that you're a MH-E developer and that you've completed your papers in the comment box, and submit your request.
On a less serious note, there is a page with the pictures of the developers. Send the project admin4 a URL to your picture and a URL to your home page or whatever which is where folks would go if they clicked on your picture. Also send a fun "Job Title". Feel free to add your own picture (see Project Home Page).
This chapter discusses the philosophy and principles of the MH-E project. The first section covers our coding philosophy, while the second section summarizes the principles of the team that have evolved over time.
The core philosophies of the MH-E project regarding the code are as follows:
That last priority struggles mightily with the other priorities. For example, the user could write his own hooks for many features. However, the average user is not going to do so. Indeed, the customization buffer may be too intimidating and providing radio buttons and checkboxes in the menu may be the way to go in some cases.
In a less contentious way, making MH-E easier to use may mean better
integration with other software packages (such as tm or
goto-addr). Or pre-written hook functions could be provided. We
should get as much mileage out of customize as we can to reduce
the amount of code that users have to write.
See Version Numbers.
The guiding principles of the MH-E developers are:
The Emacs Lisp Tips and Conventions must be followed. In addition, please observe the conventions described in this chapter.
provides and filename in the
footer accordingly.
Because you have assigned all copyrights to the FSF, the Copyright must read:
;; Copyright (C) <year> Free Software Foundation, Inc.
Please read Copyright Notices in Information For Maintainers of GNU Software. In addition, Richard Stallman notes that it is no disaster to split the copyright onto multiple lines.
You must also reference the GPL correctly. Using an existing header will guarantee that this is done.
The manual must also follow these rules since it is packaged with GNU Emacs.
It is preferable, but not required, that files in the contrib
directory follow these rules to make it easier to incorporate them
into the src directory in the future.
Exceptions to these rules include support files in src that are not included in GNU Emacs. In this case, the author may list their name in the copyright and should replace GNU Emacs in the license with MH-E.
The other directories do not need to follow these rules. However, all files must carry the GPL so that others may modify them.
mh-require-cl to require
cl.
;;;###mh-autoloads whenever a function
is needed in another file. Remove autoload cookies from functions that
aren't shared.
grep '^;;; ' *.el | egrep -v '(Commentary:|Change Log:|Code:)'
Leave a blank line before and after both the page feed and heading.
(code)
^L
;;; Heading
(code)
eval-when-compile as it is unnecessary according to an
email from Richard Stallman.
;; Shush compiler.
(defvar mh-identity-pgg-default-user-id)
(defvar mm-verify-function-alist) ; < Emacs 22
(defvar pressed-details) ; XEmacs
(defvar which-func-mode) ; < Emacs 22, XEmacs
defvar. When it is
necessary to add a value to this defvar, add a comment to the
actual definition that says to update the forward definition
accordingly if the default value changes. Note that customization
variables must not have a forward definition, or the user's
customization will be clobbered.
Foo...done messages should not end in a period, but
they aren't explicit about messages in general. Given what the
conventions do say, and because most of our messages don't end
with a period, let's just say that messages in general don't end in a
period, just like error messages.
yes-or-no-p or
y-or-n-p prompts, but not in other prompts that use
completing-read and offer defaults. In these cases, use colons
at the end of the prompt instead. The prompt, including the default
with proper white space, should look like this: Prompt (default: default): >. The “>” character is the cursor.
help-mode find the hyperlink.
checkdoc
insists that flag variables begin, `Non-nil means...'. Use
headline capitalization for option values. Use “Auto-detect” text
when option has that capability.
defcustom and
defface whose docstring can be seen in non-MH-E contexts. Since
docstrings for MH-E functions are most likely viewed with C-h k,
the map does not have to be cited for functions in the same keymap.
make recompile in
emacs/lisp) and with make in mh-e/src with the
previous version of Emacs as well as XEmacs.
for i in *.el; do
package=`basename $i .el`
emacs -q --eval '(setq load-path (cons "." load-path))' \
-l mh-autoloads.el \
--eval "(progn (require '$package) (switch-to-buffer \"*Messages*\"))"
done
lm-verify within the lisp file you are editing to ensure that
all of the fields described in
Conventional Headers for Emacs Libraries
are present. The checkdoc function must be run before check-ins
as well. All errors must be fixed. These tests are automated in
mh-unit.
The CVS Repository at SourceForge contains several modules. You can view the repository with CVSWeb. You can access the repository with this:
export CVS_RSH=ssh
cvs -z3 -d $USER@mh-e.cvs.sourceforge.net:/cvsroot/mh-e co module
where module is one of:
set-key and autoload or add-hook
statements to allow users to incorporate these features with a minimum
of configuration. Any customization must occur via the customize
package.
You can check out all of the modules at once with:
export CVS_RSH=ssh
cvs co -z3 -d $USER@mh-e.cvs.sourceforge.net:/cvsroot/mh-e .
That's a dot at the end of the check out command.
After checking out MH-E from SourceForge, you'll have a mh-e/src directory that is lacking .el files and images. These are stored in the Emacs repository at Savannah. You have several means of getting these files:
This is the simplest choice and best for users who want to run CVS MH-E but do not run CVS Emacs. A drawback of this choice is that if you're developing MH-E, you won't be able to easily verify that your changes work with CVS Emacs.
Assuming your USER environment variable is the same as your Savannah
login, make will check out just the MH-E portions of Emacs into
your mh-e/src directory. If your login differs, override the
USER variable as follows:
USER=user make
Users who check out MH-E from CVS who do not have Emacs repository privileges will have to use anonymous CVS:
USER=anoncvs make
If you already have CVS Emacs, link mh-e/src/emacs to it. This makes it easier to check your changes against multiple versions of Emacs5. Assuming Emacs and MH-E are at the same level:
cd mh-e/src
ln -s ../../emacs/
This is very similar to the previous option. Emacs developers would use:
cd mh-e/src
cvs -z3 -d $USER@savannah.gnu.org:/cvsroot/emacs co emacs
while others would use:
cd mh-e/src
cvs -z3 -d anoncvs@savannah.gnu.org:/cvsroot/emacs co emacs
If you only check out the src module and don't make use of any
of the files within, you could develop MH-E entirely within CVS
Emacs and not bother checking anything out from SourceForge. However,
this is not recommended since compilation takes longer and you don't
have access to tools such as mh-unit. However, this is a
reasonable thing to do if you're a user who wants to run both CVS
Emacs and CVS MH-E since you get CVS MH-E in CVS Emacs.
The process for checking in files is simple as we try to keep things as frictionless as possible:
When the file is checked in, a report is generated and mailed to mh-e-devel@lists.sourceforge.net. Developers are encouraged to review the attached diff for correctness, and to become familiar with more of the MH-E code.
One should consider backing out or correcting a patch if only one person complains and their complaint rings true. But the hard and fast rule is that if 1/3 of the developers (rounding up) protest the check-in, then the update needs to be remedied to the developers' satisfaction or backed out. Otherwise, it is assumed that the consensus thinks that the patch is a good thing.
If developers are unsure about a particular update, they are encouraged to post a patch for review before checking in the file.
Each module should have its own ChangeLog. Change logs are cool because they summarize all the changes in one place, and provide visibility to the changes to those who do not have access to the CVS repository.
Here is an example ChangeLog entry:
2006-07-03 Bill Wohler <wohler@newt.com>
Release MH-E version 8.0.2.
* README: Update for release 8.0.2.
2006-06-15 Bill Wohler <wohler@newt.com>
* mh-search.el (mh-index-new-folder): Use -2 suffix instead of <2>
suffix for folder names, as <> are illegal filenakme characters on
Windows (closes SF #1507002).
The first bullet shows the text that should be used when releasing a module.
As usual, the string in parenthesis indicates the documentation
section, Makefile variable or target, or program function or variable.
If you do not use the Emacs ChangeLog commands such as C-x
4 a (add-change-log-entry-other-window) which inserts this
text for you (even from a diff!), please do follow its conventions.
Multiple targets with the same text may appear in the same entry.
For consistency, phrase the issue number as follows (see Updating MH-E-NEWS):
(closes SF #621632).
or
(closes Debian #234234).
The Emacs manual has full documentation on the ChangeLog commands.
For more information regarding the style of the ChangeLog entries, please see the GNU Coding Standards. One convention that is not listed explicitly is that ChangeLog entries should be written in the present tense.
The conventions for checking files into the Emacs repository are as follows:
For example, given the ChangeLog in the previous section, here is what the log for mh-search.el would look like:
(mh-index-new-folder): Use -2 suffix instead of <2> suffix for folder
names, as <> are illegal filename characters on Windows (closes SF
#1507002).
It is not necessary to add release information since that information will be encoded in the tags.
At worst, setting the log information will be a cut and paste
operation. At best, it will be a keystroke or two. In pcl-cvs, you can
simply hit C (cvs-mode-commit-setup) and you'll get a
buffer in log-edit-mode initialized with the appropriate
entries from the change log. Or, you can suck in the change log
entries with C-c C-a (log-edit-insert-changelog) if you
use VC.
I specify the following for log-edit-hook to automate the
re-filling of the log message:
(defun bw-log-edit-hook ()
"Updates variables and fills region.
In particular, `paragraph-start' is modified to handle filenames
for check-ins involving multiple files."
;; Avoid adding text to paragraph-start over and over again.
(set (make-local-variable 'paragraph-start)
(concat paragraph-start "\\|\\s *\\s("))
(fill-region (point-min) (point-max)))
Note that this allows for multi-file commits; while this practice is not encouraged in the Emacs repository, it can be used elsewhere.
If you're editing, for example, mh-e/src/emacs/lisp/mh-e/mh-e.el, and wish to compile MH-E from within Emacs with mh-e/src/Makefile, use:
M-x compile RET (cd ../../..; make) RET
The MH-E project supports three mailing lists: mh-e-users@lists.sourceforge.net, mh-e-devel@lists.sourceforge.net, and mh-e-announce@lists.sourceforge.net. None of the lists are included in any other, so MH-E developers should subscribe to all of them.
mh-e-users@lists.sourceforge.net is for general discussion between users and developers. Developers discussing ways to implement bug fixes or features should probably keep the discussion on mh-e-users@lists.sourceforge.net to stimulate feedback from the user community.
mh-e-devel@lists.sourceforge.net is used by MH-E developers to announce CVS check-ins and discuss SourceForge issues that would not be of interest to mh-e-users@lists.sourceforge.net subscribers.
mh-e-announce@lists.sourceforge.net is used to announce new releases of MH-E. Other news items pertinent to MH-E may be posted there as well.
The Support Requests page doubles as the MH-E FAQ. Notifications of new support requests and changes to support requests are mailed to the mh-e-devel@lists.sourceforge.net mailing list. Developers are encouraged to field any questions that they can answer. After answering a question, set the status to Closed. Categories will be created if the need arises.
Bug reports, feature requests, and discussions that are expected to lead to bug reports or feature requests are created in Bugs. Most bugs should be set to the default priority of 5.
Developers should follow the bug-gnu-emacs mailing lists/newsgroup and move bug reports into Bugs if it has not been done already. Similarly, MH-E bugs reported in other systems should be transferred to SourceForge. The bug may be cut and pasted into a new bug report, or a URL to the source of the original bug report may be all that appears in the bug report.
A brief life cycle of a bug proceeds something like this. A bug is entered. A developer ensures that the Category, Priority and Group are correct. The Group for an Open bug should be set to the version of software in which the bug was found, or CVS if it was found in the latest and greatest.
The assignment of bugs in Bugs follows the honor system. If you see an open bug that you think you could handle, assign the bug to yourself. The project admin (wohler) reserves the right to assign bugs to others.
If you fix a bug, set the resolution to Fixed and group to CVS. Please also assign the bug to yourself if you have not done so already, so you get credit in the reports. If a documentation change is not required, set the status to Closed. If a documentation change is required, set the category to Documentation, and assign the bug to the documentation czar (wohler), leave the status Open, and set the priority to 3 to set it aside in listings sorted by priority.
See File Releases for a motivation of why this process is useful.
The rest of this section describes the categories and groups that have been set up for the MH-E project.
Several categories have been created for the MH-E project organized by function. They include General, UI, MIME, Security, Documentation, and Contrib
The bug status is divided into four sections: Open, Closed, Deleted and Pending.
The Bugs and Feature Requests sections are also used as a method to get the ball rolling among developers. They are used to register what we feel we should work on. For example, a developer may have questions about the way MH-E handles MIME that we should discuss before we attempt to fix it: What do other people do? How should we attack this? That developer opens a bug report in the MIME category and a discussion ensues. Once the disposition of the issue is resolved, the bug is assigned to a developer. Later, when the bug is fixed, the bug can be closed.
Discussion about entirely new features should be opened in the Feature
Requests section (see Feature Requests) but otherwise handled in
the same way.
When setting the status to Closed, the group should be set to Fixed,
Works For Me, Invalid, or Rejected.
The bug group contains several items. They include:
A bug can appear in various states:
In bug reports, use Invalid, Won't Fix, or Works For Me instead.
Use Rejected for feature requests.
When developers receive notice of new Feature Requests, they should comment on the feature's usefulness and integrity. After a a couple of positive comments have been added, the project admin (wohler) will set the status to Accepted. Otherwise, the project admin will set the status to Closed and the group to Wont Fix. If the feature request is accepted, anyone may assign the request to themselves and implement the feature.
After incorporating the feature, update the feature request as described in the previous section (see Bugs).
When developers receive notice of new patches in the Patch Manager they should comment on the patch's usefulness and integrity. After a couple of positive comments have been added, the project admin (wohler) will set the status to Accepted. Otherwise, the project admin will set the status to Closed and the group to Wont Fix. If the patch is accepted, anyone may assign the patch to themselves and incorporate the patch. After incorporating the patch, set the status to Closed. Categories will be created if the need arises.
Legally speaking, patches that are less than 15 lines can usually be incorporated, although it is always best to try to incorporate them in a “clean room” environment. Do read Legally Significant Changes for the details.
Note that developers need not use the Patch Manager. Instead, they should check in changes directly (see CVS Repository).
This section contains information about how the MH-E project releases software. In additional to making tarballs available, the software and documentation must be incorporated into Emacs and the online documentation must be updated.
One of the goals of the release process is to keep iterations short so that the timeliness and quality of releases is increased from the user's point of view. For the developer's sanity, it should be clear when we're done by limiting the scope of the release and avoiding the addition of new features late in the cycle.
Here's a suggestion for an iteration cycle when development is moving quickly.
Each developer goes through the bugs and feature requests and chooses a month's worth of work for him to do. For each selected item, he increases the priority to 7 and assigns the task to himself. Another guideline for release size is that releases should only include 7 +/- 2 new features or bug fixes.
The first month should be full of fervent activity. Development should slow down in the second month while the new features are fine-tuned. The third month is devoted to the release itself (see table below). This process should result in quarterly releases.
It is acceptable and often desirable to shorten each step in this cycle in order to keep the number of release note bullet items to 7 +/- 2, but in order to keep the releases fresh, it's probably not a good idea to lengthen the process.
If a new bug or feature arises that a developer wants to work on, the developer sets the priority of that item to 7 and resets the priority of one of his other items back to 5. This keeps the release from growing without bound.
The following table shows a formal schedule for a release. This is used in major releases or when it seems necessary. Many releases are of the “release early, release often” variety. When development is proceeding slowly, releases might occur after a feature has been added or a bug fixed without going through freezes and beta releases.
If the circumstances warrant, post the milestones leading up to that release as a news item (see News).
Time Milestone Description
T-3 months Development
T-2 months Refinement New features are fine-tuned.
T-4 weeks Soft Freeze All P7 and higher features must be committed. P6 features should be committed. Any other new features destined for the release must be committed no later than this time. However, note that it is advisable not to release new user-visible features this late in the game. It is better to add new features at the beginning of a release cycle to allow for suitable usability testing. Testing commences.
T-3 weeks Hard Freeze All P7 and higher bug fixes must be committed. P6 bug fixes should be committed. Testing continues.
T-2 weeks Beta 1 Cut beta release. Upload to SourceForge.
T-1 weeks Beta 2 Cut beta release. Upload to SourceForge.
T-0 weeks Release! Cut release. Upload to SourceForge.
Normal releases that include new features and bug fixes are minor releases. For minor releases, incompatible changes may not be made.
In some cases, there is a bug that needs to be fixed and released quickly and requires no change in MH-E-NEWS. In these cases, a patch release that includes only that fix is used.
Major releases signal to the user that the new version may not work as it did before and that reading of the release notes is mandatory. Major releases occur when incompatible changes are made that are visible to the user. Types of changes include changing the name of or deleting functions, key bindings, and customization variables. The converse is true; these sorts of changes should not be applied to minor releases.
By itself, merely adding a new feature does not justify a major release. On the other hand, a major release is called for if the code is completely rewritten, even if the user cannot notice any difference.
Beta releases bump the patch or minor number of the previous version to 90 for a planned minor or major release respectively.
For example, if 5.0 or 5.0.2 was the last release of MH-E and 5.1 is planned as the next release, then the beta is numbered 5.0.90. Subsequent betas would be numbered 5.0.91, 5.0.92 and so on. If, instead, 6.0 is planned as the next release, then the beta is numbered 5.90 and subsequent betas would be numbered 5.91, 5.92 and so on.
Alpha releases bump the patch or minor number to 80.
The first thing to do is to check the code for coding convention compliance as described in Coding Conventions. This can be done by running M-x mh-unit.
Next, go to Bugs and search for all bugs whose status is Open, group is CVS, and category is Documentation. Repeat for Feature Requests and Patches. If these searches reveal any undocumented features, document them before proceeding.
When the src module is released (see CVS Repository), the
file emacs/etc/MH-E-NEWS needs to be updated. Separate the old
news with the new with a C-l (unless both the new and old news
are only a paragraph long) and follow the existing format for
documenting user-visible changes only including New Features, New
Variables, and Bug Fixes. List SourceForge issues as (closes SF
#123456), as well as third-party issues such as (closes SF
#123456, Debian #123456).
In order to find what is appropriate for MH-E-NEWS, several things can be done.
release-utils --variable-changes previous-tag to
produce a list of new and deleted variables suitable for inclusion in
MH-E-NEWS.
[0-9][0-9][0-9][0-9][0-9][0-9] in the
ChangeLog to get a list of SF numbers.
The previous steps usually catch most items. To use a finer sieve, use the following commands. These assume that the last version of the MH-E package was 6.0.
cvs log -rprevious-tag
cvs diff -rprevious-tag
See Updating ChangeLog before checking in this file.
Update etc/NEWS by adding text similar to the following:
* Changes in Emacs 21.4
** MH-E changes.
Upgraded to MH-E version 6.1. See MH-E-NEWS for details.
It's possible that the update occurs before Emacs had been released with a previous version of MH-E; in this case, simply bump the version number in the text above rather than add an entire new stanza.
See Updating ChangeLog before checking in this file.
Ensure that the target Emacs version is correct, as well as the supported Emacs versions.
Update the version number in various places in the INSTALL section.
If the manual was updated and will be released as well, update its README similarly.
See Updating ChangeLog before checking in this file.
Update the variable mh-version and the version in the
Version header field in emacs/lisp/mh-e/mh-e.el.
See Updating ChangeLog before checking in this file.
When releasing MH-E, three ChangeLog files need to be modified. Use the following entries when checking in README, emacs/etc/MH-E-NEWS and emacs/etc/NEWS, and emacs/lisp/mh-e/mh-e.el (see Updating MH-E-NEWS, Updating NEWS, Updating README, and Updating mh-e.el):
Release MH-E version 6.0.
* README: Update for release 6.0.
Release MH-E version 6.0.
* NEWS, MH-E-NEWS: Update for MH-E release 6.0.
Release MH-E version 6.0.
* mh-e.el (Version, mh-version): Update for release 6.0.
Run a separate check-in in each directory. If the doc module is being released as well, two additional ChangeLog files need to be modified. Here are sample entries for them.
Release MH-E manual version 8.0.1.
* README: Update for release 8.0.1.
Release MH-E manual version 8.0.1.
* mh-e.texi (VERSION, EDITION, UPDATED, UPDATE-MONTH): Update for
release 8.0.1.
It is critical that a snapshot of the software is created each time the software is released. In CVS, this is performed with tags.
Tags should have the form identifier-M_N_P where M is the major number, N is the minor number, and P is the patch number. An underscore is used since one cannot use dots in CVS tag names. The P portion is optional.
Since the modules will most likely have different release schedules, each module will have different identifiers and version numbers in the tags. The identifiers used include:
Module Identifier
src mh-e
doc mh-e-doc
contrib mh-e-contrib
Here is an example that shows recent releases of each module. Because
the src and doc modules coexist with CVS Emacs, more
care with tagging is necessary since we do not want to add these tags
to all of Emacs. Hence, the tagging is done via make.
make TAG=mh-e-8_0 tag
make TAG=mh-e-doc-8_0 tag
cvs tag mh-e-contrib-1_0
It is difficult to say when one should tag the software. In some
cases, the files can be tagged immediately before the release. In
other cases, particularly with the src module, it may be well
to tag at the hard code freeze to protect ourselves from changes made
by Emacs developers who might not be following mh-e-devel.
It is also important to ensure that an upcoming Emacs release contains a released version of MH-E. This is accomplished by updating the Emacs release tag with the same version as the latest MH-E tag. It's best to get permission on emacs-devel@gnu.org before doing so. The mechanism is demonstrated in the following example:
make TAG=EMACS_21_2 tag-emacs
This command updates the EMACS_21_2 tag with the version of the latest tag that begins with mh-e- in MH-E.
The modules in the CVS Repository (see CVS Repository) map to the distribution tarballs as follows:
Module Tarball
src mh-e-M.N.tgz
doc mh-e-doc-M.N.tgz
contrib mh-e-contrib-M.N.tgz
The tarballs listed in the table above are built as follows:
export CVS_RSH=ssh
cvs -z3 -d $USER@mh-e.cvs.sourceforge.net:/cvsroot/mh-e co -r release -d module-M.N module
cd module-M.N
make emacs
cvs update -r release
In the doc module, repeat this command within the man sub-directory since the update command will not recurse into it as it is not where CVS expects it to be.
make dist
The make dist command ensures that the tarball is named correctly
and that the tar extracts in a subdirectory that has the same name as
the tarball's prefix. For example, if release was mh-e-5_2, then
the tarball would be named mh-e-5.2.tgz and would extract into the
directory named mh-e-5.2.
First, create the tarballs (see Creating Tarballs). Then add the release per the instructions in The File Release System.
Use the entire README file for the release notes.
For the src module, use the appropriate section of the emacs/etc/MH-E-NEWS file for the Change Log.
When updating the Change Log for the doc and contrib releases, first write a paragraph in a scratch buffer that summarizes the release, putting the most important things in the first sentence. Then, insert the ChangeLog entries. In the case of the doc release, merge the entries for mh-e.texi in man/ChangeLog into the existing ChangeLog entries. Use the combined result for the Change Log.
Be sure to check the box labeled Preserve my pre-formatted
text.
If there were any beta releases leading up to this release, edit the release and set the Status to Hidden.
After MH-E is released, update the tracker.
First, change the name of the group CVS to mh-e-m.n for bugs, features, and patches. For example, when MH-E version 6.0 is released, rename the CVS group to mh-e-6.0. Then create a new CVS group. This should be done for contrib releases too.
An exception to this occurs when releasing beta releases. The group name in the series of beta releases leading up to the actual release is reused. That way, in the end all the existing issues are left pointing to the actual release rather than a beta. For example, CVS would first be renamed to mh-e-6.1.90. In the next release, rename this group to mh-e-6.1.91 and perform a mass update by moving all issues (in bugs, features, and patches) from the CVS group to the mh-e-6.1.91 group. Continue in this fashion through release mh-e-7.0.
Another oddity can occur when you make a patch release. If all of the closed CVS items are in the patch, then proceed as normal. However, if any of the closed CVS items are destined for a major or minor release, then renaming the CVS group to mh-e-m.n.p would be incorrect. In this case, create a new mh-e-m.n.p group for bugs, features, and patches (rather than rename CVS), and perform a mass update by moving all the relevant bugs or features to the new patch release.
Now that the release is ready for download, announce it as described in News.
This task is the duty of Peter Galbraith <psg@debian.org>. It may be useful to others to want to make an unofficial package of the CVS tree.
To build a Debian package, you'll need to have installed the Debian
package build-essential as well as those listed in the
Build-Depends-Indep: line of the file debian/control.
Currently, there are the packages debhelper and texinfo.
The package fakeroot is also used below and dpkg-dev-el
is also useful.
apt-get install build-essential fakeroot debhelper texinfo dpkg-dev-el
Run the following commands from the top of the CVS tree to clean up the tree of backup files and make a source tar file:
rm `find . -name "*~"`
debian/rules source
This will make a new file such as mh-e_7.0.orig.tar.gz. Unpack
it in a working directory and step into its top directory. Edit the
first line of the file debian/changelog to change the version
number between parentheses to something appropriate (e.g.
7.0.+cvs-0), or add another entry to the changelog and edit the
version number. If you installed the package dpkg-dev-el above,
simply do C-c C-v to insert this block and C-c C-f to
finalize the entry when done editing the version number.
You can then create a Debian package by running:
fakeroot debian/rules binary
This creates ../mh-e_7.0.+cvs-0_all.deb which can be installed using standard Debian package management:
dpkg -i ../mh-e_7.0.+cvs-0_all.deb
This task is the duty of Bill Wohler <wohler@newt.com>. It may be useful to others to want to make an unofficial package of the CVS tree.
The rest of this section needs to be completed.
This task is the duty of Bill Wohler <wohler@newt.com>. Other developers may skip this section.
To install an updated version of the manual online at SourceForge:
ssh mh-e.sourceforge.net
cd /home/groups/m/mh/mh-e/doc
cvs update -Pd
make
Update the file MH-E.txt in the FSF/UNESCO Free Software Directory. See Free Software Directory.
After the release is complete, add the string +cvs to the
version number. See Updating mh-e.el.
Announcements about new releases are submitted at SourceForge and to mh-e-announce@lists.sourceforge.net.
The document Using Project News with Step-by-Step Instructions is helpful when composing your news item.
In all cases, use the following template for the subject:
MH-E m.n.p released
MH-E contributed software m.n.p released
MH-E manual m.n.p released
The easiest thing to do is emulate the look and feel of previous news postings. The postings should be written using the following guidelines.
First, include the release notes from emacs/etc/MH-E-NEWS. To
avoid ugly wrapping, first make every paragraph one line by copying
the release notes into a scratch buffer, setting the fill column to
some very large number, and running fill-region.
Then precede the first sentence from the release notes with the first sentence from the description on the Summary page to describe MH-E to readers who are unfamiliar with the project. The introduction to the release notes should briefly describe the benefit of the release or otherwise entice the reader to read further.
Then insert the following two sentences between the introduction and the New Features section.
Read on for more details.
Project home page at: http://mh-e.sourceforge.net/.
The contrib and doc releases, which do not have release notes, should replace the MH-E-NEWS excerpt with the Change Log created earlier. See Creating SourceForge Releases.
Note that your news posting may be shown on the SourceForge front page, so discretion is advised. Also keep in mind that only the first two sentences are shown on the SourceForge front page. Since the first sentence is fixed, the second sentence–which is the first sentence of the introduction to the release notes–should be written wisely.
Once your news posting is written and formatted, submit it.
The announcement that is sent to the mh-e-announce@lists.sourceforge.net mailing list doesn't have the same first-paragraph restrictions as does the SourceForge news item. Therefore, the announcement should contain the text:
Project home page at: http://mh-e.sourceforge.net/.
followed by the release notes. However, the announcement for contrib and doc releases, which lack release notes, should be mimic the news item minus the first introductory sentence (since readers of mh-e-announce already know what MH-E is).
The MH-E home page contains a brief overview of the MH-E project. This web space also includes other internal documents, such as this one.
To update these documents, check out the htdocs module (see CVS Repository). The home page is the file index.php, while this document is in doc/devguide.texi. Make your changes and check them in.
To install your updates into the MH-E web space at SourceForge:
ssh mh-e.sourceforge.net
cd /home/groups/m/mh/mh-e/htdocs
cvs update -Pd
make
The FSF/UNESCO Free Software Directory contains a description of all of the free software, including MH-E. It is the responsibility of the project admin6 to keep the entry for MH-E up to date. It must be updated when there is a release of MH-E, or when a significant new feature has been added which should be advertised.
This entry is the master for the short and long descriptions of MH-E in various places including the SourceForge page, the MH-E home page, the Debian package, and the XEmacs package. These items should be updated each time the master entry is modified.
In order to update the entry, first check out the directory via anonymous CVS:
cvs -d anoncvs@savannah.gnu.org:/cvsroot/directory login
cvs -z3 -d anoncvs@savannah.gnu.org:/cvsroot/directory co directory
Then make the desired changes to MH-E.txt. For new releases, this includes the source-tarball and version fields. Next, update the touched field. If the changes were significant enough to be announced, update the updated field as well. These and other fields are described in the README in the same directory.
Send the patch to bug-directory@gnu.org. For more information, see the instructions.
Finally, if any changes were made to the short or long descriptions, it is likely that the following will have to be updated: the SourceForge MH-E project description (see Editing the SourceForge Project Description), the top-level index.php file in the Project Home Page (see Project Home Page), the control file in the Debian package (see Updating the Debian Package), and the XEmacs package (see Updating the XEmacs Package).
This section contains a few additional items from the SourceForge web site. Some of these items have been deactivated; the sections are preserved here for completeness and to explain why they have been deactivated.
This task is the duty of Bill Wohler <wohler@newt.com>. Other developers may skip this section.
The data for the various trackers should be backed up at least once a month or so. To do this, click on the XML Data Export link (which was taken from the the Admin > Backups page) and save the page.
Most activity occurs either in Bugs (see Bugs), or the Patch Manager (see Patch Manager). However, in the future, we may wish to use the Task Manager as well.
The DocManager has been deactivated since all of the documentation is found on the Project Home Page.
The Public Forums section has been deactivated since discussion should take place on the mh-e-devel@lists.sourceforge.net and mh-e-users.sourceforge.net mailing lists. See Mailing Lists.
Copyright © 1989, 1991 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software—to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things.
To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it.
For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software.
Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations.
Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all.
The precise terms and conditions for copying, distribution and modification follow.
Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does.
You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.
Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program.
In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.
If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code.
If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.
This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.
Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and “any later version,” you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation.
If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.
one line to give the program's name and an idea of what it does.
Copyright (C) 19yy name of author
This program 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
of the License, or (at your option) any later version.
This program 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 this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
Also add information on how to contact you by electronic and paper mail.
If the program is interactive, make it output a short notice like this when it starts in an interactive mode:
Gnomovision version 69, Copyright (C) 20yy name of author
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
type `show w'. This is free software, and you are welcome
to redistribute it under certain conditions; type `show c'
for details.
The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `sho