X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fmaintain.texi;h=c04722c8a8f1fe3bf7efd3f6a3938d3e71ed1226;hb=1a4fd05ac8b426112d48d66a240356a4b5fd59cc;hp=fc7a006a515170774d4d3d91deb8015bfc9f3242;hpb=5337983bcb95b90198e06c767ec1fbcc487003d0;p=gnulib.git diff --git a/doc/maintain.texi b/doc/maintain.texi index fc7a006a5..c04722c8a 100644 --- a/doc/maintain.texi +++ b/doc/maintain.texi @@ -5,7 +5,7 @@ @c For double-sided printing, uncomment: @c @setchapternewpage odd @c This date is automagically updated when you save this file: -@set lastupdate March 21, 2008 +@set lastupdate February 1, 2009 @c %**end of header @dircategory GNU organization @@ -25,12 +25,12 @@ Information for maintainers of GNU software, last updated @value{lastupdate}. Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, -2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software +2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or +under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled @@ -88,6 +88,9 @@ version for widespread distribution, we suggest you follow these 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 @@ -96,6 +99,11 @@ 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. +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. + 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 @@ -106,10 +114,10 @@ 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. Contact -@email{accounts@@gnu.org} 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.) +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}. @@ -169,6 +177,11 @@ out the maintainer's functions together. If you would like to propose some of your developers as co-maintainers, please contact @email{maintainers@@gnu.org}. +We're happy to acknowledge all major contributors to GNU packages on +the @url{http://www.gnu.org/people/people.html} web page. Please send +an entry for yourself to @email{webmasters@@gnu.org}, and feel free to +suggest it to other significant developers on your package. + @node Legal Matters @chapter Legal Matters @@ -606,11 +619,12 @@ Every nontrivial file needs a license notice as well as the copyright notice. (Without a license notice giving permission to copy and change the file, the file is non-free.) -The package itself should contain a full copy of GPL (conventionally -in a file named @file{COPYING}) and the GNU Free Documentation License -(included within your documentation). If the package contains any -files distributed under the Lesser GPL, it should contain a full copy -of that as well (conventionally in a file named +The package itself should contain a full copy of GPL in plain text +(conventionally in a file named @file{COPYING}) and the GNU Free +Documentation License (included within your documentation, so there is +no need for a separate plain text version). If the package contains +any files distributed under the Lesser GPL, it should contain a full +copy of its plain text version also (conventionally in a file named @file{COPYING.LESSER}). If you have questions about license issues for your GNU package, @@ -700,7 +714,7 @@ features of the GFDL. @smallexample Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.2 or +under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being ``GNU General Public License'', with the Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts @@ -720,17 +734,18 @@ name. Please adjust the list of invariant sections as appropriate for your manual. If there are none, then say ``with no Invariant Sections''. If your manual is not published by the FSF, and under 400 pages, you -can omit both cover texts and the inclusion of the GPL. +can omit both cover texts. @xref{GNU Sample Texts,,,texinfo,Texinfo}, for a full example in a Texinfo manual, and see @url{http://www.gnu.org/licenses/fdl-howto.html} for more advice about how to use the GNU FDL. -If the manual is over 400 pages, or if the FSF thinks it might be a good -choice for publishing on paper, then please include our standard -invariant section which explains the importance of free documentation. -Write to @email{assign@@gnu.org} to get a copy of this section. +If the manual is over 400 pages, or if the FSF thinks it might be a +good choice for publishing on paper, then please include the GNU GPL, +as in the notice above. Please also include our standard invariant +section which explains the importance of free documentation. Write to +@email{assign@@gnu.org} to get a copy of this section. When you distribute several manuals together in one software package, their on-line forms can share a single copy of the GFDL (see @@ -831,8 +846,8 @@ important one, important enough to be worth the work of cleaning it up. The GNU Coding Standards are a good thing to send people when you ask them to clean up changes (@pxref{Top, , Contents, standards, GNU Coding 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 (@pxref{Tips, , Tips and Standards, elisp, The GNU Emacs Lisp +coding standards for Emacs Lisp programs; it is good to urge Lisp authors to +read it (@pxref{Tips, , Tips and Conventions, elisp, The GNU Emacs Lisp Reference Manual}). @@ -903,13 +918,26 @@ used for all GNU programs that don't have their own specific lists. But nowadays we want to give each program its own bug-reporting list and move away from using @email{bug-gnu-utils}. +If you wish, you can also have mailing lists such as +@samp{info-@var{program}} for announcements (@pxref{Announcements}), +@samp{help-@var{program}} for general help and discussion (see below), +or any others you find useful. + +By far the easiest way to create mailing lists is through +@code{savannah.gnu.org}. Once you register your program, you can do +this yourself through the `Mailing Lists' menu, without needing +intervention by anyone else. Furthermore, lists created through +Savannah will have a reasonable default configuration for antispam +purposes (see below). + If you are the maintainer of a GNU package, you should have an account -on the GNU servers; contact @email{accounts@@gnu.org} 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.) With this account, you can edit -@file{/com/mailer/aliases} to create a new unmanaged list or add -yourself to an existing unmanaged list. A comment near the beginning of -that file explains how to create a Mailman-managed mailing list. +on the GNU servers; contact +@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.) With this account, you can +edit @file{/com/mailer/aliases} to create a new unmanaged list or add +yourself to an existing unmanaged list. A comment near the beginning +of that file explains how to create a Mailman-managed mailing list. But if you don't want to learn how to do those things, you can alternatively ask @email{alias-file@@gnu.org} to add you to the @@ -1181,7 +1209,7 @@ before they are made publicly available. @node Automated Upload Registration @subsection Automated Upload Registration -@cindex registration +@cindex registration for uploads @cindex uploads, registration for Here is how to register your information so you can perform uploads @@ -1202,8 +1230,10 @@ command @code{gpg --gen-key}. (For full information about GPG, see @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 @@ -1228,15 +1258,18 @@ The administrators will acknowledge your message when they have added 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 @cindex uploads -Once you have registered your information as described in the -previous section, you will be able to do unattended ftp uploads using -the following procedure. +Once you have registered your information as described in the previous +section, you will be able to do ftp uploads for yourself using the +following procedure. For each upload destined for @code{ftp.gnu.org} or @code{alpha.gnu.org}, three files (a @dfn{triplet}) need to be @@ -1263,9 +1296,9 @@ extension. If you do not follow this naming convention, the upload @emph{will not be processed}. Since v1.1 of the upload script, it is also possible to upload a -@dfn{directive file} on its own to perform certain operations on -uploaded files. @xref{FTP Upload Directive File - v1.1}, for more -information. +clearsigned directive file on its own (no accompanying @file{.sig} or +any other file) to perform certain operations on the server. +@xref{FTP Upload Directive File - v1.1}, for more information. Upload the file(s) via anonymous ftp to @code{ftp-upload.gnu.org}. If the upload is destined for @code{ftp.gnu.org}, place the file(s) in @@ -1284,6 +1317,19 @@ 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 +@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 +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 +command line @code{ftp}. + If you have difficulties processing an upload, email @email{ftp-upload@@gnu.org}. @@ -1337,10 +1383,18 @@ When uploaded by itself, the directive file must contain one or more of the directives @code{symlink}, @code{rmsymlink} or @code{archive}, in addition to the obligatory @code{directory} and @code{version} directives. A @code{filename} directive is not allowed, and a -@code{comment} directive is optional. +@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: @@ -1428,16 +1482,32 @@ your package (in the example above, that is @code{bar}). @node Announcements @section Announcing Releases +@cindex announcements +@cindex @code{info-gnu} mailing list When you have a new release, please make an announcement. For official new releases, including those made just to fix bugs, we -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. - -You can maintain your own mailing list for announcements as well if -you like. For your own list, you can decide as you see fit what -events are worth announcing. +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. + +@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.) + +@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 +events are worth announcing. (@xref{Mail}, for more suggestions on +handling mail for your package.) @node Web Pages @@ -1446,9 +1516,10 @@ events are worth announcing. Please write web pages about your package for installation on @code{www.gnu.org}. They should follow our usual standards for web -pages (see @url{http://www.gnu.org/server}); we chose them in order to -support a wide variety of browsers, to focus on information rather -than flashy eye candy, and to keep the site simple and uniform. +pages (see @url{http://www.gnu.org/server/fsf-html-style-sheet.html}). +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. 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 @@ -1525,32 +1596,36 @@ Texinfo documentation output for your web pages section above. It has a companion template file, used as the basis for the HTML index pages. Both are available from the Texinfo CVS sources: -@format + +@smallformat @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh} @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template} -@end format +@end smallformat -There is also a ``minimalistic'' template version, available from: +There is also a minimalistic template, available from: -@format +@smallformat @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template_min} -@end format +@end smallformat Invoke the script like this, in the directory containing the Texinfo source: -@example -gendocs.sh @var{yourmanual} "GNU @var{yourmanual} manual" -@end example -@noindent where @var{yourmanual} is the short name for your package. -The script processes the file @file{@var{yourmanual}.texinfo} (or -@file{.texi} or @file{.txi}). For example: +@smallexample +gendocs.sh --email @var{yourbuglist} @var{yourmanual} "GNU @var{yourmanual} manual" +@end smallexample -@example +@noindent where @var{yourmanual} is the short name for your package +and @var{yourbuglist} is the email address for bug reports (typically +@code{bug-@var{package}@@gnu.org}). The script processes the file +@file{@var{yourmanual}.texinfo} (or @file{.texi} or @file{.txi}). For +example: + +@smallexample cd .../emacs/man # download gendocs.sh and gendocs_template -gendocs.sh emacs "GNU Emacs manual" -@end example +gendocs.sh --email bug-gnu-emacs@@gnu.org emacs "GNU Emacs manual" +@end smallexample @command{gendocs.sh} creates a subdirectory @file{manual/} containing the manual generated in all the standard output formats: Info, HTML, @@ -1573,20 +1648,21 @@ times with different arguments, specifying a different output directory with @option{-o} each time, and moving all the output to your web page. Then write (by hand) an overall index.html with links to them all. For example: -@example + +@smallexample cd .../texinfo/doc -gendocs.sh -o texinfo texinfo "GNU Texinfo manual" -gendocs.sh -o info info "GNU Info manual" -gendocs.sh -o info-stnd info-stnd "GNU info-stnd manual" -@end example +gendocs.sh --email bug-texinfo@@gnu.org -o texinfo texinfo "GNU Texinfo manual" +gendocs.sh --email bug-texinfo@@gnu.org -o info info "GNU Info manual" +gendocs.sh --email bug-texinfo@@gnu.org -o info-stnd info-stnd "GNU info-stnd manual" +@end smallexample By default, the script uses @command{makeinfo} for generating @acronym{HTML} output. If you prefer to use @command{texi2html}, use the @option{--texi2html} command line option, e.g.: -@example +@smallexample gendocs --texi2html -o texinfo texinfo "GNU Texinfo manual" -@end example +@end smallexample The template files will automatically produce entries for additional HTML output generated by @command{texi2html} (i.e., split by sections @@ -1597,6 +1673,9 @@ You can set the environment variables @env{MAKEINFO}, @env{TEXI2DVI}, executed, and @env{GENDOCS_TEMPLATE_DIR} to control where the @file{gendocs_template} file is found. +As usual, run @samp{gendocs.sh --help} for a description of all the +options, environment variables, and more information. + Please email bug reports, enhancement requests, or other correspondence to @email{bug-texinfo@@gnu.org}. @@ -1717,7 +1796,7 @@ different movements which differ in their basic philosophy. The Free Software Movement is idealistic, and raises issues of freedom, ethics, principle and what makes for a good society. The Open Source Movement, founded in 1998, studiously avoids such questions. For more explanation, -see @url{http://www.gnu.org/philosophy/free-software-for-freedom.html}. +see @url{http://www.gnu.org/philosophy/open-source-misses-the-point.html}. The GNU Project is aligned with the Free Software Movement. This doesn't mean that all GNU contributors and maintainers have to agree; @@ -1814,10 +1893,13 @@ on www.gnu.org for more information on how to contribute. @cindex Free Software Directory @cindex Directory, Free Software -The Free Software Directory aims to be a complete list of free software -packages, within certain criteria. Every GNU package should be listed -there, so please contact @email{bug-directory@@gnu.org} to ask for -information on how to write an entry for your package. +The Free Software Directory aims to be a complete list of free +software packages, within certain criteria. Every GNU package should +be listed there, so please see +@url{http://www.gnu.org/help/directory.html#adding-entries} for +information on how to write an entry for your package. Contact +@email{bug-directory@@gnu.org} with any questions or suggestions for +the Free Software Directory. @node Using the Proofreaders List @@ -1897,5 +1979,5 @@ time-stamp-start: "@set lastupdate " time-stamp-start: "@set lastupdate " time-stamp-end: "$" time-stamp-format: "%:b %:d, %:y" -compile-command: "make just-maintain" +compile-command: "make -C work.m" End: