@c For double-sided printing, uncomment:
@c @setchapternewpage odd
@c This date is automagically updated when you save this file:
-@set lastupdate October 12, 2011
+@set lastupdate November 15, 2012
@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 Free Software Foundation, Inc.
+2010, 2011, 2012 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@menu
* Preface::
* Getting Help::
-* Getting a GNU Account::
+* GNU Accounts and Resources::
* Stepping Down::
* Recruiting Developers::
* Legal Matters::
* Web Pages::
* Ethical and Philosophical Consideration::
* Terminology::
+* Interviews and Speeches::
* Hosting::
* Donations::
* Free Software Directory::
try not to burden them unnecessarily.
-@node Getting a GNU Account
-@chapter Getting a GNU Account
+@node GNU Accounts and Resources
+@chapter GNU Accounts and Resources
@cindex shell account, on fencepost
-@cindex @code{fencepost.gnu.org} GNU machine
+@cindex @code{fencepost.gnu.org} GNU login host
+@cindex resources for GNU developers
+@cindex development resources
@c We want to repeat this text later, so define a macro.
@macro gdgnuorgtext
@gdgnuorgtext{}
+Other resources available to GNU maintainers are described at
+@url{http://www.gnu.org/software/devel.html}, as well as throughout
+this document. In brief:
+
+@itemize @bullet
+@item Login accounts (see above).
+
+@item Version control (@pxref{Old Versions}).
+
+@item Mailing lists (@pxref{Mail}).
+
+@item Web pages (@pxref{Web Pages}).
+
+@item Mirrored release areas (@pxref{Distributions}).
+
+@cindex Hydra
+@cindex @code{platform-testers} mailing list
+@item Pre-release portability testing, both automated (via Hydra) and
+on request (via volunteers).
+
+@end itemize
+
@node Stepping Down
@chapter Stepping Down
@node Copyright Papers
@section Copyright Papers
@cindex copyright papers
+@cindex assignments, copyright
+@cindex disclaimers
If you maintain an FSF-copyrighted package
certain legal procedures are required when incorporating legally significant
@strong{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 you still get no response after an
+additional week, please write to @email{maintainers@@gnu.org} about it.
+
+After receiving the necessary form, all contributors then print it and
+sign it. Contributors located in the USA or Germany can then email or
+fax a scanned copy back to the FSF (or 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
automatically, if you are careful about the formatting of the change
log entries.
+It is ok to include other email addresses, names, and program
+information in @file{AUTHORS}, such as bug-reporting information.
+@xref{Standard Mailing Lists}.
+
+
@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
@url{http://www.gnu.org/licenses/fdl-howto.html} for more advice about
how to use the GNU FDL.
+If you write a manual that people might want to buy on paper, please
+write to @email{maintainers@@gnu.org} to tell the FSF about it. We
+might want to publish it.
+
If the manual is over 400 pages, or if the FSF thinks it might be a
good choice for publishing on paper, then please include the GNU GPL,
as in the notice above. Please also include our standard invariant
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
+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
+incompatble with GPL version 3. ``GPL version 3 only'' and ``GPL
+version 2 or 3 only'' have a subtler problem: they will be incompatble
+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 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
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
advertised bug-reporting email address should always be
@samp{bug-@var{package}@@gnu.org}, to help show users that the program
is a GNU package, but it is ok to set up that list to forward to another
-site if you prefer. The package distribution should state the
-name of the bug-reporting list in a prominent place, and ask users to
-help us by reporting bugs there.
+site if you prefer.
@cindex @email{bug-gnu-utils@@gnu.org}
We also have a catch-all list, @email{bug-gnu-utils@@gnu.org}, which is
@samp{info-@var{package}} for announcements (@pxref{Announcements}).
Any other mailing lists you find useful can also be created.
+The package distribution should state the name of all the package's
+mailing lists in a prominent place, and ask users to help us by
+reporting bugs appropriately. The top-level @file{README} file and/or
+@file{AUTHORS} file are good places. Mailing list information should
+also be included in the manual and the package web pages (@pxref{Web
+Pages}).
+
+
@node Creating Mailing Lists
@section Creating Mailing Lists
To create and maintain simple aliases and unmanaged lists, you can
edit @file{/com/mailer/aliases} on the main GNU server. If you don't
have an account there, please read
-@url{http://www.gnu.org/software/README.accounts.html} (@pxref{Getting
-a GNU Account}).
+@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
@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 Directive File - v1.2::
* 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
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).
+accept and/or confirm the default answers to its questions).
Optional but recommended: Send your key to a GPG public key server:
@code{gpg --keyserver keys.gnupg.net --send-keys @var{keyid}}, where
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
+Since v1.1 of the upload directives, 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.
@url{https://lists.gnu.org/archive/html/ftp-upload-report}.
+@node FTP Upload Directive File - v1.2
+@subsection FTP Upload Directive File - v1.2
+
+All the directives and documentation for v1.1 of the protocol still
+apply. @xref{FTP Upload Directive File - v1.1}, for more information.
+
+@subheading New directive @code{replace}
+
+@cindex replacing uploaded files
+@cindex uploads, replacing
+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.2
+directory: bar/v1
+filename: foo.tar.gz
+comment: hello world!
+@end example
+
+If @file{foo.tar.gz} exists prior to upload, this directive file will
+result in an error. Prior to May 2012, the behavior (of v1.1) was
+different: any existing files were automatically archived and replaced
+with the new upload. Since May 2012, no files are replaced unless the
+(new) @code{replace} directive is set to @code{true} in the directive
+file. That directive requires version 1.2 of the protocol. For
+example:
+
+@example
+version: 1.2
+directory: bar/v1
+filename: foo.tar.gz
+replace: true
+comment: hello world!
+@end example
+
+
@node FTP Upload Directive File - v1.1
@subsection FTP Upload Directive File - v1.1
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.
+described. In addition, a @code{comment} directive is allowed.
The @code{version} directive must always have the value @samp{1.1}.
@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}).
+directory trees, as long as they are under the directory for your
+package (in the example above, the package directory 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.
+There is no automated or online access to archived files; if you want
+to retrieve or view them, please email sysadmin.
@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}
+When uploaded by itself, a 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.
@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 phased out 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
@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
@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
terminology and its reasons, you can refer to the URL
@url{http://www.gnu.org/gnu/linux-and-gnu.html}.
+To make it clear that Linux is a kernel, not an operating system,
+please take care to avoid using the term ``Linux system'' in those
+materials. If you want to have occasion to make a statement about
+systems in which the kernel is Linux, write ``systems in which the
+kernel is Linux'' or ``systems with Linux as the kernel.'' That
+explicitly contrasts the system and the kernel, and will help readers
+understand the difference between the two. Please avoid simplified
+forms such as ``Linux-based systems'' because those fail to highlight
+the difference between the kernel and the system, and could encourage
+readers to overlook the distinction.
+
To contrast the GNU system properly with respect to GNU/Linux, you can
call it ``GNU/Hurd'' or ``the GNU/Hurd system''. However, when that
contrast is not specifically the focus, please call it just ``GNU'' or
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
projects / gnulib.git / blobdiff