   Information for maintainers of GNU software.  Copyright (C) 1992,
1993, 1994, 1995, 1996, 1997, 1998, 1999 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

Version
*******

   Last updated April  8, 1999.

About This Document
*******************

   This file contains guidelines and advice for someone who is the
maintainer of a GNU program on behalf of the GNU project.  Anyone can
change GNU software, and you need not read this file just to do that.
But if you want to maintain a version for widespread distribution, then
this file becomes important for you.

   Please send corrections or suggestions for this document to
<gnu@gnu.org>.  If you make a suggestion, please include a suggested
new wording for it; our time is limited.  We prefer a context diff to
the `maintain.texi' file, but if you don't have that file, please mail
your suggestion anyway.

   This document uses the gender-neutral third-person pronouns "person",
"per", "pers" and "perself."  They are used just like "she", "her",
"hers" and "herself", except that they have no implications about
gender.  For example, "Person placed per new program under the GNU GPL,
to let the public benefit from per work, and to enable person to think
well of perself."  These pronouns were promoted, and perhaps invented,
by Marge Piercy in `Woman on the Edge of Time'.

   The directory `/gd/gnuorg' is found on the GNU machines; if you are
the maintainer of a GNU package, you should have an account on them.
Contact <gnu@gnu.org> if you don't have one.  `/gd/gnu/maintain.tar.gz'
is a tar file containing all of these files in that directory which are
mentioned in this file; it is updated daily.

   This release of the GNU Maintenance Instructions was last updated
April  8, 1999.

Legal Matters
*************

   When incorporating changes from other people, make sure to follow the
correct procedures.  Doing this ensures that the FSF has the legal right
to distribute and defend GNU software.

Copyrights
==========

   This section applies *if* the package you are maintaining is
copyright Free Software Foundation.

   For the sake of registering the copyright on later versions of the
software, you need to keep track of each person who makes significant
changes.  A change of ten lines or so, or a few such changes, in a
large program is not significant.

   *Before* incorporating significant changes, make sure that person
has signed copyright papers and that the Free Software Foundation has
received and signed them.

   To check whether papers have been received, look in
`/gd/gnuorg/copyright.list'.  If you can't look there directly,
<fsf-records@gnu.org> can check for you, and can also check for papers
that are waiting to be entered and inform you when expected papers
arrive.

   The directory `/gd/gnuorg' is found on the GNU machines; if you are
the maintainer of a GNU package, you should have an account on them.
Contact `gnu@gnu.org' if you don't have one.

   In order for the contributor to know person should sign papers, you
need to ask for the necessary papers.  If you don't know per well, and
you don't know that person is used to our ways of handling copyright
papers, then it might be a good idea to raise the subject with a
message like this:

     Would you be willing to assign the copyright to the Free Software
     Foundation, so that we could install it in ....

or

     Would you be willing to sign a copyright disclaimer to put this
     change in the public domain, so that we can install it in ....

   If person wants more information, you can send per
`/gd/gnuorg/conditions.text', which explains per options (assign vs.
disclaim) and their consequences.

   Once the conversation is under way and the contributor is ready for
more details, you should send one of the templates that are found in
`/gd/gnuorg'.  This section explains which templates you should use in
which circumstances.  *Please don't use any of the templates except for
those listed here, and please don't change the wording.*

   Once the conversation is under way, you can send the contributor the
precise wording and instructions by email.  Before you do this, make
sure to get the current version of the template you will use!  We change
these templates occasionally--don't keep using an old version.

   For large changes, ask the person for an assignment.  Send the
person a copy of the file `/gd/gnuorg/assign.changes', but first, go to
the second page and insert per name and the name of the program
involved in place of `NAME OF PERSON' and `NAME OF PROGRAM'.  Do this
before sending, because otherwise person might sign without noticing
them.  Then the papers would be useless.

   For medium to small changes, ask per to fill out and return the
disclaimer in the file `/gd/gnuorg/disclaim.changes'.

   If the contributor is likely to keep making changes, person might
want to sign an assignment for all per future changes to the program.
So it is useful to offer per that alternative.  If person is
interested, send per the template in `/gd/gnuorg/assign.future'.

   Before signing this, person needs to ask per employer for a
disclaimer-in-advance; the template for this is in
`/gd/gnuorg/disclaim.future', so you should send that file as well as
`assign.future'.  (It is more convenient to send them in separate
messages.)

   We need legal papers for changes in manuals as well as for changes in
software.  For smaller changes, use
`/gd/gnuorg/disclaim.changes.manual'; for larger ones, use
`/gd/gnuorg/assign.changes.manual'.  To cover both past and future
changes to a manual, you can use `/gd/gnuorg/assign.future.manual'.

   If a contributor is reluctant to sign an assignment for a large
change, and is willing to sign a disclaimer instead, that is
acceptable, so you should offer this alternative if it seems useful.
While we prefer an assignment for a larger change, so that we can
enforce the GNU GPL for the new text, a disclaimer is enough to let us
use the text.

   If you maintain a collection of programs, occasionally someone will
contribute an entire separate program or manual that should be added to
the collection.  Then you can use the files `assign.program',
`disclaim.program', `assign.manual', and `disclaim.manual'.  We very
much prefer an assignment for a new separate program or manual, unless
it is quite small, but a disclaimer is sufficient to let us use the
work.

   *Although there are other templates besides the ones listed here,
they are for special circumstances; please do not use them without
getting advice from Richard Stallman.*

   If you are not sure what to do, then please ask Richard Stallman for
advice; if the contributor asks you questions about the meaning and
consequences of the legal papers, and you don't know the answers, you
can forward them to Stallman.

   *Please do not try changing the wording of a template yourself.  If
you think a change is needed, please talk with Richard Stallman, who
will work with a lawyer to decide what to do.*

Copyright Notices
=================

   You should maintain copyright notices in all files of the program.
A copyright notice looks like this:

     Copyright 19XX, 19YY, 19ZZ  COPYRIGHT-HOLDER

   The COPYRIGHT-HOLDER may be the Free Software Foundation, Inc., or
someone else; you should know who is the copyright holder for your
package.

   The list of year numbers should include each year in which you
finished preparing a version which was actually released, and which was
an ancestor of the current version.

   It is important to understand that rule carefully, much as you would
understand a complicated C statement in order to hand-simulate it.

   This list is _not_ a list of years in which versions were released.
It is a list of years in which versions, later released, were
_completed_.  So if you finish a version on Dec 31, 1994 and release it
on Jan 1, 1995, this version requires the inclusion of 1994, but
doesn't require the inclusion of 1995.

   The versions that matter, for purposes of this list, are versions
that were ancestors of the current version.  So if you made a temporary
branch in maintenance, and worked on branches A and B in parallel, then
each branch would have its own list of years, which is based on the
versions released in that branch.  A version in branch A need not be
reflected in the list of years for branch B, and vice versa.

   However, if you copy code from branch A into branch B, the years for
branch A (or at least, for the parts that you copied into branch B) do
need to appear in the list in branch B, because now they are ancestors
of branch B.

   We agree that this rule is complicated.  If we were in charge of
copyright law, we would probably change this (as well as lots more).

Recording Changes
=================

   *Keep records of which portions were written by whom.*

   These records don't need to be as detailed as a change log.  They
don't need to distinguish work done at different times, only different
people.

   They should say which files or functions were written by each person,
and which files or functions were revised by each person.  They don't
need to say what the purpose of the change was.  The Register of
Copyrights doesn't care what the program does.

   For example, this would describe an early version of GAS:

     Dean Elsner   first version of all files except gdb-lines.c and m68k.c.
     Jay Fenlason  entire files gdb-lines.c and m68k.c, most of app.c,
       extensive changes in messages.c, input-file.c, write.c,
       revisions elsewhere.

   Please keep these records in a file named `AUTHORS' in the source
directory for the program itself.

Cleaning Up Changes
*******************

   If someone sends you changes which are ugly and will make the program
harder to understand and maintain in the future, such as a port to
another operating system containing ad hoc conditionals, don't hesitate
to ask person to clean up per changes before you merge them.

   Since the amount of work we do is constant in any case, the more work
we get other people to do, the faster GNU will advance.

   If person will not or can not make the changes clean enough, then say
that you can't afford to merge them.  Invite per to distribute per
changes another way, or to find other people who can make them clean
enough for us to maintain.

   The only reason to do these cleanups yourself is if (1) it is easy
enough that it is less work than telling the author what to clean up,
or (2) users will greatly appreciate the improvement, and you would
almost write it yourself if you had time.

   The GNU Coding Standards are a good thing to send people who have to
clean up C programs (see Contents (standards)).  The Emacs Lisp
manual contains an appendix that gives coding standards for Emacs Lisp
programs; it is good to urge authors to read it (see Tips and Standards (elisp)).

Dealing With Mail
*****************

   Once a program is in use, you will start getting bug reports.  Some
GNU programs have their own special lists for sending bug reports.  For
miscellaneous programs that don't have their own lists, we use a
catch-all list, <bug-gnu-utils@gnu.org>.  Many lists are handled by
smartlist; for those lists, you can send mail to the -request address
to subscribe; otherwise, talk with <gnu@gnu.org> to arrange to be added
to the proper list for your program.  To set up a new list, you should
also talk with <gnu@gnu.org>.

   When you receive bug reports, keep in mind that bug reports are
crucial for your work.  If you don't know about problems, you cannot
fix them.  So always thank the people who send bug reports.

   You don't have an obligation to give more response than that, though.
The main purpose of bug reports is to help you to improve the next
version of the program.  Many of the people who report bugs don't
realize this-they think that the point is for you to help them
individually.  Some will ask to focus on that _instead of_ on making
the program better.  That isn't part of the job you have undertaken, so
you shouldn't feel an obligation to satisfy them.

   For example, people sometimes report a bug in a vague (and therefore
useless) way, and when you ask for more information, they say, "I just
wanted to see if you already knew the solution" (in which case the bug
report is certainly useless).  When this happens, you should explain to
them what bug reports are really for.

   When people ask you to put your time into helping them use the
program, it may seem "helpful" to do what they ask.  But it is much
_less_ helpful than improving the program, which is the maintainer's
real job.  If you spend significant time helping one person, when you
could instead have helped thousands, the world as a whole is worse off.

   So be careful to limit the amount of time you spend giving in to
those requests--don't let them take priority over maintaining the
program.  Spend time helping individual users when you feel like it,
when you feel you have the time available.  But know how to say no to
them, also; if you feel really pressed for time, just "thanks for the
bug report" is enough response.

Recording Old Versions
**********************

   It is very important to keep backup files of all source files of GNU.
You can do this using RCS, CVS or PRCS if you like.  The easiest way to
use RCS or CVS is via the Version Control library in Emacs; see
Concepts of Version Control (emacs).

   Alternatively, you can keep backup files.

Backup Files
============

   Emacs makes a backup file by renaming the old source file to a new
name.  This means that if the file is also pointed to by a distribution
directory, the distribution directory continues to point to the same
version it always did--the right thing.

   We want to keep more than one backup for all GNU sources.  So, if you
are going to edit GNU sources, _make certain_ to put
     (setq version-control t)

into your `.emacs' file, so that Emacs always creates numbered backup
files.

   Using Emacs backup files works as long as people always make changes
with Emacs.  If you change the file in some other way, and use `cp',
`ftp', or `tar' to install it, you will _overwrite_ the old version and
fail to make a backup.  Don't do that!

   If you want to make a change to a source file with something other
than Emacs, you can write the changed file to another name, and use
`C-x C-w' in Emacs to write it under the real name.  This makes the
backup file properly.

   You can use GNU `cp' or `mv' to install changed files if you give
them the `--backup' (or, equivalently, `-b') option; then they make
backup copies the same way that Emacs does.  You should also use the
`--version-control=t' option, or, alternately, first
     export VERSION_CONTROL=t

(or the `csh' equivalent); this makes GNU `cp' and `mv' create numbered
backup files instead of a single backup file with a `~' appended to the
filename.  For installing many changed files, you can use shell
wildcards and also give GNU `cp' or `mv' the `--update' (`-u') option,
which only copies (or moves) files that have been modified more
recently than the existing destination files, and the `--verbose'
(`-v') option, which prints the names of the files that are actually
copied (or moved).

   Before you use `mv' or `cp' in this way, _make sure it is the GNU
version_.  Do `which mv' (in `csh') or `type mv' (in `bash') to verify
you are not getting `/bin/mv' (or likewise for `cp').  Or just type
`cp' or `mv' and look at the usage message.

Deleting Backup Files
=====================

   Always answer no when Emacs offers to delete backup files
automatically.  The way to delete them is by hand, using `M-x dired'.

   When you decide which backup files to delete, it is good to keep one
every couple of weeks or so, going back about 2 months.

   If there is a long gap between versions, because that file did not
change during a long period of time, then keep the version before the
gap even if it is 2 months old.  Pretend it is just 2 weeks older than
the next kept version, so delete it when the next version is >= 6 weeks
old.

   If the changes in a program have been simple, then you don't need to
keep as many backup files.  Just one a month for 2 months is enough.

   If you have made big changes, keep the versions before and after the
big change, until they are old enough.

   If you made several changes the same day, usually the last version
written that day is best to keep.

   It is almost always right to keep the most recent backup version.

Distributions
*************

   It is important to follow the GNU conventions when making GNU
software distributions.

Distribution tar Files
======================

   The tar file for version M.N of program `foo' should be named
`foo-M.N.tar'.  It should unpack into a subdirectory named `foo-M.N'.
Tar files should not unpack into files in the current directory,
because this is inconvenient if the user happens to unpack into a
directory with other files in it.

   Here is how the `Makefile' for Bison creates the tar file.  This
method is good for other programs.

     dist: bison.info
             echo bison-`sed -e '/version_string/!d' \
               -e 's/[^0-9.]*\([0-9.]*\).*/\1/' -e q version.c` > .fname
             -rm -rf `cat .fname`
             mkdir `cat .fname`
             dst=`cat .fname`; for f in $(DISTFILES); do \
                ln $(srcdir)/$$f $$dst/$$f || { echo copying $$f; \
                  cp -p $(srcdir)/$$f $$dst/$$f ; } \
             done
             tar --gzip -chf `cat .fname`.tar.gz `cat .fname`
             -rm -rf `cat .fname` .fname

   Source files that are symbolic links to other file systems cannot be
installed in the temporary directory using `ln', so use `cp' if `ln'
fails.

   Using Automake is a good way to take care of writing the `dist'
target.

Distribution Patches
====================

   If the program is large, it is useful to make a set of diffs for each
release, against the previous important release.

   At the front of the set of diffs, put a short explanation of which
version this is for and which previous version it is relative to.  Also
explain what else people need to do to update the sources properly (for
example, delete or rename certain files before installing the diffs).

   The purpose of having diffs is that they are small.  To keep them
small, exclude files that the user can easily update.  For example,
exclude info files, DVI files, tags tables, output files of Bison or
Flex.  In Emacs diffs, we exclude compiled Lisp files, leaving it up to
the installer to recompile the patched sources.

   When you make the diffs, each version should be in a directory
suitably named--for example, `gcc-2.3.2' and `gcc-2.3.3'.  This way, it
will be very clear from the diffs themselves which version is which.

   If you use GNU `diff' to make the patch, use the options `-rc2P'.
That will put any new files into the output as "entirely different."
Also, the patch's context diff headers should have dates and times in
Universal Time using traditional Unix format, so that patch recipients
can use GNU `patch''s `-Z' option.  For example, you could use the
following Bourne shell command to create the patch:

     LC_ALL=C TZ=UTC0 diff -rc2P gcc-2.3.2 gcc-2.3.3 | \
     gzip -9 >gcc-2.3.2-2.3.3.patch.gz

   If the distribution has subdirectories in it, then the diffs probably
include some files in the subdirectories.  To help users install such
patches reliably, give them precise directions for how to run patch.
For example, say this:

     To apply these patches, cd to the main directory of the program
     and then use `patch -p1'.   `-p1' avoids guesswork in choosing
     which subdirectory to find each file in.

   It's wise to test your patch by applying it to a copy of the old
version, and checking that the result exactly matches the new version.

Distribution on `ftp.gnu.org'
=============================

   Only the latest version of any program needs to be on `ftp.gnu.org'.
Being an archive of old versions is not the function of `ftp.gnu.org'.

   Diffs are another matter.  Since they are much smaller than
distribution files, it is good to keep the diffs around for quite a
while.

Test Releases
=============

   When you release a greatly changed new major version of a program,
you might want to do so as a beta test release.

   Once a program gets to be widely used and people expect it to work
solidly, it is a good idea to do pretest releases before each "real"
release.  This means that you make a tar file, but send it only to a
group of volunteers that you have recruited.  (Use a suitable GNU
mailing list/newsgroup to recruit them.)

   One thing that you should never do is to release a distribution which
is considered a pretest or beta test but which contains the version
number for the planned real release.  Many people will look only at the
version number (in the tar file name, in the directory name that it
unpacks into, or wherever they can find it) to determine whether a tar
file is the latest version.  People might look at the test release in
this way and mistake it for the real release.  Therefore, always change
the number when you make a new tar file.

   If you are about to release version 4.6 but you want to do a pretest
or beta test first, call it 4.5.90.  If you need a second pretest, call
it 4.5.91, and so on.

Using the Proofreaders List
***************************

   If you want help finding errors in documentation, or help improving
the quality of writing, or if you are not a native speaker of English
and want help producing good English documentation, you can use the GNU
proofreaders mailing list: <proofreaders@gnu.org>.

   But be careful when you use the list, because there are over 200
people on it.  If you simply ask everyone on the list to read your work,
there will probably be tremendous duplication of effort by the
proofreaders, and you will probably get the same errors reported 100
times.  This must be avoided.

   Also, the people on the list do not want to get a large amount of
mail from it.  So do not ever ask people on the list to send mail to
the list!

   Here are a few methods that seem reasonable to use:

   * For something small, mail it to the list, and ask people to pick a
     random number from 1 to 20, and read it if the number comes out as
     10.  This way, assuming 50% response, some 5 people will read the
     piece.

   * For a larger work, divide your work into around 20 equal-sized
     parts, tell people where to get it, and ask each person to pick
     randomly which part to read.

     Be sure to specify the random choice procedure; otherwise people
     will probably use a mental procedure that is not really random,
     such as "pick a part near the middle", and you will not get even
     coverage.

     You can either divide up the work physically, into 20 separate
     files, or describe a virtual division, such as by sections (if
     your work has approximately 20 sections).  If you do the latter,
     be sure to be precise about it--for example, do you want the
     material before the first section heading to count as a section,
     or not?

   * For a job needing special skills, send an explanation of it, and
     ask people to send you mail if they volunteer for the job.  When
     you get enough volunteers, send another message to the list saying
     "I have enough volunteers, no more please."