@c For double-sided printing, uncomment:
@c @setchapternewpage odd
@c This date is automagically updated when you save this file:
-@set lastupdate January 12, 2012
+@set lastupdate October 9, 2013
@c %**end of header
@dircategory GNU organization
Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
-2010, 2011, 2012 Free Software Foundation, Inc.
+2010, 2011, 2012, 2013 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
* Web Pages::
* Ethical and Philosophical Consideration::
* Terminology::
+* Interviews and Speeches::
* Hosting::
* Donations::
* Free Software Directory::
@cindex down, when GNU machines are
@cindex outage, of GNU machines
-@cindex @url{http://identi.ca/group/fsfstatus}
+@cindex @url{https://pumprock.net/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
+@url{http://pumprock.net/fsfstatus}. Most likely the problem, if
it can be alleviated at the FSF end, is already being worked on.
@cindex sysadmin, FSF
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,
+you should have an account there. If you don't have one already, see
@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.
+the package. Such GNU login accounts include email
+(see @url{http://www.fsf.org/about/systems/sending-mail-via-fencepost}).
@end macro
@gdgnuorgtext{}
@node Copyright Papers
@section Copyright Papers
@cindex copyright papers
-
-If you maintain an FSF-copyrighted package
-certain legal procedures are required when incorporating legally significant
-changes written by other people. This ensures that the FSF has the
-legal right to distribute the package, and the standing to defend its
-GPL-covered status in court if necessary.
-
-@strong{Before} incorporating significant changes, make sure that the
+@cindex assignments, copyright
+@cindex disclaimers
+
+If you maintain an FSF-copyrighted package, certain legal procedures
+are required when incorporating legally significant changes written by
+other people. This ensures that the FSF has the legal right to
+distribute the package, and the standing to defend its GPL-covered
+status in court if necessary.
+
+GNU packages need not be FSF-copyrighted; this is up to the author(s),
+generally at the time the package is dubbed GNU. When copyright is
+assigned to the FSF, the FSF can act to stop GPL violations about the
+package. Otherwise, legal actions are up to the author(s). The rest
+of this section is about the case when a package is FSF-copyrighted.
+
+@emph{Before} incorporating significant changes, make sure that the
person who wrote the changes has signed copyright papers and that the
-Free Software Foundation has received and signed them. We may also need
-an employer's disclaimer from the person's employer.
+Free Software Foundation has received and signed them. We may also
+need an employer's disclaimer from the person's employer, which
+confirms that the work was not part of the person's job and the
+employer makes no claim on it. However, a copy of the person's
+employment contract, showing that the employer can't claim any rights
+to this work, is often sufficient.
+
+If the employer does claim the work was part of the person's job, and
+there is no clear basis to say that claim is invalid, then we have to
+consider it valid. Then the person cannot assign copyright, but the
+employer can. Many companies have done this. Please ask the
+appropriate managers to contact @code{assign@@gnu.org}.
@cindex data base of GNU copyright assignments
To check whether papers have been received, look in
getting an employer's disclaimer from the contributor's employer.
When the contributor emails the form to the FSF, the FSF sends per an
-electronic (usually PDF) copy of the assignment. All contributors
-then print the assignment and sign it. Contributors residing outside
-the U.S. must mail the signed form to the FSF via the post.
-Contributors located in the U.S. can then email or fax a scanned copy
-back to the FSF (or use postal mail, if they prefer). (To emphasize,
-the necessary distinction is between US residents and non-residents,
-citizenship does not matter.)
+electronic (usually PDF) copy of the assignment. This, or whatever
+response is required, should happen within five business days of the
+initial request. If no reply from the FSF comes after that time,
+please send a reminder. If there is still no response after an
+additional week, please write to @email{maintainers@@gnu.org} about it.
+
+After receiving the necessary form, the contributor needs to sign it.
+Contributors residing in the USA may use GPG in order to sign their
+assignment. Contributors located in the USA or Germany can print,
+sign, and then email (or fax) a scanned copy back to the FSF.
+(Specific instructions for both cases are sent with the assignment
+form.) They may use postal mail, if they prefer. Contributors
+residing outside the USA or Germany must mail the signed form to the
+FSF via postal mail. To emphasize, the necessary distinction is
+between residents and non-residents of these countries; citizenship
+does not matter.
For less common cases, we have template files you should send to the
contributor. Be sure to fill in the name of the person and the name
@node Copying from Other Packages
@section Copying from Other Packages
+This section explains legal considerations when merging code from
+other packages into your package. Using an entire module as a whole,
+and maintaining its separate identity, is a different issue;
+see @ref{External Libraries}.
+
+@menu
+* Non-FSF-Copyrighted Package::
+* FSF-Copyrighted Package::
+@end menu
+
+@node Non-FSF-Copyrighted Package
+@subsection Non-FSF-Copyrighted Package
+
+Here we suppose that your package is not FSF-copyrighted.
+
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,
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.
+If the code is supposed to be in the public domain, make sure that is
+really true: 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
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.
+Using code that is not in the public domain, but rather released under
+a GPL-compatible free license, may require preserving copyright
+notices or other steps. Of course, you should follow the requirements
+stated.
+
+@node FSF-Copyrighted Package
+@subsection FSF-Copyrighted Package
+
+If you are maintaining an FSF-copyrighted package, please don't copy
+in any code without verifying first that we have suitable legal papers
+for that 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
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.
+can omit both cover texts. However, if it is copyright FSF, always
+ask the FSF what to do.
@xref{GNU Sample Texts,,, texinfo, Texinfo}, for a full example in a
Texinfo manual, and see
useful functionality, as a ``library'' facility (though the module is
not always packaged technically as a library).
-In a case like this, it would be unreasonable to ask the author of that
-module to assign the copyright to the FSF. After all, person did not
-write it specifically as a contribution to your package, so it would be
-impertinent to ask per, out of the blue, ``Please give the FSF your
+Make sure the license of the module is compatible with current @emph{and
+future} GPL versions. ``GNU GPL version 3 or later'' is good, and
+so is anything which includes permission for use under those GPL
+versions (including ``GNU GPL version 2 or later'', ``LGPL version
+@var{n} or later'', ``LGPL version 2.1'', ``GNU Affero GPL version 3
+or later''). Lax permissive licenses are ok too, since they are
+compatible with all GPL versions.
+
+``GPL version 2 only'' is obviously unacceptable because it is
+incompatible with GPL version 3. ``GPL version 3 only'' and ``GPL
+version 2 or 3 only'' have a subtler problem: they would be incompatible
+with GPL version 4, if we ever make one, so the module would become an
+obstacle to upgrading your package's license to ``GPL version 4 or
+later''.
+
+One package you need to avoid is @code{goffice}, since it allows only
+GPL versions 2 and 3.
+
+It would be unreasonable to ask the author of the external module to
+assign its copyright to the FSF. After all, person did not write
+it specifically as a contribution to your package, so it would be
+impertinent to ask, out of the blue, ``Please give the FSF your
copyright.''
-So the thing to do in this case is to make your program use the module,
-but not consider it a part of your program. There are two reasonable
-methods of doing this:
+So make your program use the module but without treating the module as
+a part of your program. There are two reasonable methods of doing
+this:
@enumerate
@item
@url{http://www.gnu.org/software/README.accounts.html} (@pxref{GNU
Accounts and Resources}).
-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
-bug-reporting list for your program. To set up a new list, contact
-@email{new-mailing-list@@gnu.org}. You can subscribe to a list managed
-by Mailman by sending mail to the corresponding @samp{-request} address.
+But if you don't want to learn how to do those things, you can ask
+@email{new-mailing-list@@gnu.org} to help you.
@cindex spam prevention
You should moderate postings from non-subscribed addresses on your
@node Distributions
@chapter Distributions
-It is important to follow the GNU conventions when making GNU software
+Please follow the GNU conventions when making GNU software
distributions.
@menu
It's wise to test your patch by applying it to a copy of the old
version, and checking that the result exactly matches the new version.
+
@node Distribution on ftp.gnu.org
@section Distribution on @code{ftp.gnu.org}
@cindex GNU ftp site
@cindex @code{ftp.gnu.org}, the GNU release site
-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.
+We strongly recommend using @code{ftp.gnu.org} to distribute official
+releases. If you want to also distribute the package from a site of
+your own, that is fine. To use some other site instead of
+@code{ftp.gnu.org} is acceptable, provided it allows connections from
+anyone anywhere.
+
+@xref{Automated FTP Uploads}, for the procedural details of putting
+new versions on @code{ftp.gnu.org}.
-@xref{Automated FTP Uploads}, for procedural details of putting new
-versions on @code{ftp.gnu.org}.
@node Test Releases
@section Test Releases
a suitable GNU mailing list/newsgroup to recruit them.)
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}.
+prerelease versions. @xref{Automated FTP Uploads}, for the procedural
+details of putting new versions on @code{alpha.gnu.org}.
Once a program gets to be widely used and people expect it to work
solidly, it is a good idea to do pretest releases before each ``real''
information. Then, you can perform uploads yourself, with no
intervention needed by the system administrators.
-The general idea is that releases should be crytographically signed
+The general idea is that releases should be cryptographically signed
before they are made publicly available.
@menu
* Automated Upload Registration::
* Automated Upload Procedure::
+* FTP Upload Release File Triplet::
+* FTP Upload Directive File::
+* FTP Upload Directory Trees::
+* FTP Upload File Replacement::
+* FTP Upload Standalone Directives::
* FTP Upload Directive File - v1.1::
* FTP Upload Directive File - v1.0::
@end menu
for your GNU package:
@enumerate
-
@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
@item
In the @samp{My Account Conf} page on @code{savannah}, upload the GPG
-key you will use to sign your packages. If you haven't created one
-before, you can do so with the command @code{gpg --gen-key} (you can
-accept all the default answers to its questions).
+key (in ASCII-armored format) that you will use to sign your packages.
+If you haven't created one before, you can do so with the command
+@code{gpg --gen-key} (you can accept and/or confirm the default
+answers to its questions). Then, to get the ASCII-armored version,
+run @samp{gpg --export --armor @var{your_key_id}}.
Optional but recommended: Send your key to a GPG public key server:
@code{gpg --keyserver keys.gnupg.net --send-keys @var{keyid}}, where
preferred email address, and your Savannah username.
@item
-An ASCII armored copy of your GPG key, as an attachment. (@samp{gpg
---export -a @var{your_key_id} >mykey.asc} should give you this.)
+The ASCII armored copy of your GPG key, as an attachment.
@item
A list of names and preferred email addresses of other individuals you
The upload system will email receipts to the given email addresses
when an upload is made, either successfully or unsuccessfully.
+Should you later have to update your GPG key, you'll have to re-submit
+it to both Savannah and @email{ftp-upload@@gnu.org}, as these systems
+are not connected.
+
@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 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
-uploaded via ftp to the host @code{ftp-upload.gnu.org}.
+section, you can and should do ftp uploads for your package. There
+are two basic kinds of uploads (details in the following sections):
@enumerate
@item
-The file to be distributed; for example, @file{foo.tar.gz}.
+Three related files (a ``triplet'') to upload a file destined for
+@code{ftp.gnu.org} or @code{alpha.gnu.org}: @pxref{FTP Upload Release
+File Triplet}.
@item
-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}; 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.
+A single (signed) standalone ``directive file'' to perform operations
+on the server: @pxref{FTP Upload Standalone Directives}.
@end enumerate
-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
-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
-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.
+In either case, you upload the file(s) via anonymous ftp to the host
+@code{ftp-upload.gnu.org}. If the upload is destined for
+@code{ftp.gnu.org}, place the file(s) in the directory
+@file{/incoming/ftp}. If the upload is destined for
+@code{alpha.gnu.org}, place the file(s) in the directory
+@file{/incoming/alpha}.
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. Uploaded
-files that belong to an incomplete triplet are deleted automatically
-after 24 hours.
+properly, so do not worry about the timing of your upload. Spurious
+and stale uploaded files are deleted automatically after 24 hours.
-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.
+Your designated upload email addresses (@pxref{Automated Upload
+Registration}) are sent a message if there are problems processing an
+upload for your package. You also receive a message when an upload
+has been successfully processed.
-One automated way to create and transfer the necessary files is to use
-the @code{gnupload} script, which is available from the
+One programmatic 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.
+@url{http://savannah.gnu.org/projects/gnulib}. Run
+@code{gnupload@tie{}--help} for a description and examples. (With
+@code{gnupload}, you specify a destination such as
+@samp{ftp.gnu.org:}@var{pkgname} rather than using the
+@samp{ftp-upload} hostname.)
-@code{gnupload} uses the @code{ncftpput} program to do the actual
+@code{gnupload} invokes the program @code{ncftpput} 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}.
+directory of @code{gnulib} can serve as a replacement. It uses the
+plain command line @code{ftp} program.
If you have difficulties with an upload, email
@email{ftp-upload@@gnu.org}. You can check the archive of uploads
@url{https://lists.gnu.org/archive/html/ftp-upload-report}.
-@node FTP Upload Directive File - v1.1
-@subsection FTP Upload Directive File - v1.1
+@node FTP Upload Release File Triplet
+@subsection FTP Upload Release File Triplet
-The directive file name must end in @file{directive.asc}.
+@cindex FTP uploads, of release files
-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.
+Ordinarily, the goal is to upload a new release of your package, let's
+say, the source archive @file{foo-1.0.tar.gz}. To do this, you
+simultaneously upload three files:
-The @code{version} directive must always have the value @samp{1.1}.
+@enumerate
+@item
+The file to be distributed; in our example, @file{foo-1.0.tar.gz}.
-The @code{directory} directive specifies the final destination
-directory where the uploaded file and its @file{.sig} companion are to
-be placed.
+@item
+Detached GPG binary signature file for (1); for example,
+@file{foo-1.0.tar.gz.sig}. Make this with @samp{gpg -b foo-1.0.tar.gz}.
-The @code{filename} directive must contain the name of the file to be
-distributed (item@tie{}(1) above).
+@item
+A clearsigned @dfn{directive file}; for example,
+@file{foo-1.0.tar.gz.directive.asc}, created with @samp{gpg
+--clearsign foo-1.0.tar.gz.directive}. Its contents are described in
+the next section.
+@end enumerate
+
+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}.
+
+
+@node FTP Upload Directive File
+@subsection FTP Upload Directive File
+
+@cindex directive file, for FTP uploads
+
+To repeat, a (signed) @dfn{directive file} must be part of every
+upload. The unsigned original is just a plain text file you can
+create with any text editor. Its name must be, e.g.,
+@file{foo-1.0.tar.gz.directive} for accompanying an upload of
+@file{foo-1.0.tar.gz}.
+
+After creating the file, run @samp{gpg --clearsign
+foo-1.0.tar.gz.directive}, which will create
+@file{foo-1.0.tar.gz.directive.asc}; this is the file to be uploaded.
+
+When part of a triplet for uploading a release file, the directive
+file must always contain the directives @code{version},
+@code{filename} and @code{directory}. In addition, a @code{comment}
+directive is optional. These directives can be given in any order.
+
+Continuing our example of uploading @file{foo-1.0.tar.gz} for a
+package named @code{foo} to @code{ftp.gnu.org}, the values would be as
+follows:
+
+@table @code
+@item version
+must be the value @samp{1.2} (the current version, as of May@tie{}2012):@*
+@t{version: 1.2}
+
+@item filename
+must be the name of the file to be distributed:@*
+@t{filename: foo-1.0.tar.gz}
+
+@item directory
+specifies the final destination directory where the uploaded file and
+its @file{.sig} companion are to be placed. Here we will put our file
+in the top level directory of the package, as is the most common
+practice:@*
+@t{directory: foo}
-For example, as part of an uploaded triplet, a
-@file{foo.tar.gz.directive.asc} file might contain these lines (before
-being gpg clearsigned):
+@item comment
+is optional, and ignored if present:@*
+@t{comment: let's hope this works!}
+@end table
+
+Putting all of the above together, the complete contents of the
+directive file @file{foo-1.0.tar.gz.directive} for our example would
+be:
@example
-version: 1.1
-directory: bar/v1
-filename: foo.tar.gz
-comment: hello world!
+version: 1.2
+directory: foo
+filename: foo-1.0.tar.gz
+comment: let's hope this works!
@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.
+Then you @samp{gpg --clearsign} the file as given above, and upload
+(using anonymous ftp) the three files:
-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}).
+@table @file
+@item foo-1.0.tar.gz
+@item foo-1.0.tar.gz.sig
+@item foo-1.0.tar.gz.directive.asc
+@end table
-If you upload a file that already exists in the FTP directory, the
-original will simply be archived and replaced with the new upload.
+@noindent to the host @file{ftp-upload.gnu.org}, directory
+@file{/incoming/ftp} (for official releases), or the directory
+@file{/incoming/alpha} (for test releases).
-@subheading Standalone directives
+After the system authenticates the signatures, the files
+@file{foo-1.0.tar.gz} and @file{foo-1.0.tar.gz.sig} are placed in
+the directory @file{gnu/foo/} on @code{ftp.gnu.org}. That is, we'll
+have made our release available at
+@indicateurl{http://ftp.gnu.org/gnu/foo/foo-1.0.tar.gz} (and then from
+our many mirrors via
+@indicateurl{http://ftpmirror.gnu.org/foo/foo-1.0.tar.gz}). Whew.
-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 remains optional.
+A common reason for the upload not succeeding is your GPG signature
+not being registered with the upload system. There is nothing that
+makes this happen automatically. You must email the system
+administrators as described above (@pxref{Automated Upload
+Registration}).
-If you use more than one directive, the directives are executed in the
-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.)
+@node FTP Upload Directory Trees
+@subsection FTP Upload Directory Trees
+
+@cindex directory trees, in ftp uploads
+@cindex hierarchy, under ftp upload directory
+@cindex uploads, directory trees in
+
+You can make any directory hierarchy you like under your package
+directory. The system automatically creates any intermediate
+directories you specify in the @code{directory} directive.
-Here are a few examples. The first removes a symlink:
+Slightly modifying the example above, the following directive file:
@example
-version: 1.1
-directory: bar/v1
-rmsymlink: foo-latest.tgz
-comment: remove a symlink
+version: 1.2
+directory: foo/foo-1.0
+filename: foo-1.0.tar.gz
+comment: creates per-version subdirectory as needed
@end example
@noindent
-Archive an old file, taking it offline:
+would put the tar file in the @file{foo-1.0/} subdirectory of the
+package @code{foo}, thus ending up at
+@indicateurl{ftp.gnu.org:gnu/foo/foo-1.0/foo-1.0.tar.gz}.
+
+However, to keep things simpler for users, we recommend not using
+subdirectories, unless perhaps each release of your package consists
+of many separate files.
+
+
+@node FTP Upload File Replacement
+@subsection FTP Upload File Replacement
+
+@cindex replacing uploaded files
+@cindex uploads, replacing
+
+You can replace existing files that have already been uploaded by
+including a directive line @code{replace:@tie{}true}. For example,
+you might like to provide a README file in the release directory and
+update it from time to time. The full directive file for that would
+look like this:
@example
-version: 1.1
-directory: bar/v1
-archive: foo-1.1.tar.gz
-comment: archive an old file; it will not be
-comment: available through FTP any more.
+replace: true
+version: 1.2
+directory: foo
+filename: README
+comment: replaces an existing README
@end example
-@noindent
-Archive an old directory (with all contents), taking it offline:
+It is ok if the file to be replaced doesn't already exist; then the
+new file is simply added, i.e., the @file{replace} directive has no
+effect.
+
+When an existing file is replaced, the original is archived to a
+private location. There is no automated or public access to such
+archived files; if you want to retrieve or view them, please email
+@email{sysadmin@@fsf.org}.
+
+We very strongly discourage replacing an actual software release file,
+such as @file{foo-1.0.tar.gz}. Releases should be unique, and
+forever. If you need to make fixes, make another release. If you
+have an exigent reason for a particular release file to no longer be
+available, it can be explicitly archived, as described in the next
+section.
+
+If you want to make the current release available under a generic
+name, such as @code{foo-latest.tar.gz}, that is better done with
+symlinks, also as described in the next section.
+
+
+@node FTP Upload Standalone Directives
+@subsection FTP Upload Standalone Directives
+
+@cindex standalone directives, for ftp uploads
+@cindex directives for ftp uploads, standalone
+
+The previous sections describe how to upload a file to be publicly
+released. It's also possible to upload a directive file by itself to
+perform a few operations on the upload directory. The supported
+directives are:
+
+@table @code
+@item symlink
+creates a symlink.
+
+@item rmsymlink
+removes a symlink.
+
+@item archive
+takes a file or directory offline.
+@end table
+
+As for the directives described above, the @code{directory} and
+@code{version} directives are still required, the @code{comment}
+directive remains optional, and the @code{filename} directive is not
+allowed.
+
+When uploaded by itself, the name of the directive file is not
+important. But it must be still be signed, using @samp{gpg
+--clearsign}; the resulting @file{.asc} file is what should be
+uploaded.
+
+Here's an example of the full directive file to create a
+@file{foo-latest.tar.gz} symlink:
@example
-version: 1.1
-directory: bar/v1
-archive: foo
-comment: archive an old directory; it and its entire
-comment: contents will not be available through FTP anymore
+version: 1.2
+directory: foo
+symlink: foo-1.1.tar.gz foo-latest.tar.gz
+comment: create a symlink
@end example
-@noindent
-Create a new symlink:
+If you include more than one directive in a standalone upload, the
+directives are executed in the 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. On the other hand, 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 replaced.)
+
+Here's an example of removing a symlink, e.g., if you decide not to
+maintain a @file{foo-latest} link any more:
@example
-version: 1.1
-directory: bar/v1
-symlink: foo-1.2.tar.gz foo-latest.tgz
-comment: create a new symlink
+version: 1.2
+directory: foo
+rmsymlink: foo-latest.tar.gz
+comment: remove a symlink
@end example
@noindent
-Do everything at once:
+And here's an example of archiving a file, e.g., an unintended upload:
@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
+version: 1.2
+directory: foo
+archive: foo-1.1x.tar.gz
+comment: archive an old file; it will not be
+comment: publicly available any more.
@end example
+The @code{archive} directive causes the specified items to become
+inaccessible. This should only be used when it is actively bad for
+them to be available, e.g., you uploaded something by mistake.
+
+If all you want to do is reduce how much stuff is in your release
+directory, an alternative is to email @email{sysadmin@@fsf.org} and
+ask them to move old items to the @file{http://ftp.gnu.org/old-gnu/}
+directory; then they will still be available. In general, however, we
+recommend leaving all official releases in the main release directory.
+
+
+@node FTP Upload Directive File - v1.1
+@subsection FTP Upload Directive File - v1.1
+
+The v1.1 protocol for uploads lacked the @code{replace} directive;
+instead, file replacements were done automatically and silently
+(clearly undesirable). This is the only difference between v1.2 and
+v1.1.
+
@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.}
+Support for v1.0 uploads was discontinued in May 2012; please upgrade
+to@tie{}v1.2.
-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) are to be placed.
+In v1.0, the directive file contained one line, excluding the
+clearsigned data GPG that inserts, which specifies the final
+destination directory where items (1) and (2) are to be placed.
-For example, the @file{foo.tar.gz.directive.asc} file might contain the
+For example, the @file{foo-1.0.tar.gz.directive.asc} file might contain the
single line:
@example
directory: bar/v1
@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 were to
+This directory line indicates that @file{foo-1.0.tar.gz} and
+@file{foo-1.0.tar.gz.sig} are part of package @code{bar}. If you were to
upload the triplet to @file{/incoming/ftp}, and the system can
positively authenticate the signatures, then the files
-@file{foo.tar.gz} and @file{foo.tar.gz.sig} will be placed in the
+@file{foo-1.0.tar.gz} and @file{foo-1.0.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
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
+@url{http://planet.gnu.org} (GNU Planet), unless the text of the entry
+contains the string @samp{::noplanet::}. 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{package}@@gnu.org}) for announcements as well if you
+@indicateurl{info-@var{package}@@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.)
@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
+@indicateurl{http://ftpmirror.gnu.org/@var{package/}} will automatically
redirect to a nearby mirror.
@item
the present release.
@end itemize
+You may find the @file{announce-gen} script useful for creating
+announcements, which is available from the @file{build-aux/} directory
+of the @code{gnulib} project at
+@url{http://savannah.gnu.org/projects/gnulib}.
+
@node Web Pages
@chapter Web Pages
@node Hosting for Web Pages
@section Hosting for Web Pages
+@cindex web pages, hosting for
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
@node Freedom for Web Pages
@section Freedom for Web Pages
+@cindex web pages, freedom for
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
@node Manuals on Web Pages
@section Manuals on Web Pages
+@cindex web pages, including manuals on
+@cindex formats for documentation, desired
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.
+DVI, Info, PDF, plain ASCII, and the source Texinfo. All of these can
+be generated automatically from Texinfo using Makeinfo and other
+programs. If the Texinfo itself is generated from some other source
+format, include that too.
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
@subsection Invoking @command{gendocs.sh}
@pindex gendocs.sh
@cindex generating documentation output
+@cindex documentation output, generating
The script @command{gendocs.sh} eases the task of generating the
Texinfo documentation output for your web pages
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.:
+By default, the script uses @command{makeinfo} for generating HTML
+output. If you prefer to use @command{texi2html}, use the
+@option{--texi2html} command line option, e.g.:
@smallexample
gendocs --texi2html -o texinfo texinfo "GNU Texinfo manual"
and chapters).
You can set the environment variables @env{MAKEINFO}, @env{TEXI2DVI},
-@env{TEXI2HTML} and @env{DVIPS} to control the programs that get
-executed, and @env{GENDOCS_TEMPLATE_DIR} to control where the
+etc., to control the programs that get 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}.
+correspondence about @command{gendocs} to @email{bug-texinfo@@gnu.org}.
@node CVS Keywords in Web Pages
serious about the need for free documentation, we must not contradict
our position by recommending use of documentation that isn't free.
+Please don't host discussions about your package in a service that
+requires nonfree software. For instance, Google+ ``communities''
+require running a nonfree JavaScript program to post a message, so
+they can't be used in the Free World. To host discussions there would
+be excluding people who live by free software principles.
+
+Of course, you can't order people not to use such services to talk
+with each other. What you can do is not legitimize them, and use your
+influence to lead people away from them. For instance, where you say
+where to have discussions related to the program, don't list such a
+place.
+
Finally, new issues concerning the ethics of software freedom come up
frequently. We ask that GNU maintainers, at least on matters that
pertain specifically to their package, stand with the rest of the GNU
Note that this uses a space, not a slash.
+@node Interviews and Speeches
+@chapter Interviews and Speeches
+
+Interviews and speeches about your package are an important channel
+for informing the public about the GNU system and the ideas of the
+free software movement. Please avoid saying ``open source'' and avoid
+calling the GNU system ``Linux'', just as you would in the package
+itself (@pxref{Terminology}). Likewise, avoid promoting nonfree
+programs (@pxref{References,,, standards, GNU Coding
+Standards}) as you would in the package itself.
+
+Many GNU users have erroneous ideas about GNU. Outside of our
+community, most people think it is Linux. Please use your opportunity
+to set them straight. Start the presentation with the answers to
+these basic questions:
+
+@itemize @bullet
+@item
+What GNU is (an operating system developed to be Unix-like and totally
+free software). It is good to mention @url{http://www.gnu.org}.
+
+@item
+What free software is (the users control it, so it doesn't control
+them). It is good to state the four freedoms and/or refer to
+@url{http://www.gnu.org/philosophy/free-sw.html}.
+
+@item
+What GNU/Linux is (Linux filled the last gap in GNU). It is useful to
+refer to @url{http://www.gnu.org/gnu/linux-and-gnu.html}.
+
+@item
+What the GNU Project is (the project to develop GNU).
+
+@item
+How your package fits in (it's part of GNU, and the work is part of
+the GNU Project).
+@end itemize
+
+If you feel a social pressure not to say these things, you may be
+coming in contact with some who would prefer that these things not be
+said. That's precisely when we need your support most.
+
+Please don't include advertisements or plugs for any company, product
+or service. Even if the product would meet the standards for the FSF
+to endorse it, an ad for it is out of place in a presentation about a
+GNU package. Likewise, please don't include company slogans. Mention
+a company only when called for by the subject matter.
+
+A few GNU packages are actually business activities of a particular
+company. In that case, it is ok to say so at the start. Otherwise,
+please show that this is a project of the GNU Project, and avoid
+suggesting it is any company's project.
+
+If you are paid by a company to work on the GNU package, it is
+appropriate to thank the company in a discreet way, but please don't
+go beyond that.
+
+Before you do a speech or interview, please contact the GNU Project
+leadership. We can give you advice on how to deal with various
+eventualities.
+
+When your interviews and speech recordings or transcript are posted,
+please tell us about them. Then we can publicize them.
+
+Please post them in formats that are friendly to free software: not in
+Doc or Docx format, not with Flash, not with QuickTime, not with MP3,
+MPEG2 or MPEG4. Plain text, HTML and PDF are good.
+
@node Hosting
@chapter Hosting
@cindex CVS repository
We don't recommend any specific payment service. However, GNU
developers should not use a service that requires them to sign a
proprietary software license, such as Google's payment service.
+Please also avoid sites that requires users to run nonfree software in
+order to donate. (This includes JavaScript software, so try it with
+LibreJS or with JavaScript disabled.)
+
+In the text you post on the site, please pay attention to the
+terminological issues we care about (@pxref{Terminology}).
+
+We have no objections to using Bitcoin to receive donations.
+
+The FSF can collect donations for a limited number of projects; if you
+want to propose that for your project, write to
+@email{maintainers@@gnu.org}. The FSF is required to supervise the
+spending of these funds.
-Of course, it is also good to encourage people to join or contribute
-to the FSF (@url{http://www.fsf.org}), either instead of or as well as
-package-specific donations.
+Of course, it is also good to encourage people to join the FSF
+(@url{http://www.fsf.org}) or make a general donation, either instead
+of or as well as package-specific donations.
@node Free Software Directory
projects / gnulib.git / blobdiff