X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fmaintain.texi;h=d84fabaf143c56330ebba43b96f620db864a5c55;hb=54b5ce0e1a4f6a4af37f970e45e6e173e5b0a1c6;hp=013785d480bdff30fd70bf658f56632bb4290e01;hpb=567f85cfcdb0a63cf96730d0858581b013765d59;p=gnulib.git diff --git a/doc/maintain.texi b/doc/maintain.texi index 013785d48..d84fabaf1 100644 --- a/doc/maintain.texi +++ b/doc/maintain.texi @@ -1,11 +1,11 @@ \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 May 26, 2009 +@set lastupdate December 12, 2009 @c %**end of header @dircategory GNU organization @@ -17,9 +17,7 @@ @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}. @@ -39,7 +37,7 @@ Texts. A copy of the license is included in the section entitled @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 @@ -85,25 +83,48 @@ maintainer of a GNU program on behalf of the GNU Project. Everyone is 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 @@ -112,13 +133,6 @@ they apply equally to males and females. For example, ``Person placed 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}. @@ -141,10 +155,11 @@ maintainer needs the GNU Project's confirmation, but your judgment that 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 @@ -1011,6 +1026,7 @@ publicly accessible, be careful not to put anything in the repository or 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 @@ -1018,9 +1034,17 @@ read-only access to your development sources, it is convenient for 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 @@ -1230,9 +1254,14 @@ maintain the web pages at @url{www.gnu.org} for your project @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}. @@ -1282,15 +1311,19 @@ uploaded via ftp to the host @code{ftp-upload.gnu.org}. @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 @@ -1322,8 +1355,8 @@ are sent a message if there are any problems processing an upload for your 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 @@ -1332,10 +1365,10 @@ description and examples. @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}. @@ -1552,29 +1585,46 @@ The overall goals are to support a wide variety of browsers, to focus 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 @@ -1589,13 +1639,24 @@ Please don't link to a site that is about your package, which the 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 @@ -1605,20 +1666,19 @@ subdirectory to link to that manual in all its forms, and make 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 @@ -1895,6 +1955,7 @@ We recommend using @code{savannah.gnu.org} for the source code 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