\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 March 12, 2009
+@set lastupdate December 12, 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
entitled to change and redistribute GNU software; you need not pay
attention to this file to get permission. But if you want to maintain a
version for widespread distribution, we suggest you follow these
-guidelines; if you would like to be a GNU maintainer, then it is
+guidelines. If you would like to be a GNU maintainer, then it is
essential to follow these guidelines.
In addition to this document, please read and follow the GNU Coding
Standards (@pxref{Top, , Contents, standards, GNU Coding Standards}).
-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
-efficiently. We prefer a context diff to the @file{maintain.texi} file,
-but if you don't have that file, you can make a context diff for some
-other version of this document, or propose it in any way that makes it
-clear.
+@cindex @code{gnustandards-commit@@gnu.org} mailing list
+If you want to receive diffs for every change to these GNU documents,
+join the mailing list @code{gnustandards-commit@@gnu.org}, via the web
+interface at
+@url{http://lists.gnu.org/mailman/listinfo/gnustandards-commit}.
+Archives are also available there.
+@cindex @code{maintainers@@gnu.org} email address
+Please send corrections or suggestions for this document to
+@email{bug-standards@@gnu.org}. If you make a suggestion, please
+include a suggested new wording for it, to help us consider the
+suggestion efficiently. We prefer a context diff to the
+@file{maintain.texi} file, but if you don't have that file, you can
+make a context diff for some 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
+list of a few experienced GNU contributors 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
@item
In the @samp{My Account Conf} page on @code{savannah}, upload the GPG
-key you will use to sign your packages. You can create a key with the
-command @code{gpg --gen-key}. (For full information about GPG, see
-@url{http://www.gnu.org/software/gpg}).
+key you will use to sign your packages.
+
+You can create a key with the command @code{gpg --gen-key}. It is
+good to also send your key to the GPG public key server: @code{gpg
+--keyserver keys.gnupg.net --send-keys @var{keyid}}, where @var{keyid}
+is the eight hex digits reported by @code{gpg --list-public-keys} on
+the @code{pub} line before the date. For full information about GPG,
+see @url{http://www.gnu.org/software/gpg})
@item
Compose a message with the following items in some @var{msgfile}.
@enumerate
@item
-The file to be distributed (for example, @file{foo.tar.gz}).
+The file to be distributed; for example, @file{foo.tar.gz}.
@item
-Detached GPG binary signature for (1), made using @samp{gpg -b}
-(for example, @file{foo.tar.gz.sig}).
+Detached GPG binary signature file for (1); for example,
+@file{foo.tar.gz.sig}. Make this with @samp{gpg -b foo.tar.gz}.
+
@item
-A clearsigned @dfn{directive file}, made using @samp{gpg --clearsign}
-(for example, @file{foo.tar.gz.directive.asc}).
+A clearsigned @dfn{directive file}; for example,
+@file{foo.tar.gz.directive.asc}. Make this by preparing the plain
+text file @file{foo.tar.gz.directive} and then run @samp{gpg
+--clearsign foo.tar.gz.directive}. @xref{FTP Upload Directive File -
+v1.1}, for the contents of the directive file.
@end enumerate
The names of the files are important. The signature file must have the
package. You also receive a message when your upload has been successfully
processed.
-One relatively easy way to create and transfer the necessary files is
-to use the @code{gnupload} script, which is available from the
+One automated way to create and transfer the necessary files is to use
+the @code{gnupload} script, which is available from the
@file{build-aux/} directory of the @code{gnulib} project at
@url{http://savannah.gnu.org/projects/gnulib}. @code{gnupload} can
also remove uploaded files. Run @code{gnupload --help} for a
@code{gnupload} uses the @code{ncftpput} program to do the actual
transfers; if you don't happen to have the @code{ncftp} package
installed, the @code{ncftpput-ftp} script in the @file{build-aux/}
-directory of @code{gnulib}. serves as a replacement which uses plain
+directory of @code{gnulib} serves as a replacement which uses plain
command line @code{ftp}.
-If you have difficulties processing an upload, email
+If you have difficulties with an upload, email
@email{ftp-upload@@gnu.org}.
on information rather than flashy eye candy, and to keep the site
simple and uniform.
+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
+databases (including mail logs and bug tracking) are an exception; set
+them up on whatever site is convenient for you, and make the pages on
+@code{www.gnu.org} link to that site.
+
+@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. You can keep your source files there too, but if you want
-to use @code{savannah.gnu.org} only for the web pages, that's ok;
-simply register a ``web-only'' project.
+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 CVS if you can.
+is more work for them, so please use Savannah 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
-databases (including mail logs and bug tracking) are an exception; set
-them up on whatever site is convenient for you, and make the pages on
-@code{www.gnu.org} link to that site.
+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}.
-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 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 / gnulib.git / blobdiff