@c For double-sided printing, uncomment:
@c @setchapternewpage odd
@c This date is automagically updated when you save this file:
-@set lastupdate March 22, 2006
+@set lastupdate June 26, 2007
@c %**end of header
@dircategory GNU organization
@copying
Information for maintainers of GNU software, last updated @value{lastupdate}.
-Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
-2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
+2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software
+Foundation, Inc.
@quotation
Permission is granted to make and distribute verbatim copies
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.) @file{/gd/gnuorg/maintain.tar.gz} is a tar file containing
-all of these files in that directory which are mentioned in this file;
-it is updated daily.
+package.)
This release of the GNU Maintenance Instructions was last updated
@value{lastupdate}.
@menu
* Copyright Papers::
* Legally Significant::
-* Recording Contributors::
-* Copyright Notices::
-* License Notices::
-* External Libraries::
+* Recording Contributors::
+* Copying from Other Packages::
+* Copyright Notices::
+* License Notices::
+* External Libraries::
@end menu
@node Copyright Papers
Only the contributions that are legally significant for copyright
purposes (@pxref{Legally Significant}) need to be listed. Small
-contributions, ideas, etc., can be omitted.
+contributions, bug reports, ideas, etc., can be omitted.
For example, this would describe an early version of GAS:
Please keep these records in a file named @file{AUTHORS} in the source
directory for the program itself.
+You can use the change log as the basis for these records, if you
+wish. Just make sure to record the correct author for each change
+(the person who wrote the change, @emph{not} the person who installed
+it), and add @samp{(tiny change)} for those changes that are too
+trivial to matter for copyright purposes. Later on you can update the
+@file{AUTHORS} file from the change log. This can even be done
+automatically, if you are careful about the formatting of the change
+log entries.
+
+@node Copying from Other Packages
+@section Copying from Other Packages
+
+When you copy legally significant code from another free software
+package with a GPL-compatible license, you should look in the
+package's records to find out the authors of the part you are copying,
+and list them as the contributors of the code that you copied. If all
+you did was copy it, not write it, then for copyright purposes you are
+@emph{not} one of the contributors of @emph{this} code.
+
+Especially when code has been released into the public domain, authors
+sometimes fail to write a license statement in each file. In this
+case, please first be sure that all the authors of the code have
+disclaimed copyright interest. Then, when copying the new files into
+your project, add a brief note at the beginning of the files recording
+the authors, the public domain status, and anything else relevant.
+
+On the other hand, when merging some public domain code into an
+existing file covered by the GPL (or LGPL or other free software
+license), there is no reason to indicate the pieces which are public
+domain. The notice saying that the whole file is under the GPL (or
+other license) is legally sufficient.
+
+Using code that is released under a GPL-compatible free license,
+rather than being in the public domain, may require preserving
+copyright notices or other steps. Of course, you should do what is
+needed.
+
+If you are maintaining an FSF-copyrighted package, please verify we
+have papers for the code you are copying, @emph{before} copying it.
+If you are copying from another FSF-copyrighted package, then we
+presumably have papers for that package's own code, but you must check
+whether the code you are copying is part of an external library; if
+that is the case, we don't have papers for it, so you should not copy
+it. It can't hurt in any case to double-check with the developer of
+that package.
+
+When you are copying code for which we do not already have papers, you
+need to get papers for it. It may be difficult to get the papers if
+the code was not written as a contribution to your package, but that
+doesn't mean it is ok to do without them. If you cannot get papers
+for the code, you can only use it as an external library
+(@pxref{External Libraries}).
+
@node Copyright Notices
@section Copyright Notices
entitled "GNU Free Documentation License".
(a) The FSF's Back-Cover Text is: ``You are free to copy and modify
-this GNU Manual. Buying copies from GNU Press supports the FSF in
+this GNU Manual. Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom.''
-
@end smallexample
If the FSF does not publish this manual on paper, then omit the last
you don't have access to one of these platforms, please ask
@email{maintainers@@gnu.org} to help you out.
-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 take
-care of a certain platform, you may have to desupport it unless and
-until users come forward to help. Conversely, if a user offers changes
-to support an additional platform, you will probably want to install
-them, but you don't have to. If you feel the changes are complex and
-ugly, if you think that they will increase the burden of future
-maintenance, you can and should reject them. This includes both free
-platforms such as NetBSD or FreeBSD and non-free platforms such as
-Windows.
+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
+take care of a certain platform, you may have to desupport it unless
+and until users come forward to help. Conversely, if a user offers
+changes to support an additional platform, you will probably want to
+install them, but you don't have to. If you feel the changes are
+complex and ugly, if you think that they will increase the burden of
+future maintenance, you can and should reject them. This includes
+both free or mainly-free platforms such as OpenBSD, FreeBSD, and
+NetBSD, and non-free platforms such as Windows.
+
@node Mail
@chapter Dealing With Mail
@menu
* Automated Upload Registration::
* Automated Upload Procedure::
+* FTP Upload Directive File - v1.1::
+* FTP Upload Directive File - v1.0::
@end menu
@cindex uploads
-Once you have registered your information, as described in the
+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.
@enumerate
@item
-File to distributed (e.g., @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}
@item
A clearsigned @dfn{directive file}, made using @samp{gpg --clearsign}
(for example, @file{foo.tar.gz.directive.asc}).
-
@end enumerate
-Upload the triplet via anonymous ftp to @code{ftp-upload.gnu.org}. If
-the upload is destined for @code{ftp.gnu.org}, then place the triplet
-in the @file{/incoming/ftp} directory. If the upload is destined for
-@code{alpha.gnu.org}, then place the triplet in the
-@file{/incoming/alpha} directory.
+The names of the files are important. The signature file must have the
+same name as the file to be distributed, with an additional
+@file{.sig} extension. The directive file must have the same name as
+the file to be distributed, with an additional @file{.directive.asc}
+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.
+
+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
+the @file{/incoming/ftp} directory. If the upload is destined for
+@code{alpha.gnu.org}, place the file(s) in the @file{/incoming/alpha}
+directory.
+
+Uploads are processed every five minutes. Uploads that are in progress while
+the upload processing script is running are handled properly, so do not worry
+about the timing of your upload.
+
+Your designated upload email addresses (@pxref{Automated Upload Registration})
+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.
+
+If you have difficulties processing an upload, email
+@email{ftp-upload@@gnu.org}.
+
+
+@node FTP Upload Directive File - v1.1
+@subsection FTP Upload Directive File - v1.1
+
+The directive file name must end in @file{directive.asc}.
+
+When part of a triplet, the directive file must always contain the
+directives @code{version}, @code{directory} and @code{filename}, as
+described. In addition, a 'comment' directive is allowed.
+
+The @code{version} directive must always have the value @samp{1.1}.
+
+The @code{directory} directive specifies the final destination
+directory where the uploaded file and its @file{.sig} companion are to
+be placed.
+
+The @code{filename} directive must contain the name of the file to be
+distributed (item@tie{}(1) above).
+
+For example, as part of an uploaded triplet, a
+@file{foo.tar.gz.directive.asc} file might contain these lines (before
+being gpg clearsigned):
+
+@example
+version: 1.1
+directory: bar/v1
+filename: foo.tar.gz
+comment: hello world!
+@end example
+
+This directory line indicates that @file{foo.tar.gz} and
+@file{foo.tar.gz.sig} are part of package @code{bar}. If you uploaded
+this triplet to @file{/incoming/ftp} and the system positively
+authenticates the signatures, the files @file{foo.tar.gz} and
+@file{foo.tar.gz.sig} will be placed in the directory
+@file{gnu/bar/v1} of the @code{ftp.gnu.org} site.
+
+The directive file can be used to create currently non-existent
+directory trees, as long as they are under the package directory for
+your package (in the example above, that is @code{bar}).
+
+If you upload a file that already exists in the FTP directory, the
+original will simply be archived and replaced with the new upload.
+
+@subheading Standalone directives
+
+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.
+
+If you use more than one directive, the directives are executed in the
+sequence they are specified in.
-Uploads are processed every five minutes. Uploads that are in
-progress when the upload processing script is running are handled
-properly, so do not worry about the timing of your upload.
+Here are a few examples. The first removes a symlink:
+
+@example
+version: 1.1
+directory: bar/v1
+rmsymlink: foo-latest.tgz
+comment: remove a symlink
+@end example
+
+@noindent
+Archive an old file, taking it offline:
+
+@example
+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
+@end example
+
+@noindent
+Create a new symlink:
+
+@example
+version: 1.1
+directory: bar/v1
+symlink: foo-1.2.tar.gz foo-latest.tgz
+comment: create a new symlink
+@end example
+
+@noindent
+Do everything at once:
+
+@example
+version: 1.1
+directory: bar/v1
+rmsymlink: foo-latest.tgz
+symlink: foo-1.2.tar.gz foo-latest.tgz
+archive: foo-1.1.tar.gz
+comment: now do everything at once
+@end example
+
+
+@node FTP Upload Directive File - v1.0
+@subsection FTP Upload Directive File - v1.0
+
+@dfn{As of June 2006, the upload script is running in compatibility
+mode, allowing uploads with either version@tie{}1.1 or
+version@tie{}1.0 of the directive file syntax. Support for v1.0
+uploads will be phased out by the end of 2006, so please upgrade
+to@tie{}v1.1.}
The directive file should contain one line, excluding the clearsigned
data GPG that inserts, which specifies the final destination directory
-where items (1) and (2) to be placed.
+where items (1) and (2) are to be placed.
-For example, the @file{foo.tar.gz.directive} file might contain the
+For example, the @file{foo.tar.gz.directive.asc} file might contain the
single line:
@example
directory trees, as long as they are under the package directory for
your package (in the example above, that is @code{bar}).
-Your designated upload email addresses (@pxref{Automated Upload
-Registration}) 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.
-
-If you have difficulties processing an upload, email
-@email{ftp-upload@@gnu.org}.
-
@node Announcements
@section Announcing Releases
announce pretest releases, only real releases. But real releases do
include releases made just to fix bugs.
-@node Web Pages
+@node Web Pages
@chapter Web Pages
@cindex web pages
them up on whatever site is convenient for you, and make the pages on
@code{www.gnu.org} link to that site.
-Web pages for GNU packages should not include GIF images, since the GNU
-project avoids GIFs due to patent problems. @xref{Ethical and
-Philosophical Consideration}.
+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}.
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
+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.
* CVS Keywords in Web Pages::
@end menu
-@node Invoking gendocs.sh
-@section Invoking @command{gendocs.sh}
+@node Invoking gendocs.sh
+@section Invoking @command{gendocs.sh}
@pindex gendocs.sh
@cindex generating documentation output
The script @command{gendocs.sh} eases the task of generating the
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
+for the HTML index pages. Both are available from the Texinfo CVS
sources:
@format
@uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh}
output avoiding the literal keyword string.
-@node Ethical and Philosophical Consideration
+@node Ethical and Philosophical Consideration
@chapter Ethical and Philosophical Consideration
@cindex ethics
@cindex philosophy
software.
Beyond that, sometimes the GNU project takes a strong stand against a
-particular patented technology in order to encourage everyone to reject
-it.
-
-For example, the GIF file format is covered by the LZW software patent
-in the USA. A patent holder has threatened lawsuits against not only
-developers of software to produce GIFs, but even web sites that
-contain them.
-
-For this reason, you should not include GIFs in the web pages for your
-package, nor in the distribution of the package itself. It is ok for
-a GNU package to support displaying GIFs which will come into play if
-a user asks it to operate on one. However, it is essential to provide
-equal or better support for the competing PNG and JPG
-formats---otherwise, the GNU package would be @emph{pressuring} users
-to use GIF format, and that it must not do. More about our stand on
-GIF is available at @uref{http://www.gnu.org/philosophy/gif.html}.
+particular patented technology in order to encourage everyone to
+reject it. For example, until the GIF patents expired in 2006, we
+specified that GNU packages and web pages should not include GIF image
+files, and that equal or better support for other image formats such
+as PNG and JPEG was crucial. (These other formats remain superior, so
+there is still no particular reason to use GIF's.)
Software patents are not the only matter for ethical concern. A GNU
package should not recommend use of any non-free program, nor should it
of the GNU kernel, please call it ``the Hurd'' or ``the GNU Hurd.''
Note that this uses a space, not a slash.
-@node Hosting
+@node Hosting
@chapter Hosting
@cindex CVS repository
@cindex repository