@c For double-sided printing, uncomment:
@c @setchapternewpage odd
@c This date is automagically updated when you save this file:
-@set lastupdate December 6, 2005
+@set lastupdate May 23, 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 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
@end ifnottex
@menu
-* Preface::
-* Stepping Down::
-* Recruiting Developers::
-* Legal Matters::
-* Clean Ups::
-* Platforms::
-* Mail::
-* Old Versions::
-* Distributions::
-* Web Pages::
-* Ethical and Philosophical Consideration::
-* Terminology::
-* Hosting::
-* Free Software Directory::
-* Using the Proofreaders List::
-* Index::
+* Preface::
+* Stepping Down::
+* Recruiting Developers::
+* Legal Matters::
+* Clean Ups::
+* Platforms::
+* Mail::
+* Old Versions::
+* Distributions::
+* Web Pages::
+* Ethical and Philosophical Consideration::
+* Terminology::
+* Hosting::
+* Free Software Directory::
+* Using the Proofreaders List::
+* Index::
@end menu
@node Preface
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}.
as you maintain the program, to avoid legal difficulties.
@menu
-* Copyright Papers::
+* Copyright Papers::
* Legally Significant::
* Recording Contributors::
+* Copying from Other Packages::
* Copyright Notices::
* License Notices::
* External Libraries::
@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; 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.)
+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.)
In order for the contributor to know person should sign papers, you need
to ask for the necessary papers. If you don't know per well, and you
Once the conversation is under way and the contributor is ready for
more details, you should send one of the templates that are found in
-the directory @file{/gd/gnuorg/Copyright/}. This section explains
-which templates you should use in which circumstances. @strong{Please
-don't use any of the templates except for those listed here, and
-please don't change the wording.}
+the directory @file{/gd/gnuorg/Copyright/}; they are also available
+from the @file{doc/Copyright/} directory of the @code{gnulib} project
+at @url{http://savannah.gnu.org/projects/gnulib}. This section
+explains which templates you should use in which circumstances.
+@strong{Please don't use any of the templates except for those listed
+here, and please don't change the wording.}
Once the conversation is under way, you can send the contributor the
precise wording and instructions by email. Before you do this, make
For large changes, ask the contributor for an assignment. Send per a
copy of the file @file{request-assign.changes}. (Like all the
-@samp{request-} files, it is in @file{/gd/gnuorg/Copyright}.)
+@samp{request-} files, it is in @file{/gd/gnuorg/Copyright} and in
+@code{gnulib}.)
For medium to small changes, request a disclaimer by sending per the
file @file{request-disclaim.changes}.
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
@cindex copyright notices in program files
-You should maintain a proper copyright notice and a license notice in
-each nontrivial file in the package. (Any file more than ten lines
-long is nontrivial for this purpose.) This includes header files and
-interface definitions for building or running the program,
-documentation files, and any supporting files. If a file has been
-explicitly placed in the public domain, then instead of a copyright
-notice, it should have a notice saying explicitly that it is in the
-public domain.
+You should maintain a proper copyright notice and a license
+notice in each nontrivial file in the package. (Any file more than ten
+lines long is nontrivial for this purpose.) This includes header files
+and interface definitions for
+building or running the program, documentation files, and any supporting
+files. If a file has been explicitly placed in the public domain, then
+instead of a copyright notice, it should have a notice saying explicitly
+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
translations may use C-in-a-circle in locales where that symbol is
known to work.
-To update the list of year numbers, add each year in which you change
-the package. (Here we assume you're using a publicly accessible
-revision control server, so that every revision installed is also
-immediately and automatically published.)
+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
+a publicly accessible revision control server, so that every revision
+installed is also immediately and automatically published.) When you
+add the new year, it is not required to keep track which files have
+seen significant changes in the new year and which have not. It is
+recommended and simpler to add the new year to all files in the
+package, and be done with it for the rest of the year.
+
+For files which are regularly copied from another project (such as
+@samp{gnulib}), the copyright notice should left as it is in the
+original.
Don't delete old year numbers, though; they can indicate when older
versions might theoretically go into the public domain. If you copy a
Do not abbreviate the year list using a range; for instance, do not
write @samp{1996--1998}; instead, write @samp{1996, 1997, 1998}.
+The copyright statement may be split across multiple lines, both in
+source files and in any generated output. This often happens for
+files with a long history, having many different years of
+publication.
+
For an FSF-copyrighted package, if you have followed the procedures to
obtain legal papers, each file should have just one copyright holder:
the Free Software Foundation, Inc. You should edit the file's
displayed when the program starts up. This copyright notice should
mention the year of completion of the most recent major version; it
can mention years of completion of previous major versions, but that
+is optional.
@node License Notices
@item
The directory @file{/gd/gnuorg} on the host
-@code{fencepost.gnu.org}. (You can ask @email{accounts@@gnu.org}
+@code{fencepost.gnu.org}. (You can ask @email{accounts@@gnu.org}
for an account there if you don't have one).
@item
@smallexample
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
+under the terms of the GNU Free Documentation License, Version 1.2 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
@end smallexample
If the FSF does not publish this manual on paper, then omit the last
-sentence in (b) that talks about copies from GNU Press. If the FSF is
+sentence in (a) that talks about copies from GNU Press. If the FSF is
not the copyright holder, then replace @samp{FSF} with the appropriate
name.
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
distributions.
@menu
-* Distribution tar Files::
-* Distribution Patches::
-* Distribution on ftp.gnu.org::
-* Test Releases::
-* Automated FTP Uploads::
-* Announcements::
+* Distribution tar Files::
+* Distribution Patches::
+* Distribution on ftp.gnu.org::
+* Test Releases::
+* Automated FTP Uploads::
+* Announcements::
@end menu
@node Distribution tar Files
@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
-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.
+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.
+
+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
about GNU.
@menu
-* Free Software and Open Source::
-* GNU and Linux::
+* Free Software and Open Source::
+* GNU and Linux::
@end menu
@node Free Software and Open Source
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
projects / gnulib.git / blobdiff