@c For double-sided printing, uncomment:
@c @setchapternewpage odd
@c This date is automagically updated when you save this file:
-@set lastupdate January 4, 2005
+@set lastupdate October 9, 2006
@c %**end of header
@dircategory GNU organization
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.
+2001, 2002, 2003, 2004, 2005, 2006 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
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.
+
+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 legally valid copyright notice and a license
+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
+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
remains the end.
When a file is automatically generated from some other file in the
-distribution, it is useful to copy the copyright notice and permission
-notice of the file it is generated from, if you can. Alternatively, put
-a notice at the beginning saying which file it is generated from.
+distribution, it is useful for the automatic procedure to copy the
+copyright notice and permission notice of the file it is generated
+from, if possible. Alternatively, put a notice at the beginning saying
+which file it is generated from.
A copyright notice looks like this:
translations may use C-in-a-circle in locales where that symbol is
known to work.
-The list of year numbers should include each year in which you finished
-preparing a version which was actually released, and which was an
-ancestor of the current version.
+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.
-Please reread the paragraph above, slowly and carefully. It is
-important to understand that rule precisely, much as you would
-understand a complicated C statement in order to hand-simulate it.
+For files which are regularly copied from another project (such as
+@samp{gnulib}), the copyright notice should left as it is in the
+original.
-This list is @emph{not} a list of years in which versions were
-@emph{released}. It is a list of years in which versions, later
-released, were @emph{completed}. So if you finish a version on Dec 31,
-1994 and release it on Jan 1, 1995, this version requires the inclusion
-of 1994, but doesn't require the inclusion of 1995.
+Don't delete old year numbers, though; they can indicate when older
+versions might theoretically go into the public domain. If you copy a
+file into the package from some other program, keep the copyright
+years that come with the file.
Do not abbreviate the year list using a range; for instance, do not
-write @samp{1996--1998}; instead, write @samp{1996, 1997, 1998}. Do
-write each relevant year as a four-digit number. In the normal course
-of maintenance, you may come across copyright notices which omit the
-century, as in @samp{1996, 97, 98}---change these to include the
-century. However, there is no need to systematically change the
-notice in every old file.
-
-The versions that matter, for purposes of this list, are versions that
-were ancestors of the current version. So if you made a temporary
-branch in maintenance, and worked on branches A and B in parallel, then
-each branch would have its own list of years, which is based on the
-versions released in that branch. A version in branch A need not be
-reflected in the list of years for branch B, and vice versa.
-
-However, if you copy code from branch A into branch B, the years for
-branch A (or at least, for the parts that you copied into branch B) do
-need to appear in the list in branch B, because now they are ancestors
-of branch B.
-
-This rule is complicated. If we were in charge of copyright law, we
-would probably change this (as well as many other aspects).
+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:
But if contributors are not all assigning their copyrights to a single
copyright holder, it can easily happen that one file has several
-copyright holders. Each contributor of nontrivial amounts is a
-copyright holder.
+copyright holders. Each contributor of nontrivial text is a copyright
+holder.
In that case, you should always include a copyright notice in the name
of main copyright holder of the file. You can also include copyright
-notices for other copyright holders as well, and this is a good idea for
-those who have contributed a large amount and for those who specifically
-ask for notices in their names. But you don't have to include a notice
-for everyone who contributed to the file, and that would be rather
-inconvenient.
+notices for other copyright holders as well, and this is a good idea
+for those who have contributed a large amount and for those who
+specifically ask for notices in their names. (Sometimes the license
+on code that you copy in may require preserving certain copyright
+notices.) But you don't have to include a notice for everyone who
+contributed to the file (which would be rather inconvenient).
+
+Sometimes a program has an overall copyright notice that refers to the
+whole program. It might be in the @file{README} file, or it might be
+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
@section 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
You should have received a copy of the GNU General Public License
along with @var{program}; see the file COPYING. If not, write to
-the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-Boston, MA 02111-1307, USA.
+the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
+Boston, MA 02110-1301 USA.
@end quotation
But in a small program which is just a few files, you can use
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
-59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
+51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
@end quotation
Documentation files should have license notices also. Manuals should
@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.
notice and this notice are preserved.
@end smallexample
+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
+license for these macros.
+
If you would like help with license issues or with using the GFDL,
please contact @email{licensing@@gnu.org}.
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.
-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.
+@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.
+
+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
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}
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
projects / gnulib.git / blobdiff