\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 July 6, 2008
+@set lastupdate July 5, 2010
@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}.
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, 2010 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
@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
@menu
* Preface::
+* Getting Help::
+* Getting a GNU Account::
* Stepping Down::
* Recruiting Developers::
* Legal Matters::
This file contains guidelines and advice for someone who is the
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
-essential to follow these guidelines.
+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 are or would like to be a GNU maintainer, then it
+is essential to follow these guidelines.
-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.
+In addition to this document, please read and follow the GNU Coding
+Standards (@pxref{Top, , Contents, standards, GNU Coding Standards}).
+@cindex @code{bug-standards@@gnu.org} email address
+@cindex Savannah repository for gnustandards
+@cindex gnustandards project repository
+Please send corrections or suggestions for this document to
+@email{bug-standards@@gnu.org}. If you make a suggestion, please
+include suggested new wording if you can. We prefer a context diff to
+the Texinfo source, but if that's difficult for you, you can make a
+diff for some other version of this document, or propose it in any way
+that makes it clear. The source repository for this document can be
+found at @url{http://savannah.gnu.org/projects/gnustandards}.
+
+@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}, for
+instance via the web interface at
+@url{http://lists.gnu.org/mailman/listinfo/gnustandards-commit}.
+Archives are also available there.
+
+@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. 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.)
-
-This release of the GNU Maintenance Instructions was last updated
+This release of the GNU Maintainer Information was last updated
@value{lastupdate}.
+@node Getting Help
+@chapter Getting Help
+@cindex help, getting
+
+@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 experienced GNU contributors who have offered to answer
+questions for new maintainers.
+
+@cindex advisory committee
+The GNU Advisory Committee helps to coordinate activities in the GNU
+project on behalf of RMS. If you have any organizational questions or
+concerns you can contact the committee at
+@email{gnu-advisory@@gnu.org}. The committee holds a regular monthly
+meeting to discuss any issues that have been raised. The minutes of
+the meeting are sent to the @code{gnu-prog} list, and can also be
+found, along with additional information, in
+@file{/gd/gnuorg/advisory}.
+
+
+
+@node Getting a GNU Account
+@chapter Getting a GNU Account
+@cindex shell account, on fencepost
+@cindex @code{fencepost.gnu.org} GNU machine
+
+@c We want to repeat this text later, so define a macro.
+@macro gdgnuorgtext
+The directory @file{/gd/gnuorg} mentioned throughout this document is
+available on the general GNU server, currently
+@code{fencepost.gnu.org}. If you are the maintainer of a GNU package,
+you should have an account there. If you don't have one already,
+@url{http://www.gnu.org/software/README.accounts.html}. You can also
+ask for accounts for people who significantly help you in working on
+the package.
+@end macro
+
+@gdgnuorgtext{}
+
+@cindex down, when GNU machines are
+@cindex outage, of GNU machines
+@cindex @url{http://identi.ca/group/fsfstatus}
+If you find that any GNU computer systems (@code{fencepost.gnu.org},
+@code{ftp.gnu.org}, @code{www.gnu.org}, @code{savannah.gnu.org},
+@dots{}) seem to be down, you can check the current status at
+@url{http://identi.ca/group/fsfstatus}. Most likely the problem, if
+it can be alleviated at the FSF end, is already being worked on.
+
+
@node Stepping Down
@chapter Stepping Down
+@cindex stepping down as maintainer
+@cindex resigning as maintainer
With good fortune, you will continue maintaining your package for many
decades. But sometimes for various reasons maintainers decide to step
We need to know that the package no longer has a maintainer, so we can
look for and appoint a new maintainer.
+@cindex @email{maintainers@@gnu.org}
If you have an idea for who should take over, please tell
@email{maintainers@@gnu.org} your suggestion. The appointment of a new
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
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
@cindex @file{/gd/gnuorg} directory
@c This paragraph intentionally duplicates information given
@c near the beginning of the file--to make sure people don't miss it.
-The directory @file{/gd/gnuorg} is found on the GNU machines,
-currently @code{fencepost.gnu.org}; if you are the maintainer of a GNU
-package, you should have an account on them. 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.)
+@gdgnuorgtext{}
In order for the contributor to know person should sign papers, you need
to ask per for the necessary papers. If you don't know per well, and you
in the public domain, so that we can install it in @var{program}?
@end quotation
-If the contributor wants more information, you can send per
+If the contributor then wants more information, you can send per the file
@file{/gd/gnuorg/conditions.text}, which explains per options (assign
vs.@: disclaim) and their consequences.
When the contributor emails the form to the FSF, the FSF sends per
papers to sign. If person signs them right away, the whole process
-takes about two weeks--mostly waiting for letters to go back and
+takes a couple of weeks---mostly waiting for letters to go back and
forth.
For less common cases, we have template files you should send to the
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
don't need to distinguish work done at different times, only different
people. They don't need describe changes in more detail than which
files or parts of a file were changed. And they don't need to say
-anything about the function or purpose of a file or change--the
+anything about the function or purpose of a file or change---the
Register of Copyrights doesn't care what the text does, just who wrote
or contributed to which parts.
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
A copyright notice looks like this:
@example
-Copyright (C) @var{year1}, @var{year2}, @var{year3} @var{copyright-holder}
+Copyright (C) @var{year1}, @var{year2}, @var{year3} @var{copyright-holder}
@end example
+The word @samp{Copyright} must always be in English, by international
+convention.
+
The @var{copyright-holder} may be the Free Software Foundation, Inc., or
someone else; you should know who is the copyright holder for your
package.
will work. For example, a program's standard @option{--version}
message should use parenthesized @samp{C} by default, though message
translations may use C-in-a-circle in locales where that symbol is
-known to work.
+known to work. Alternatively, the @samp{(C)} or C-in-a-circle can be
+omitted entirely; the word @samp{Copyright} suffices.
To update the list of year numbers, add each year in which you have
made nontrivial changes to the package. (Here we assume you're using
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,
@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
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
@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
You will naturally want to keep the program running on all the platforms
it supports. But you personally will not have access to most of these
-platforms--so how should you do it?
+platforms---so how should you do it?
Don't worry about trying to get access to all of these platforms. Even
if you did have access to all the platforms, it would be inefficient for
It is important to test the program personally on GNU or GNU/Linux,
because these are the most important platforms for a GNU package. If
-you don't have access to one of these platforms, please ask
-@email{maintainers@@gnu.org} to help you out.
+you don't have access to one of these platforms, as a GNU maintainer
+you can get access to the general GNU login machine; see
+@url{http://www.gnu.org/software/README.accounts.html}.
Supporting other platforms is optional---we do it when that seems like
a good idea, but we don't consider it obligatory. If the users don't
@node Mail
@chapter Dealing With Mail
-@cindex bug reports
+@cindex email
+
+This chapter describes setting up mailing lists for your package, and
+gives advice on how to handle bug reports and random requests once you
+have them.
+
+@menu
+* Standard Mailing Lists:: @samp{bug-pkg@@gnu.org} and other standard names.
+* Creating Mailing Lists:: The best way is to use Savannah.
+* Replying to Mail:: Advice on replying to incoming mail.
+@end menu
+
+
+@node Standard Mailing Lists
+@section Standard Mailing Lists
+
+@cindex standard mailing lists
+@cindex mailing lists, standard names of
-@cindex email, for receiving bug reports
@cindex mailing list for bug reports
Once a program is in use, you will get bug reports for it. Most GNU
programs have their own special lists for sending bug reports. The
advertised bug-reporting email address should always be
@samp{bug-@var{program}@@gnu.org}, to help show users that the program
is a GNU package, but it is ok to set up that list to forward to another
-site for further forwarding. The package distribution should state the
+site if you prefer. The package distribution should state the
name of the bug-reporting list in a prominent place, and ask users to
help us by reporting bugs there.
+@cindex @email{bug-gnu-utils@@gnu.org}
We also have a catch-all list, @email{bug-gnu-utils@@gnu.org}, which is
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 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.
+@cindex help for users, mailing list for
+Some GNU programs with many users have another mailing list,
+@samp{help-@var{program}.org}, for people to ask other users for help.
+If your program has many users, you should create such a list for it.
+For a fairly new program, which doesn't have a large user base yet, it
+is better not to bother with this.
+
+@cindex announcements, mailing list for
+If you wish, you can also have a mailing list
+@samp{info-@var{program}} for announcements (@pxref{Announcements}),
+and any others you find useful.
+
+
+@node Creating Mailing Lists
+@section Creating Mailing Lists
+
+@cindex creating mailing lists
+@cindex mailing lists, creating
+
+Using the web interface on @code{savannah.gnu.org} is by far the
+easiest way to create normal mailing lists, managed through Mailman on
+the GNU mail server. Once you register your package on Savannah, you
+can create (and remove) lists yourself through the `Mailing Lists'
+menu, without needing to wait for intervention by anyone else.
+Furthermore, lists created through Savannah will have a reasonable
+default configuration for antispam purposes (see below).
+
+To create and maintain simple aliases and unmanaged lists, you can
+edit @file{/com/mailer/aliases} on the main GNU server. If you don't
+have an account there, please read
+@url{http://www.gnu.org/software/README.accounts.html} (@pxref{Getting
+a GNU Account}).
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
@email{new-mailing-list@@gnu.org}. You can subscribe to a list managed
by Mailman by sending mail to the corresponding @samp{-request} address.
+@cindex spam prevention
You should moderate postings from non-subscribed addresses on your
mailing lists, to prevent propagation of unwanted messages (``spam'')
to subscribers and to the list archives. For lists controlled by
periodically (daily is best) reviewing the held messages, accepting
the real ones and discarding the junk.
+Lists created through Savannah will have this setting, and a number of
+others, such that spam will be automatically deleted (after a short
+delay). The Savannah mailing list page describes all the details.
+You should still review the held messages in order to approve any that
+are real.
+
+
+@node Replying to Mail
+@section Replying to Mail
+
@cindex responding to bug reports
+@cindex bug reports, handling
+@cindex help requests, handling
+
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 each person who sends a bug report.
time, just ``thanks for the bug report---I will fix it'' is enough
response.
-Some GNU packages, such as Emacs and GCC, come with advice about how to
-make bug reports useful. If you want to copy and adapt that, it could
-be a very useful thing to do.
+Some GNU packages, such as Emacs and GCC, come with advice about how
+to make bug reports useful. Copying and adapting that could be very
+useful for your package.
@node Old Versions
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, please 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
@node Distribution on ftp.gnu.org
@section Distribution on @code{ftp.gnu.org}
@cindex GNU ftp site
-@cindex @code{ftp.gnu.org}, the GNU ftp site
+@cindex @code{ftp.gnu.org}, the GNU release site
-GNU packages are distributed through directory @file{/gnu} on
-@code{ftp.gnu.org}. Each package should have a subdirectory
-named after the package, and all the distribution files for the package
-should go in that subdirectory.
+GNU packages are distributed through the directory @file{/gnu} on
+@code{ftp.gnu.org}, via both HTTP and FTP. Each package should have a
+subdirectory named after the package, and all the distribution files
+for the package should go in that subdirectory.
@c If you have an interest in seeing the monthly download logs from the FTP
@c site at @code{ftp.gnu.org} for your program, that is something that
@cindex beta releases
@cindex pretest releases
-@cindex @code{alpha.gnu.org}, ftp site for test releases
+@cindex @code{alpha.gnu.org}, test release site
When you release a greatly changed new major version of a program, you
might want to do so as a pretest. 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.)
-We normally use the FTP server @code{alpha.gnu.org} for pretests and
+We normally use the server @code{alpha.gnu.org} for pretests and
prerelease versions. @xref{Automated FTP Uploads}, for procedural details
of putting new versions on @code{alpha.gnu.org}.
@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
@item
Create an account for yourself at @url{http://savannah.gnu.org}, if
you don't already have one. By the way, this is also needed to
-maintain the web pages at @url{www.gnu.org} for your project
+maintain the web pages at @url{http://www.gnu.org} for your project
(@pxref{Web Pages}).
@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
-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
@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
@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
@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
package. You also receive a message when your upload has been successfully
processed.
-If you have difficulties processing an upload, email
+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
+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 with an upload, email
@email{ftp-upload@@gnu.org}.
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:
version: 1.1
directory: bar/v1
archive: foo-1.1.tar.gz
-comment: archive an old file; it will not be available through FTP anymore
+comment: archive an old file; it will not be
+comment: available through FTP any more.
@end example
@noindent
version: 1.1
directory: bar/v1
archive: foo
-comment: archive an old directory; it will not be available through FTP anymore
+comment: archive an old directory; it and its entire
+comment: contents will not be available through FTP anymore
@end example
@noindent
@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.
+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 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. Here, 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} (GNU Planet). You can also post items
+directly, or arrange for feeds from other locations; see 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 decide as you see fit what
+events are worth announcing. (@xref{Mail}, for setting this up, and
+more suggestions on handling mail for your package.)
+
+@cindex contents of announcements
+When writing an announcement, please include the following:
-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.
+@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 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
@cindex web pages
-Please write web pages about your package for installation on
+Please write web pages about your package, and install them 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
-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.
+We encourage you to use the standard @code{www.gnu.org} template as
+the basis for your pages:
+@url{http://www.gnu.org/server/@/standards/@/boilerplate-source.html}.
+
+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 archives 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, 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 named @file{.symlinks}
+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 list all GNU manuals on the page
+@url{http://www.gnu.org/manual}, so if yours isn't there, please send
+mail to @code{webmasters@@gnu.org}, asking them to add yours, 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
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
+
+@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:
-@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,
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
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}.
@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
cvs add -ko @var{file1} @var{file2} ...
@end example
-@xref{Keyword substitution,,,cvs,Version Management with CVS}.
+@c The CVS manual is now built with numeric references and no nonsplit
+@c form, so it's not worth trying to give a direct link.
+See the ``Keyword Substitution'' section in the CVS manual, available
+at @url{http://ximbiot.com/cvs/manual}.
In Texinfo source, the recommended way to literally specify a
``dollar'' keyword is:
are some patents which we know are likely to be used to threaten free
software, so we make an effort to avoid the patented techniques. If
you are concerned about the danger of a patent and would like advice,
-write to @email{maintainers@@gnu.org}, and we will try to help you get
+write to @email{licensing@@gnu.org}, and we will try to help you get
advice from a lawyer.
Sometimes the GNU project takes a strong stand against a particular
@cindex source repository
@cindex version control system
@cindex FTP site
+@cindex release site
@cindex hosting
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.
+repository for your package, but that's not required. @xref{Old
+Versions}, for more information about Savannah.
+
+We strongly urge you to use @code{ftp.gnu.org} as the standard
+distribution site. Doing so makes it easier for developers and users
+to find the latest GNU releases. However, it is ok to use another
+server if you wish, provided it allows access from the general public
+without limitation (for instance, without excluding any country).
-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
-ftp site, please put this statement in a prominent place on the site,
-so as to prevent people from getting the wrong idea about the
-relationship between the package and the company:
+If you use a company's machine to hold the repository for your
+program, or as its ftp site, please put this statement in a prominent
+place on the site, so as to prevent people from getting the wrong idea
+about the relationship between the package and the company:
@smallexample
The programs <list of them> hosted here are free software packages
@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
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:
projects / gnulib.git / blobdiff