\input texinfo.tex @c -*-texinfo-*-
@c %**start of header
@setfilename maintain.info
-@settitle Information For Maintainers of GNU Software
+@settitle Information for Maintainers of GNU Software
@c For double-sided printing, uncomment:
@c @setchapternewpage odd
@c This date is automagically updated when you save this file:
-@set lastupdate January 1, 2009
+@set lastupdate July 24, 2009
@c %**end of header
@dircategory GNU organization
@c Put everything in one index (arbitrarily chosen to be the concept index).
@syncodeindex fn cp
-@syncodeindex ky cp
@syncodeindex pg cp
-@syncodeindex vr cp
@copying
Information for maintainers of GNU software, last updated @value{lastupdate}.
@end copying
@titlepage
-@title Information For Maintainers of GNU Software
+@title Information for Maintainers of GNU Software
@author Richard Stallman
@author last updated @value{lastupdate}
@page
In addition to this document, please read and follow the GNU Coding
Standards (@pxref{Top, , Contents, standards, GNU Coding Standards}).
+@cindex @code{maintainers@@gnu.org} email address
Please send corrections or suggestions for this document to
@email{maintainers@@gnu.org}. If you make a suggestion, please include
a suggested new wording for it, to help us consider the suggestion
other version of this document, or propose it in any way that makes it
clear.
+@cindex @code{mentors@@gnu.org} mailing list
If you have general questions or encounter a situation where it isn't
clear what to do, you can ask @email{mentors@@gnu.org}, which is a
list of a few other GNU contributor who have offered to answer
questions for new maintainers.
+The directory @file{/gd/gnuorg} mentioned throughout this document is
+found on the GNU file server, currently @code{fencepost.gnu.org}; if
+you are the maintainer of a GNU package, you should have an account
+there. See @url{http://www.gnu.org/software/README.accounts.html} if
+you don't have one. (You can also ask for accounts for people who
+help you a large amount in working on the package.)
+
+If on occasion you find that any GNU computer systems
+(@code{fencepost.gnu.org}, @code{ftp.gnu.org},
+@code{savannah.gnu.org}, or others) seem to be down, you can check the
+current status at @url{http://identi.ca/group/fsfstatus}. Most likely
+the problem, if it is at the FSF end, is already being worked on.
+
+@cindex Piercy, Marge
This document uses the gender-neutral third-person pronouns ``person'',
``per'', ``pers'' and ``perself'' which were promoted, and perhaps
invented, by Marge Piercy in @cite{Woman on the Edge of Time}. They are
per new program under the GNU GPL, to let the public benefit from per
work, and to enable per to feel person has done the right thing.''
-The directory @file{/gd/gnuorg} is found on the GNU file server,
-currently @code{fencepost.gnu.org}; if you are the maintainer of a GNU
-package, you should have an account there. See
-@url{http://www.gnu.org/software/README.accounts.html} if you don't
-have one. (You can also ask for accounts for people who help you a
-large amount in working on the package.)
-
This release of the GNU Maintenance Instructions was last updated
@value{lastupdate}.
a person is capable of doing the job will carry a lot of weight.
As your final act as maintainer, it would be helpful to set up the
-package under @code{savannah.gnu.org} (@pxref{Old Versions}). This will
-make it much easier for the new maintainer to pick up where you left off
-and will ensure that the source tree is not misplaced if it takes us a
-while to find a new maintainer.
+package under @code{savannah.gnu.org} if it is not there already
+(@pxref{Old Versions}). This will make it much easier for the new
+maintainer to pick up where you left off and will ensure that the
+source tree is not misplaced if it takes us a while to find a new
+maintainer.
@node Recruiting Developers
papers. In any case, you should wait for the confirmation from the
FSF that the signed papers have been received and accepted before
integrating the new contributor's material, as usual.
-
+
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 helps you reach agreement. We
that it is in the public domain.
Even image files and sound files should contain copyright notices and
-license notices, if they can. Some formats do not have room for textual
-annotations; for these files, state the copyright and copying
-permissions in a README file in the same directory.
+license notices, if their format permits. Some formats do not have
+room for textual annotations; for these files, state the copyright and
+copying permissions in a @file{README} file in the same directory.
Change log files should have a copyright notice and license notice at
the end, since new material is added at the beginning but the end
@subsection License Notices for Other Files
Small supporting files, short manuals (under 300 lines long) and rough
-documentation (README files, INSTALL files, etc) can use a simple
-all-permissive license like this one:
+documentation (@file{README} files, @file{INSTALL} files, etc.)@: can
+use a simple all-permissive license like this one:
@smallexample
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
-notice and this notice are preserved.
+notice and this notice are preserved. This file is offered as-is,
+without any warranty.
@end smallexample
+Older versions of this license did not have the second sentence with
+the express warranty disclaimer. There is no urgent need to update
+existing files, but new files should use the new text.
+
If your package distributes Autoconf macros that are intended to be
used (hence distributed) by third-party packages under possibly
incompatible licenses, you may also use the above all-permissive
change log that you would not want to hand over to another maintainer
some day.
+@cindex @code{savannah-hackers@@gnu.org}
The GNU Project provides a server that GNU software packages can use
for source control and other package needs: @code{savannah.gnu.org}.
You don't have to use this repository, but if you plan to allow public
people to be able to find various GNU packages in a central place.
Savannah is managed by @email{savannah-hackers@@gnu.org}.
-All GNU maintainers are encouraged to take advantage of Savannah, as
-sharing such a central point can serve to foster a sense of community
-among GNU developers and help in keeping up with project management.
+All GNU maintainers are strongly encouraged to take advantage of
+Savannah, as sharing such a central point can serve to foster a sense
+of community among GNU developers and help in keeping up with project
+management.
+
+@cindex @code{savannah-announce@@gnu.org} mailing list
+If you do use Savannah, it is a good idea to subscribe to the
+@email{savannah-announce@@gnu.org} mailing list
+(@url{http://lists.gnu.org/mailman/listinfo/savannah-announce}). This
+is a very low-volume list to keep Savannah users informed of system
+upgrades, problems, and the like.
@node Distributions
@url{http://www.gnu.org/software/gpg}).
@item
-Send a message, preferably GPG-signed, to @email{ftp-upload@@gnu.org}
-with the following:
+Compose a message with the following items in some @var{msgfile}.
+Then GPG-sign it by running @code{gpg --clearsign @var{msgfile}}, and
+finally email the resulting @file{@var{msgfile}.asc}), to
+@email{ftp-upload@@gnu.org}.
@enumerate
@item
the proper GPG keys as authorized to upload files for the
corresponding packages.
+The upload system will email receipts to the given email addresses
+when an upload is made, either successfully or unsuccessfully.
+
@node Automated Upload Procedure
@subsection Automated Upload Procedure
@code{comment} directive remains optional.
If you use more than one directive, the directives are executed in the
-sequence they are specified in.
+sequence they are specified in. If a directive results in an error,
+further execution of the upload is aborted.
+
+Removing a symbolic link (with @code{rmsymlink}) which does not exist
+results in an error. However, attempting to create a symbolic link
+that already exists (with @code{symlink}) is not an error. In this
+case @code{symlink} behaves like the command @command{ln -s -f}: any
+existing symlink is removed before creating the link. (But an
+existing regular file or directory is not removed.)
Here are a few examples. The first removes a symlink:
strongly recommend using the (moderated) general GNU announcements
list, @email{info-gnu@@gnu.org}. Doing so makes it easier for users
and developers to find the latest GNU releases. On the other hand,
-please do not announce test releases on @code{info-gnu} unless it's an
-unusual situation.
+please do not announce test releases on @code{info-gnu} unless it's a
+highly unusual situation.
@cindex @url{http://planet.gnu.org}
@cindex Savannah, news area
Please also post release announcements in the news section of your
Savannah project site. It is fine to also write news entries for test
releases and any other newsworthy events. The news feeds from all GNU
-projects at savannah are aggregated at @url{http://planet.gnu.org}.
-(You can also post items directly, or arrange for feeds from other
-locations; see contact information on the GNU Planet web page.)
+projects at savannah are aggregated at @url{http://planet.gnu.org}
+(GNU Planet). You can also post items directly, or arrange for feeds
+from other locations; see contact information on the GNU Planet web
+page.
@cindex announcement mailing list, project-specific
You can maintain your own mailing list (typically
@email{info-@var{program}@@gnu.org}) for announcements as well if you
-like. For your own list, of course you can decide as you see fit what
+like. For your own list, of course you decide as you see fit what
events are worth announcing. (@xref{Mail}, for more suggestions on
handling mail for your package.)
+@cindex contents of announcements
+When writing an announcement, please include the following:
+
+@itemize @bullet
+@item
+A very brief description (a few sentences at most) of the general
+purpose of your package.
+
+@item
+Your package's web page (normally
+@indicateurl{http://www.gnu.org/software/@var{package}/}).
+
+@item
+Your package's download location (normally
+@indicateurl{http://ftp.gnu.org/gnu/@var{package}/}). It is also
+useful to mention the FTP mirror list at
+@url{http://www.gnu.org/order/ftp.html}, and that
+@url{http://ftpmirror.gnu.org/@var{package/}} will automatically
+redirect to a nearby mirror.
+
+@item
+The NEWS (@pxref{NEWS File,,, standards, GNU Coding Standards}) for
+the present release.
+@end itemize
+
@node Web Pages
@chapter Web Pages
on information rather than flashy eye candy, and to keep the site
simple and uniform.
-The simplest way to maintain the web pages for your project is to
-register the project on @code{savannah.gnu.org}. Then you can edit
-the pages using CVS. You can keep the source files there too, but if
-you want to use @code{savannah.gnu.org} only for the web pages, simply
-register a ``web-only'' project.
-
-If you don't want to use that method, please talk with
-@email{webmasters@@gnu.org} about other possible methods. For
-instance, you can mail them pages to install, if necessary. But that
-is more work for them, so please use CVS if you can.
-
Some GNU packages have just simple web pages, but the more information
you provide, the better. So please write as much as you usefully can,
and put all of it on @code{www.gnu.org}. However, pages that access
them up on whatever site is convenient for you, and make the pages on
@code{www.gnu.org} link to that site.
-Historically, web pages for GNU packages did not include GIF images,
-because of patent problems (@pxref{Ethical and Philosophical
-Consideration}). Although the GIF patents expired in 2006, using GIF
-images is still not recommended, as the PNG and JPEG formats are
-generally superior. See @url{http://www.gnu.org/philosophy/gif.html}.
+@menu
+* Hosting for Web Pages::
+* Freedom for Web Pages::
+* Manuals on Web Pages::
+* CVS Keywords in Web Pages::
+@end menu
+
+@node Hosting for Web Pages
+@section Hosting for Web Pages
+
+The best way to maintain the web pages for your project is to register
+the project on @code{savannah.gnu.org}. Then you can edit the pages
+using CVS, using the separate ``web repository'' available on
+Savannah, which corresponds to
+@indicateurl{http://www.gnu.org/software/@var{package}/}. You can
+keep your source files there too (using any of a variety of version
+control systems), but you can use @code{savannah.gnu.org} only for
+your gnu.org web pages if you wish; simply register a ``web-only''
+project.
+
+If you don't want to use that method, please talk with
+@email{webmasters@@gnu.org} about other possible methods. For
+instance, you can mail them pages to install, if necessary. But that
+is more work for them, so please use Savannah if you can.
+
+If you use Savannah, you can use a special @file{.symlinks} file in
+order to create symbolic links, which are not supported in CVS. For
+details, see
+@url{http://www.gnu.org/server/standards/README.webmastering.html#symlinks}.
+
+
+@node Freedom for Web Pages
+@section Freedom for Web Pages
If you use a site other than @code{www.gnu.org}, please make sure that
the site runs on free software alone. (It is ok if the site uses
public might perceive as connected with it and reflecting the position
of its developers, unless it follows that criterion.
+Historically, web pages for GNU packages did not include GIF images,
+because of patent problems (@pxref{Ethical and Philosophical
+Consideration}). Although the GIF patents expired in 2006, using GIF
+images is still not recommended, as the PNG and JPEG formats are
+generally superior. See @url{http://www.gnu.org/philosophy/gif.html}.
+
+
+@node Manuals on Web Pages
+@section Manuals on Web Pages
+
The web pages for the package should include its manuals, in HTML,
DVI, Info, PostScript, PDF, plain ASCII, and Texinfo format (source).
-(All of these can be generated automatically from the Texinfo source
-using Makeinfo and other programs.) When there is only one manual,
-put it in a subdirectory called @file{manual}; the file
-@file{manual/index.html} should have a link to the manual in each of
-its forms.
+All of these can be generated automatically from the Texinfo source
+using Makeinfo and other programs.
+
+When there is only one manual, put it in a subdirectory called
+@file{manual}; the file @file{manual/index.html} should have a link to
+the manual in each of its forms.
If the package has more than one manual, put each one in a
subdirectory of @file{manual}, set up @file{index.html} in each
See the section below for details on a script to make the job of
creating all these different formats and index pages easier.
-We would like to include links to all these manuals in the page
-@url{http://www.gnu.org/manual}. Just send mail to
-@code{webmasters@@gnu.org} telling them the name of your package and
-asking them to edit @url{http://www.gnu.org/manual}, and they will do
-so based on the contents of your @file{manual} directory.
+We would like to include links to all GNU manuals on the page
+@url{http://www.gnu.org/manual}, so if yours isn't listed, please send
+mail to @code{webmasters@@gnu.org} telling them the name of your
+package and asking them to edit @url{http://www.gnu.org/manual}, and
+they will do so based on the contents of your @file{manual} directory.
@menu
* Invoking gendocs.sh::
-* CVS Keywords in Web Pages::
@end menu
@node Invoking gendocs.sh
-@section Invoking @command{gendocs.sh}
+@subsection Invoking @command{gendocs.sh}
@pindex gendocs.sh
@cindex generating documentation output
@node CVS Keywords in Web Pages
@section CVS Keywords in Web Pages
-@cindex cvs keywords in web pages
-@cindex rcs keywords in web pages
+@cindex CVS keywords in web pages
+@cindex RCS keywords in web pages
@cindex $ keywords in web pages
-@cindex web pages, and cvs keywords
+@cindex web pages, and CVS keywords
Since @code{www.gnu.org} works through CVS, CVS keywords in your
manual, such as @code{@w{$}Log$}, need special treatment (even if you
repository for your package, and, even more so, using
@code{ftp.gnu.org} as the standard distribution site. Doing so makes
it easier for developers and users to find the latest GNU releases.
+@xref{Old Versions}, for more information about Savannah.
However, it is ok to use other machines if you wish. If you use a
company's machine to hold the repository for your program, or as its
projects / pspp / blobdiff