diff options
Diffstat (limited to 'gnulib/doc/maintain.texi')
| m--------- | gnulib | 0 | ||||
| -rw-r--r-- | gnulib/doc/maintain.texi | 2319 |
2 files changed, 2319 insertions, 0 deletions
diff --git a/gnulib b/gnulib deleted file mode 160000 -Subproject 443bc5ffcf7429e557f4a371b0661abe98ddbc1 diff --git a/gnulib/doc/maintain.texi b/gnulib/doc/maintain.texi new file mode 100644 index 0000000..40e37ba --- /dev/null +++ b/gnulib/doc/maintain.texi @@ -0,0 +1,2319 @@ +\input texinfo.tex @c -*-texinfo-*- +@c %**start of header +@setfilename maintain.info +@settitle Information for Maintainers of GNU Software +@c For double-sided printing, uncomment: +@c @setchapternewpage odd +@c This date is automagically updated when you save this file: +@set lastupdate December 2, 2011 +@c %**end of header + +@dircategory GNU organization +@direntry +* Maintaining: (maintain). Maintaining GNU software. +@end direntry + +@setchapternewpage off + +@c Put everything in one index (arbitrarily chosen to be the concept index). +@syncodeindex fn cp +@syncodeindex pg cp + +@copying +Information for maintainers of GNU software, last updated @value{lastupdate}. + +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. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled +``GNU Free Documentation License''. +@end quotation +@end copying + +@titlepage +@title Information for Maintainers of GNU Software +@author Richard Stallman +@author last updated @value{lastupdate} +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + +@ifnottex +@node Top +@top Version + +@insertcopying +@end ifnottex + +@menu +* Preface:: +* Getting Help:: +* Getting a GNU Account:: +* Stepping Down:: +* Recruiting Developers:: +* Legal Matters:: +* Clean Ups:: +* Platforms:: +* Mail:: +* Old Versions:: +* Distributions:: +* Web Pages:: +* Ethical and Philosophical Consideration:: +* Terminology:: +* Hosting:: +* Donations:: +* Free Software Directory:: +* Using the Proofreaders List:: +* GNU Free Documentation License:: +* Index:: +@end menu + + +@node Preface +@chapter About This Document + +This file contains guidelines and advice for someone who is the +maintainer of a GNU program on behalf of the GNU Project. Everyone is +entitled to change and redistribute GNU software; you need not pay +attention to this file to get permission. But if you want to maintain +a version for widespread distribution, we suggest you follow these +guidelines. If you are or would like to be a GNU maintainer, then it +is essential to follow these guidelines. + +In addition to this document, please read and follow the GNU Coding +Standards (@pxref{Top, , Contents, standards, GNU Coding Standards}). + +@cindex @code{bug-standards@@gnu.org} email address +@cindex Savannah repository for @code{gnustandards} +@cindex @code{gnustandards} project repository +Please send corrections or suggestions for this document to +@email{bug-standards@@gnu.org}. If you make a suggestion, please +include suggested new wording if you can. We prefer a context diff to +the Texinfo source, but if that's difficult for you, you can make a +diff for some other version of this document, or propose it in any way +that makes it clear. The source repository for this document can be +found at @url{http://savannah.gnu.org/projects/gnustandards}. + +@cindex @code{gnustandards-commit@@gnu.org} mailing list +If you want to receive diffs for every change to these GNU documents, +join the mailing list @code{gnustandards-commit@@gnu.org}, for +instance via the web interface at +@url{http://lists.gnu.org/mailman/listinfo/gnustandards-commit}. +Archives are also available there. + +@cindex Piercy, Marge +This document uses the gender-neutral third-person pronouns ``person'', +``per'', ``pers'' and ``perself'' which were promoted, and perhaps +invented, by Marge Piercy in @cite{Woman on the Edge of Time}. They are +used just like ``she'', ``her'', ``hers'' and ``herself'', except that +they apply equally to males and females. For example, ``Person placed +per new program under the GNU GPL, to let the public benefit from per +work, and to enable per to feel person has done the right thing.'' + +This release of the GNU Maintainer Information was last updated +@value{lastupdate}. + + +@node Getting Help +@chapter Getting Help +@cindex help, getting + +@cindex @code{mentors@@gnu.org} mailing list +If you have any general questions or encounter a situation where it +isn't clear how to get something done or who to ask, you (as a GNU +contributor) can always write to @email{mentors@@gnu.org}, which is a +list of a few experienced GNU folks who have volunteered to answer +questions. Any GNU-related question is fair game for the +@code{mentors} list. + +@cindex advisory committee +The GNU Advisory Committee helps to coordinate activities in the GNU +project on behalf of RMS (Richard Stallman, the Chief GNUisance). If +you have any organizational questions or concerns you can contact the +committee at @email{gnu-advisory@@gnu.org}. See +@url{http://www.gnu.org/contact/gnu-advisory.html} for the current +committee members. Additional information is in +@file{/gd/gnuorg/advisory}. + +@cindex down, when GNU machines are +@cindex outage, of GNU machines +@cindex @url{http://identi.ca/group/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 +it can be alleviated at the FSF end, is already being worked on. + +@cindex sysadmin, FSF +@cindex FSF system administrators +@cindex GNU system administrators +The FSF system administrators are responsible for the network and GNU +hardware. You can email them at @email{sysadmin@@fsf.org}, but please +try not to burden them unnecessarily. + + +@node Getting a GNU Account +@chapter Getting a GNU Account +@cindex shell account, on fencepost +@cindex @code{fencepost.gnu.org} GNU machine + +@c We want to repeat this text later, so define a macro. +@macro gdgnuorgtext +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, +@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. +@end macro + +@gdgnuorgtext{} + + +@node Stepping Down +@chapter Stepping Down +@cindex stepping down as maintainer +@cindex resigning as maintainer + +With good fortune, you will continue maintaining your package for many +decades. But sometimes for various reasons maintainers decide to step +down. + +If you're the official maintainer of a GNU package and you decide to +step down, please inform the GNU Project (@email{maintainers@@gnu.org}). +We need to know that the package no longer has a maintainer, so we can +look for and appoint a new maintainer. + +@cindex @email{maintainers@@gnu.org} +If you have an idea for who should take over, please tell +@email{maintainers@@gnu.org} your suggestion. The appointment of a new +maintainer needs the GNU Project's confirmation, but your judgment that +a person is capable of doing the job will carry a lot of weight. + +As your final act as maintainer, it would be helpful to set up or +update the package under @code{savannah.gnu.org} (@pxref{Old +Versions}). This will make it much easier for the new maintainer to +pick up where you left off and will ensure that the source tree is not +misplaced if it takes us a while to find a new maintainer. + + +@node Recruiting Developers +@chapter Recruiting Developers + +Unless your package is a fairly small, you probably won't do all the +work on it yourself. Most maintainers recruit other developers to help. + +Sometimes people will offer to help. Some of them will be capable, +while others will not. It's up to you to determine who provides useful +help, and encourage those people to participate more. + +Some of the people who offer to help will support the GNU Project, while +others may be interested for other reasons. Some will support the goals +of the Free Software Movement, but some may not. They are all welcome +to help with the work---we don't ask people's views or motivations +before they contribute to GNU packages. + +As a consequence, you cannot expect all contributors to support the GNU +Project, or to have a concern for its policies and standards. So part +of your job as maintainer is to exercise your authority on these points +when they arise. No matter how much of the work other people do, you +are in charge of what goes in the release. When a crucial point arises, +you should calmly state your decision and stick to it. + +Sometimes a package has several co-maintainers who share the role of +maintainer. Unlike developers who help, co-maintainers have actually +been appointed jointly as the maintainers of the package, and they carry +out the maintainer's functions together. If you would like to propose +some of your developers as co-maintainers, please contact +@email{maintainers@@gnu.org}. + +We're happy to acknowledge all major contributors to GNU packages on +the @url{http://www.gnu.org/people/people.html} web page. Please send +an entry for yourself to @email{webmasters@@gnu.org}, and feel free to +suggest it to other significant developers on your package. + + +@node Legal Matters +@chapter Legal Matters +@cindex legal matters + +This chapter describes procedures you should follow for legal reasons +as you maintain the program, to avoid legal difficulties. + +@menu +* Copyright Papers:: +* Legally Significant:: +* Recording Contributors:: +* Copying from Other Packages:: +* Copyright Notices:: +* License Notices:: +* External Libraries:: +@end menu + +@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 +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. + +@cindex data base of GNU copyright assignments +To check whether papers have been received, look in +@file{/gd/gnuorg/copyright.list}. If you can't look there directly, +@email{fsf-records@@gnu.org} can check for you. Our clerk can also +check for papers that are waiting to be entered and inform you when +expected papers arrive. + +@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. +@gdgnuorgtext{} + +In order for the contributor to know person should sign papers, you need +to ask per for the necessary papers. If you don't know per well, and you +don't know that person is used to our ways of handling copyright papers, +then it might be a good idea to raise the subject with a message like +this: + +@quotation +Would you be willing to assign the copyright to the Free Software +Foundation, so that we could install it in @var{package}? +@end quotation + +@noindent +or + +@quotation +Would you be willing to sign a copyright disclaimer to put this change +in the public domain, so that we can install it in @var{package}? +@end quotation + +If the contributor then wants more information, you can send per the file +@file{/gd/gnuorg/conditions.text}, which explains per options (assign +vs.@: disclaim) and their consequences. + +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/}; 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 +sure to get the current version of the template you will use! We change +these templates occasionally---don't keep using an old version. + +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} and in +@code{gnulib}.) + +For medium to small changes, request a personal disclaimer by sending +per the file @file{request-disclaim.changes}. + +If the contributor is likely to keep making changes, person might want +to sign an assignment for all per future changes to the program. So it +is useful to offer per that alternative. If person wants to do it that +way, send per the @file{request-assign.future}. + +When you send a @file{request-} file, you don't need to fill in anything +before sending it. Just send the file verbatim to the contributor. The +file gives per instructions for how to ask the FSF to mail per the +papers to sign. The @file{request-} file also raises the issue of +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.) + +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 +of the program in these templates, where it says @samp{NAME OF PERSON} +and @samp{NAME OF PROGRAM}, before sending; otherwise person might +sign without noticing them, and the papers would be useless. Note +that in some templates there is more than one place to put the name of +the program or the name of the person; be sure to change all of them. +All the templates raise the issue of an employer's disclaimer as well. + +@cindex legal papers for changes in manuals +You do not need to ask for separate papers for a manual that is +distributed only in the software package it describes. But if we +sometimes distribute the manual separately (for instance, if we publish +it as a book), then we need separate legal papers for changes in the +manual. For smaller changes, use +@file{disclaim.changes.manual}; for larger ones, use +@file{assign.changes.manual}. To cover both past and future +changes to a manual, you can use @file{assign.future.manual}. +For a translation of a manual, use @file{assign.translation.manual}. + +For translations of program strings (as used by GNU Gettext, for +example; @pxref{Internationalization,,, standards, GNU Coding +Standards}), use @file{disclaim.translation}. If you make use of the +Translation Project (@url{http://translationproject.org}) facilities, +please check with the TP coordinators that they have sent the +contributor the papers; if they haven't, then you should send the +papers. In any case, you should wait for the confirmation from the +FSF that the signed papers have been received and accepted before +integrating the new contributor's material, as usual. + +If a contributor is reluctant to sign an assignment for a large change, +and is willing to sign a disclaimer instead, that is acceptable, so you +should offer this alternative if it helps you reach agreement. We +prefer an assignment for a larger change, so that we can enforce the GNU +GPL for the new text, but a disclaimer is enough to let us use the text. + +If you maintain a collection of programs, occasionally someone will +contribute an entire separate program or manual that should be added to +the collection. Then you can use the files +@file{request-assign.program}, @file{disclaim.program}, +@file{assign.manual}, and @file{disclaim.manual}. We very much prefer +an assignment for a new separate program or manual, unless it is quite +small, but a disclaimer is acceptable if the contributor insists on +handling the matter that way. + +If a contributor wants the FSF to publish only a pseudonym, that is +ok. The contributor should say this, and state the desired pseudonym, +when answering the @file{request-} form. The actual legal papers will +use the real name, but the FSF will publish only the pseudonym. When +using one of the other forms, fill in the real name but ask the +contributor to discuss the use of a pseudonym with +@email{assign@@gnu.org} before sending back the signed form. + +@strong{Although there are other templates besides the ones listed here, +they are for special circumstances; please do not use them without +getting advice from @email{assign@@gnu.org}.} + +If you are not sure what to do, then please ask @email{assign@@gnu.org} for +advice; if the contributor asks you questions about the meaning and +consequences of the legal papers, and you don't know the answers, you +can forward them to @email{assign@@gnu.org} and we will answer. + +@strong{Please do not try changing the wording of a template yourself. +If you think a change is needed, please talk with @email{assign@@gnu.org}, +and we will work with a lawyer to decide what to do.} + +@node Legally Significant +@section Legally Significant Changes + +If a person contributes more than around 15 lines of code and/or text +that is legally significant for copyright purposes, we +need copyright papers for that contribution, as described above. + +A change of just a few lines (less than 15 or so) is not legally +significant for copyright. A regular series of repeated changes, such +as renaming a symbol, is not legally significant even if the symbol +has to be renamed in many places. Keep in mind, however, that a +series of minor changes by the same person can add up to a significant +contribution. What counts is the total contribution of the person; it +is irrelevant which parts of it were contributed when. + +Copyright does not cover ideas. If someone contributes ideas but no +text, these ideas may be morally significant as contributions, and +worth giving credit for, but they are not significant for copyright +purposes. Likewise, bug reports do not count for copyright purposes. + +When giving credit to people whose contributions are not legally +significant for copyright purposes, be careful to make that fact +clear. The credit should clearly say they did not contribute +significant code or text. + +When people's contributions are not legally significant because they +did not write code, do this by stating clearly what their contribution +was. For instance, you could write this: + +@example +/* + * Ideas by: + * Richard Mlynarik <mly@@adoc.xerox.com> (1997) + * Masatake Yamato <masata-y@@is.aist-nara.ac.jp> (1999) + */ +@end example + +@noindent +@code{Ideas by:} makes it clear that Mlynarik and Yamato here +contributed only ideas, not code. Without the @code{Ideas by:} note, +several years from now we would find it hard to be sure whether they +had contributed code, and we might have to track them down and ask +them. + +When you record a small patch in a change log file, first search for +previous changes by the same person, and see if per past +contributions, plus the new one, add up to something legally +significant. If so, you should get copyright papers for all per +changes before you install the new change. + +If that is not so, you can install the small patch. Write @samp{(tiny +change)} after the patch author's name, like this: + +@example +2002-11-04 Robert Fenk <Robert.Fenk@@gmx.de> (tiny change) +@end example + +@node Recording Contributors +@section Recording Contributors +@cindex recording contributors + +@strong{Keep correct records of which portions were written by whom.} +This is very important. These records should say which files or +parts of files were written by each person, and which files or +parts of files were revised by each person. This should include +installation scripts as well as manuals and documentation +files---everything. + +These records don't need to be as detailed as a change log. They +don't need to distinguish work done at different times, only different +people. They don't need describe changes in more detail than which +files or parts of a file were changed. And they don't need to say +anything about the function or purpose of a file or change---the +Register of Copyrights doesn't care what the text does, just who wrote +or contributed to which parts. + +The list should also mention if certain files distributed in the same +package are really a separate program. + +Only the contributions that are legally significant for copyright +purposes (@pxref{Legally Significant}) need to be listed. Small +contributions, bug reports, ideas, etc., can be omitted. + +For example, this would describe an early version of GAS: + +@display +Dean Elsner first version of all files except gdb-lines.c and m68k.c. +Jay Fenlason entire files gdb-lines.c and m68k.c, most of app.c, + plus extensive changes in messages.c, input-file.c, write.c + and revisions elsewhere. + +Note: GAS is distributed with the files obstack.c and obstack.h, but +they are considered a separate package, not part of GAS proper. +@end display + +@cindex @file{AUTHORS} file +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. + +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 + +When you copy legally significant code from another free software +package with a GPL-compatible license, you should look in the +package's records to find out the authors of the part you are copying, +and list them as the contributors of the code that you copied. If all +you did was copy it, not write it, then for copyright purposes you are +@emph{not} one of the contributors of @emph{this} code. + +Especially when code has been released into the public domain, authors +sometimes fail to write a license statement in each file. In this +case, please first be sure that all the authors of the code have +disclaimed copyright interest. Then, when copying the new files into +your project, add a brief note at the beginning of the files recording +the authors, the public domain status, and anything else relevant. + +On the other hand, when merging some public domain code into an +existing file covered by the GPL (or LGPL or other free software +license), there is no reason to indicate the pieces which are public +domain. The notice saying that the whole file is under the GPL (or +other license) is legally sufficient. + +Using code that is released under a GPL-compatible free license, +rather than being in the public domain, may require preserving +copyright notices or other steps. Of course, you should do what is +needed. + +If you are maintaining an FSF-copyrighted package, please verify we +have papers for the code you are copying, @emph{before} copying it. +If you are copying from another FSF-copyrighted package, then we +presumably have papers for that package's own code, but you must check +whether the code you are copying is part of an external library; if +that is the case, we don't have papers for it, so you should not copy +it. It can't hurt in any case to double-check with the developer of +that package. + +When you are copying code for which we do not already have papers, you +need to get papers for it. It may be difficult to get the papers if +the code was not written as a contribution to your package, but that +doesn't mean it is ok to do without them. If you cannot get papers +for the code, you can only use it as an external library +(@pxref{External Libraries}). + + +@node Copyright Notices +@section Copyright Notices +@cindex copyright notices in program files + +You should maintain a proper copyright notice and a license +notice in each nontrivial file in the package. (Any file more than ten +lines long is nontrivial for this purpose.) This includes header files +and interface definitions for +building or running the program, documentation files, and any supporting +files. If a file has been explicitly placed in the public domain, then +instead of a copyright notice, it should have a notice saying explicitly +that it is in the public domain. + +Even image files and sound files should contain copyright notices and +license notices, if their format permits. Some formats do not have +room for textual annotations; for these files, state the copyright and +copying permissions in a @file{README} file in the same directory. + +Change log files should have a copyright notice and license notice at +the end, since new material is added at the beginning but the end +remains the end. + +When a file is automatically generated from some other file in the +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: + +@example +Copyright (C) @var{year1}, @var{year2}, @var{year3} @var{copyright-holder} +@end example + +The word @samp{Copyright} must always be in English, by international +convention. + +The @var{copyright-holder} may be the Free Software Foundation, Inc., or +someone else; you should know who is the copyright holder for your +package. + +Replace the @samp{(C)} with a C-in-a-circle symbol if it is available. +For example, use @samp{@@copyright@{@}} in a Texinfo file. However, +stick with parenthesized @samp{C} unless you know that C-in-a-circle +will work. For example, a program's standard @option{--version} +message should use parenthesized @samp{C} by default, though message +translations may use C-in-a-circle in locales where that symbol is +known to work. Alternatively, the @samp{(C)} or C-in-a-circle can be +omitted entirely; the word @samp{Copyright} suffices. + +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 of 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. + +Don't delete old year numbers, though; they are significant since they +indicate when older versions might theoretically go into the public +domain, if the movie companies don't continue buying laws to further +extend copyright. If you copy a file into the package from some other +program, keep the copyright years that come with the file. + +You can use a range (@samp{2008-2010}) instead of listing individual +years (@samp{2008, 2009, 2010}) if and only if: 1)@tie{}every year in +the range, inclusive, really is a ``copyrightable'' year that would be +listed individually; @emph{and} 2)@tie{}you make an explicit statement +in a @file{README} file about this usage. + +For files which are regularly copied from another project (such as +@samp{gnulib}), leave the copyright notice as it is in the original. + +The copyright statement may be split across multiple lines, both in +source files and in any generated output. This often happens for +files with a long history, having many different years of +publication. + +For an FSF-copyrighted package, if you have followed the procedures to +obtain legal papers, each file should have just one copyright holder: +the Free Software Foundation, Inc. You should edit the file's +copyright notice to list that name and only that name. + +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 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. (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 +@cindex license notices in program files + +Every nontrivial file needs a license notice as well as the copyright +notice. (Without a license notice giving permission to copy and +change the file, the file is non-free.) + +The package itself should contain a full copy of GPL in plain text +(conventionally in a file named @file{COPYING}) and the GNU Free +Documentation License (included within your documentation, so there is +no need for a separate plain text version). If the package contains +any files distributed under the Lesser GPL, it should contain a full +copy of its plain text version also (conventionally in a file named +@file{COPYING.LESSER}). + +If you have questions about licensing issues for your GNU package, +please write @email{licensing@@gnu.org}. + +@menu +* Which: Licensing of GNU Packages. +* Canonical: Canonical License Sources. +* Code: License Notices for Code. +* Documentation: License Notices for Documentation. +* Other: License Notices for Other Files. +@end menu + + +@node Licensing of GNU Packages +@subsection Licensing of GNU Packages + +Normally, GNU packages should use the latest version of the GNU GPL, +with the ``or any later version'' formulation. @xref{License Notices +for Code}, for the exact wording of the license notice. + +Occasionally, a GNU library may provide functionality which is already +widely available to proprietary programs through alternative +implementations; for example, the GNU C Library. In such cases, the +Lesser GPL should be used (again, for the notice wording, +@pxref{License Notices for Code}). If a GNU library provides unique +functionality, however, the GNU GPL should be used. +@url{http://www.gnu.org/licenses/why-not-lgpl.html} discusses this +strategic choice. + +Some of these libraries need to work with programs released under +GPLv2-only; that is, which allow the GNU GPL version 2 but not later +versions. In this case, the GNU package should be released under a +dual license: GNU GPL version 2 (or any later version) and the GNU +Lesser GPL version 3 (or any later version). Here is the notice for +that case: + +@smallexample +This file is part of GNU @var{package}. + +GNU @var{package} is free software: you can redistribute it and/or +modify it under the terms of either: + + * the GNU Lesser General Public License as published by the Free + Software Foundation; either version 3 of the License, or (at your + option) any later version. + +or + + * the GNU General Public License as published by the Free + Software Foundation; either version 2 of the License, or (at your + option) any later version. + +or both in parallel, as here. + +GNU @var{package} is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received copies of the GNU General Public License and +the GNU Lesser General Public License along with this program. If +not, see @url{http://www.gnu.org/licenses/}. +@end smallexample + +For small packages, you can use ``This program'' instead of ``GNU +@var{package}''. + + +@node Canonical License Sources +@subsection Canonical License Sources + +You can get the official versions of these files from several places. +You can use whichever is the most convenient for you. + +@itemize @bullet +@item +@uref{http://www.gnu.org/licenses/}. + +@item +The @code{gnulib} project on @code{savannah.gnu.org}, which you +can access via anonymous Git or CVS. See +@uref{http://savannah.gnu.org/projects/gnulib}. + +@end itemize + +The official Texinfo sources for the licenses are also available in +those same places, so you can include them in your documentation. A +GFDL-covered manual should include the GFDL in this way. @xref{GNU +Sample Texts,,, texinfo, Texinfo}, for a full example in a Texinfo +manual. + + +@node License Notices for Code +@subsection License Notices for Code + +Typically the license notice for program files (including build scripts, +configure files and makefiles) should cite the GPL, like this: + +@quotation +This file is part of GNU @var{package}. + +GNU @var{package} is free software: you can redistribute it and/or +modify it under the terms of the GNU General Public License as +published by the Free Software Foundation, either version 3 of the +License, or (at your option) any later version. + +GNU @var{package} is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see @url{http://www.gnu.org/licenses/}. +@end quotation + +But in a small program which is just a few files, you can use +this instead: + +@quotation +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see @url{http://www.gnu.org/licenses/}. +@end quotation + +In either case, for those few packages which use the Lesser GPL +(@pxref{Licensing of GNU Packages}), insert the word ``Lesser'' before +``General'' in @emph{all three} places. +@url{http://@/www.gnu.org/@/licenses/@/gpl-howto.html} discusses application +the GPL in more detail. + + +@node License Notices for Documentation +@subsection License Notices for Documentation + +Documentation files should have license notices also. Manuals should +use the GNU Free Documentation License. Following is an example of the +license notice to use after the copyright line(s) using all the +features of the GFDL. + +@smallexample +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 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 +as in (a) below. A copy of the license is included in the section +entitled ``GNU Free Documentation License''. + +(a) The FSF's Back-Cover Text is: ``You have the freedom to +copy and modify this GNU manual. Buying copies from the FSF +supports it in developing GNU and promoting software freedom.'' +@end smallexample + +If the FSF does not publish this manual on paper, then omit the last +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. + +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. + +@xref{GNU Sample Texts,,, texinfo, Texinfo}, for a full example in a +Texinfo manual, and see +@url{http://www.gnu.org/licenses/fdl-howto.html} for more advice about +how to use the GNU FDL. + +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 +section which explains the importance of free documentation. Write to +@email{assign@@gnu.org} to get a copy of this section. + +When you distribute several manuals together in one software package, +their on-line forms can share a single copy of the GFDL (see +section@tie{}6). However, the printed (@samp{.dvi}, @samp{.pdf}, +@dots{}) forms should each contain a copy of the GFDL, unless they are +set up to be printed and published only together. Therefore, it is +usually simplest to include the GFDL in each manual. + + +@node License Notices for Other Files +@subsection License Notices for Other Files + +Small supporting files, short manuals (under 300 lines long) and rough +documentation (@file{README} files, @file{INSTALL} files, etc.)@: can +use a simple all-permissive license like this one: + +@smallexample +Copying and distribution of this file, with or without modification, +are permitted in any medium without royalty provided the copyright +notice and this notice are preserved. This file is offered as-is, +without any warranty. +@end smallexample + +Older versions of this license did not have the second sentence with +the express warranty disclaimer. There is no urgent need to update +existing files, but new files should use the new text. + +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. + + +@node External Libraries +@section External Libraries + +When maintaining an FSF-copyrighted GNU package, you may occasionally +want to use a general-purpose free software module which offers a +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 +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: + +@enumerate +@item +Assume the module is already installed on the system, and use it when +linking your program. This is only reasonable if the module really has +the form of a library. + +@item +Include the module in your package, putting the source in a separate +subdirectory whose @file{README} file says, ``This is not part of the +GNU FOO program, but is used with GNU FOO.'' Then set up your makefiles +to build this module and link it into the executable. + +For this method, it is not necessary to treat the module as a library +and make a @samp{.a} file from it. You can link with the @samp{.o} +files directly in the usual manner. +@end enumerate + +Both of these methods create an irregularity, and our lawyers have told +us to minimize the amount of such irregularity. So consider using these +methods only for general-purpose modules that were written for other +programs and released separately for general use. For anything that was +written as a contribution to your package, please get papers signed. + + +@node Clean Ups +@chapter Cleaning Up Changes +@cindex contributions, accepting +@cindex quality of changes suggested by others + +Don't feel obligated to include every change that someone asks you to +include. You must judge which changes are improvements---partly based +on what you think the users will like, and partly based on your own +judgment of what is better. If you think a change is not good, you +should reject it. + +If someone sends you changes which are useful, but written in an ugly +way or hard to understand and maintain in the future, don't hesitate to +ask per to clean up their changes before you merge them. Since the +amount of work we can do is limited, the more we convince others to help +us work efficiently, the faster GNU will advance. + +If the contributor will not or can not make the changes clean enough, +then it is legitimate to say ``I can't install this in its present form; +I can only do so if you clean it up.'' Invite per to distribute per +changes another way, or to find other people to make them clean enough +for you to install and maintain. + +The only reason to do these cleanups yourself is if (1) it is easy, less +work than telling the author what to clean up, or (2) the change is an +important one, important enough to be worth the work of cleaning it up. + +The GNU Coding Standards are a good thing to send people when you ask +them to clean up changes (@pxref{Top, , Contents, standards, GNU Coding +Standards}). The Emacs Lisp manual contains an appendix that gives +coding standards for Emacs Lisp programs; it is good to urge Lisp authors to +read it (@pxref{Tips, , Tips and Conventions, elisp, The GNU Emacs Lisp +Reference Manual}). + + +@node Platforms +@chapter Platforms to Support + +Most GNU packages run on a wide range of platforms. These platforms are +not equally important. + +The most important platforms for a GNU package to support are GNU and +GNU/Linux. Developing the GNU operating system is the whole point of +the GNU Project; a GNU package exists to make the whole GNU system more +powerful. So please keep that goal in mind and let it shape your work. +For instance, every new feature you add should work on GNU, and +GNU/Linux if possible too. If a new feature only runs on GNU and +GNU/Linux, it could still be acceptable. However, a feature that runs +only on other systems and not on GNU or GNU/Linux makes no sense in a +GNU package. + +You will naturally want to keep the program running on all the platforms +it supports. But you personally will not have access to most of these +platforms---so how should you do it? + +Don't worry about trying to get access to all of these platforms. Even +if you did have access to all the platforms, it would be inefficient for +you to test the program on each platform yourself. Instead, you should +test the program on a few platforms, including GNU or GNU/Linux, and let +the users test it on the other platforms. You can do this through a +pretest phase before the real release; when there is no reason to expect +problems, in a package that is mostly portable, you can just make a +release and let the users tell you if anything unportable was +introduced. + +It is important to test the program personally on GNU or GNU/Linux, +because these are the most important platforms for a GNU package. If +you don't have access to one of these platforms, as a GNU maintainer +you can get access to the general GNU login machine; see +@url{http://www.gnu.org/software/README.accounts.html}. + +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 +@cindex email + +This chapter describes setting up mailing lists for your package, and +gives advice on how to handle bug reports and random requests once you +have them. + +@menu +* Standard Mailing Lists:: @samp{bug-pkg@@gnu.org} and other standard names. +* Creating Mailing Lists:: The best way is to use Savannah. +* Replying to Mail:: Advice on replying to incoming mail. +@end menu + + +@node Standard Mailing Lists +@section Standard Mailing Lists + +@cindex standard mailing lists +@cindex mailing lists, standard names of + +@cindex mailing list for bug reports +Once a program is in use, you will get bug reports for it. Most GNU +programs have their own special lists for sending bug reports. The +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. + +@cindex @email{bug-gnu-utils@@gnu.org} +We also have a catch-all list, @email{bug-gnu-utils@@gnu.org}, which is +used for all GNU programs that don't have their own specific lists. But +nowadays we want to give each program its own bug-reporting list and +move away from using @email{bug-gnu-utils}. + +@xref{Replying to Mail}, for more about handling and tracking bug +reports. + +@cindex help for users, mailing list for +Some GNU programs with many users have another mailing list, +@samp{help-@var{package}.org}, for people to ask other users for help. +If your program has many users, you should create such a list for it. +For a fairly new program, which doesn't have a large user base yet, it +is better not to bother with this. + +@cindex announcements, mailing list for +If you wish, you can also have a mailing list +@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 + +@cindex creating mailing lists +@cindex mailing lists, creating + +Using the web interface on @code{savannah.gnu.org} is by far the +easiest way to create normal mailing lists, managed through Mailman on +the GNU mail server. Once you register your package on Savannah, you +can create (and remove) lists yourself through the `Mailing Lists' +menu, without needing to wait for intervention by anyone else. +Furthermore, lists created through Savannah will have a reasonable +default configuration for antispam purposes (see below). + +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}). + +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. + +@cindex spam prevention +You should moderate postings from non-subscribed addresses on your +mailing lists, to prevent propagation of unwanted messages (``spam'') +to subscribers and to the list archives. For lists controlled by +Mailman, you can do this by setting @code{Privacy Options - Sender +Filter - generic_nonmember_action} to @code{Hold}, and then +periodically (daily is best) reviewing the held messages, accepting +the real ones and discarding the junk. + +Lists created through Savannah will have this setting, and a number of +others, such that spam will be automatically deleted (after a short +delay). The Savannah mailing list page describes all the details. +You should still review the held messages in order to approve any that +are real. + + +@node Replying to Mail +@section Replying to Mail + +@cindex responding to bug reports +@cindex bug reports, handling +@cindex help requests, handling + +When you receive bug reports, keep in mind that bug reports are crucial +for your work. If you don't know about problems, you cannot fix them. +So always thank each person who sends a bug report. + +You don't have an obligation to give more response than that, though. +The main purpose of bug reports is to help you contribute to the +community by improving the next version of the program. Many of the +people who report bugs don't realize this---they think that the point is +for you to help them individually. Some will ask you to focus on that +@emph{instead of} on making the program better. If you comply with +their wishes, you will have been distracted from the job of maintaining +the program. + +For example, people sometimes report a bug in a vague (and therefore +useless) way, and when you ask for more information, they say, ``I just +wanted to see if you already knew the solution'' (in which case the bug +report would do nothing to help improve the program). When this +happens, you should explain to them the real purpose of bug reports. (A +canned explanation will make this more efficient.) + +When people ask you to put your time into helping them use the program, +it may seem ``helpful'' to do what they ask. But it is much @emph{less} +helpful than improving the program, which is the maintainer's real job. + +By all means help individual users when you feel like it, if you feel +you have the time available. But be careful to limit the amount of time +you spend doing this---don't let it eat away the time you need to +maintain the program! Know how to say no; when you are pressed for +time, just ``thanks for the bug report---I will fix it'' is enough +response. + +Some GNU packages, such as Emacs and GCC, come with advice about how +to make bug reports useful. Copying and adapting that could be very +useful for your package. + +@cindex @url{http://bugs.gnu.org} +@cindex bug reports, email tracker for +@cindex bug reports, web tracker for +If you would like to use an email-based bug tracking system, see +@url{http://bugs.gnu.org}; this can be connected with the regular +bug-reporting address. Alternatively, if you would like to use a +web-based bug tracking system, Savannah supports this (@pxref{Old +Versions}), but please don't fail to accept bugs by regular email as +well---we don't want to put up unnecessary barriers against users +submitting reports. + + +@node Old Versions +@chapter Recording Old Versions +@cindex version control + +It is very important to keep backup files of all source files of GNU. +You can do this using a source control system (such as Bazaar, RCS, +CVS, Git, Subversion, @dots{}) if you like. An easy way to use +many such systems is via the Version Control library in Emacs +(@pxref{Introduction to VC,, Introduction to Version Control, emacs, +The GNU Emacs Manual}). + +The history of previous revisions and log entries is very important for +future maintainers of the package, so even if you do not make it +publicly accessible, be careful not to put anything in the repository or +change log that you would not want to hand over to another maintainer +some day. + +@cindex @code{savannah-hackers@@gnu.org} +The GNU Project provides a server that GNU packages can use +for source control and other package needs: @code{savannah.gnu.org}. +Savannah is managed by @email{savannah-hackers@@gnu.org}. For more +details on using and contributing to Savannah, see +@url{http://savannah.gnu.org/maintenance}. + +It's not an absolute requirement, but all GNU maintainers are strongly +encouraged to take advantage of Savannah, as sharing such a central +point can serve to foster a sense of community among GNU developers as +well as help in keeping up with project management. Please don't mark +Savannah projects for GNU packages as private; that defeats a large +part of the purpose of using Savannah in the first place. + +@cindex @code{savannah-announce@@gnu.org} mailing list +If you do use Savannah, please subscribe to the +@email{savannah-announce@@gnu.org} mailing list +(@url{http://lists.gnu.org/mailman/listinfo/savannah-announce}). This +is a very low-volume list to keep Savannah users informed of system +upgrades, problems, and the like. + + +@node Distributions +@chapter Distributions + +It is important to follow the GNU conventions when making GNU software +distributions. + +@menu +* Distribution tar Files:: +* Distribution Patches:: +* Distribution on ftp.gnu.org:: +* Test Releases:: +* Automated FTP Uploads:: +* Announcements:: +@end menu + +@node Distribution tar Files +@section Distribution tar Files +@cindex distribution, tar files + +The tar file for version @var{m}.@var{n} of program @code{foo} should be +named @file{foo-@var{m}.@var{n}.tar}. It should unpack into a +subdirectory named @file{foo-@var{m}.@var{n}}. Tar files should not +unpack into files in the current directory, because this is inconvenient +if the user happens to unpack into a directory with other files in it. + +Here is how the @file{Makefile} for Bison creates the tar file. +This method is good for other programs. + +@example +dist: bison.info + echo bison-`sed -e '/version_string/!d' \ + -e 's/[^0-9.]*\([0-9.]*\).*/\1/' -e q version.c` > .fname + -rm -rf `cat .fname` + mkdir `cat .fname` + dst=`cat .fname`; for f in $(DISTFILES); do \ + ln $(srcdir)/$$f $$dst/$$f || @{ echo copying $$f; \ + cp -p $(srcdir)/$$f $$dst/$$f ; @} \ + done + tar --gzip -chf `cat .fname`.tar.gz `cat .fname` + -rm -rf `cat .fname` .fname +@end example + +Source files that are symbolic links to other file systems cannot be +installed in the temporary directory using @code{ln}, so use @code{cp} +if @code{ln} fails. + +@pindex automake +Using Automake is a good way to take care of writing the @code{dist} +target. + +@node Distribution Patches +@section Distribution Patches +@cindex patches, against previous releases + +If the program is large, it is useful to make a set of diffs for each +release, against the previous important release. + +At the front of the set of diffs, put a short explanation of which +version this is for and which previous version it is relative to. +Also explain what else people need to do to update the sources +properly (for example, delete or rename certain files before +installing the diffs). + +The purpose of having diffs is that they are small. To keep them +small, exclude files that the user can easily update. For example, +exclude info files, DVI files, tags tables, output files of Bison or +Flex. In Emacs diffs, we exclude compiled Lisp files, leaving it up +to the installer to recompile the patched sources. + +When you make the diffs, each version should be in a directory suitably +named---for example, @file{gcc-2.3.2} and @file{gcc-2.3.3}. This way, +it will be very clear from the diffs themselves which version is which. + +@pindex diff +@pindex patch +@cindex time stamp in diffs +If you use GNU @code{diff} to make the patch, use the options +@samp{-rc2P}. That will put any new files into the output as ``entirely +different''. Also, the patch's context diff headers should have dates +and times in Universal Time using traditional Unix format, so that patch +recipients can use GNU @code{patch}'s @samp{-Z} option. For example, +you could use the following Bourne shell command to create the patch: + +@example +LC_ALL=C TZ=UTC0 diff -rc2P gcc-2.3.2 gcc-2.3.3 | \ +gzip -9 >gcc-2.3.2-2.3.3.patch.gz +@end example + +If the distribution has subdirectories in it, then the diffs probably +include some files in the subdirectories. To help users install such +patches reliably, give them precise directions for how to run patch. +For example, say this: + +@display +To apply these patches, cd to the main directory of the program +and then use `patch -p1'. `-p1' avoids guesswork in choosing +which subdirectory to find each file in. +@end display + +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. + +@xref{Automated FTP Uploads}, for procedural details of putting new +versions on @code{ftp.gnu.org}. + +@node Test Releases +@section Test Releases +@cindex test releases +@cindex beta releases +@cindex pretest releases + +@cindex @code{alpha.gnu.org}, test release site +When you release a greatly changed new major version of a program, you +might want to do so as a pretest. This means that you make a tar file, +but send it only to a group of volunteers that you have recruited. (Use +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}. + +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'' +release. + +There are two ways of handling version numbers for pretest versions. +One method is to treat them as versions preceding the release you are going +to make. + +In this method, if you are about to release version 4.6 but you want +to do a pretest first, call it 4.5.90. If you need a second pretest, +call it 4.5.91, and so on. If you are really unlucky and ten pretests +are not enough, after 4.5.99 you could advance to 4.5.990 and so on. +(You could also use 4.5.100, but 990 has the advantage of sorting in +the right order.) + +The other method is to attach a date to the release number that is +coming. For a pretest for version 4.6, made on Dec 10, 2002, this +would be 4.6.20021210. A second pretest made the same day could be +4.6.20021210.1. + +For development snapshots that are not formal pretests, using just +the date without the version numbers is ok too. + +One thing that you should never do is to release a pretest with the same +version number as the planned real release. Many people will look only +at the version number (in the tar file name, in the directory name that +it unpacks into, or wherever they can find it) to determine whether a +tar file is the latest version. People might look at the test release +in this way and mistake it for the real release. Therefore, always +change the number when you release changed code. + + +@node Automated FTP Uploads +@section Automated FTP Uploads + +@cindex ftp uploads, automated +In order to upload new releases to @code{ftp.gnu.org} or +@code{alpha.gnu.org}, you first need to register the necessary +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 +before they are made publicly available. + +@menu +* Automated Upload Registration:: +* Automated Upload Procedure:: +* FTP Upload Directive File - v1.1:: +* FTP Upload Directive File - v1.0:: +@end menu + + +@node Automated Upload Registration +@subsection Automated Upload Registration + +@cindex registration for uploads +@cindex uploads, registration for + +Here is how to register your information so you can perform uploads +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 +maintain the web pages at @url{http://www.gnu.org} for your project +(@pxref{Web Pages}). + +@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). + +Optional but recommended: Send your key to a GPG public key server: +@code{gpg --keyserver keys.gnupg.net --send-keys @var{keyid}}, where +@var{keyid} is the eight hex digits reported by @code{gpg +--list-public-keys} on the @code{pub} line before the date. For full +information about GPG, see @url{http://www.gnu.org/software/gpg}. + +@item +Compose a message with the following items in some @var{msgfile}. +Then GPG-sign it by running @code{gpg --clearsign @var{msgfile}}, and +finally email the resulting @file{@var{msgfile}.asc} to +@email{ftp-upload@@gnu.org}. + +@enumerate +@item +Name of package(s) that you are the maintainer for, your +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.) + +@item +A list of names and preferred email addresses of other individuals you +authorize to make releases for which packages, if any (in the case that you +don't make all releases yourself). + +@item +ASCII armored copies of GPG keys for any individuals listed in (3). +@end enumerate +@end enumerate + +The administrators will acknowledge your message when they have added +the proper GPG keys as authorized to upload files for the +corresponding packages. + +The upload system will email receipts to the given email addresses +when an upload is made, either successfully or unsuccessfully. + + +@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}. + +@enumerate +@item +The file to be distributed; for example, @file{foo.tar.gz}. + +@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. +@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. + +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. + +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. + +One automated 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. + +@code{gnupload} uses the @code{ncftpput} program 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}. + +If you have difficulties with an upload, email +@email{ftp-upload@@gnu.org}. You can check the archive of uploads +processed at +@url{https://lists.gnu.org/archive/html/ftp-upload-report}. + + +@node FTP Upload Directive File - v1.1 +@subsection FTP Upload Directive File - v1.1 + +The directive file name must end in @file{directive.asc}. + +When part of a triplet, the directive file must always contain the +directives @code{version}, @code{directory} and @code{filename}, as +described. In addition, a 'comment' directive is allowed. + +The @code{version} directive must always have the value @samp{1.1}. + +The @code{directory} directive specifies the final destination +directory where the uploaded file and its @file{.sig} companion are to +be placed. + +The @code{filename} directive must contain the name of the file to be +distributed (item@tie{}(1) above). + +For example, as part of an uploaded triplet, a +@file{foo.tar.gz.directive.asc} file might contain these lines (before +being gpg clearsigned): + +@example +version: 1.1 +directory: bar/v1 +filename: foo.tar.gz +comment: hello world! +@end example + +This directory line indicates that @file{foo.tar.gz} and +@file{foo.tar.gz.sig} are part of package @code{bar}. If you uploaded +this triplet to @file{/incoming/ftp} and the system positively +authenticates the signatures, the files @file{foo.tar.gz} and +@file{foo.tar.gz.sig} will be placed in the directory +@file{gnu/bar/v1} of the @code{ftp.gnu.org} site. + +The directive file can be used to create currently non-existent +directory trees, as long as they are under the package directory for +your package (in the example above, that is @code{bar}). + +If you upload a file that already exists in the FTP directory, the +original will simply be archived and replaced with the new upload. + +@subheading Standalone directives + +When uploaded by itself, the directive file must contain one or more +of the directives @code{symlink}, @code{rmsymlink} or @code{archive}, +in addition to the obligatory @code{directory} and @code{version} +directives. A @code{filename} directive is not allowed, and a +@code{comment} directive remains optional. + +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.) + +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 +comment: available through FTP any more. +@end example + +@noindent +Archive an old directory (with all contents), taking it offline: + +@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 +@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) are to be placed. + +For example, the @file{foo.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 +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 +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}). + + +@node Announcements +@section Announcing Releases +@cindex announcements + +@cindex @code{info-gnu} mailing list +When you have a new release, please make an announcement. For +official new releases, including those made just to fix bugs, we +strongly recommend using the (moderated) general GNU announcements +list, @email{info-gnu@@gnu.org}. Doing so makes it easier for users +and developers to find the latest GNU releases. On the other hand, +please do not announce test releases on @code{info-gnu} unless it's a +highly unusual situation. + +@cindex @url{http://planet.gnu.org} +@cindex Savannah, news area +Please also post release announcements in the news section of your +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 +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 +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.) + +@cindex contents of announcements +When writing an announcement, please include the following: + +@itemize @bullet +@item +A very brief description (a few sentences at most) of the general +purpose of your package. + +@item +Your package's web page (normally +@indicateurl{http://www.gnu.org/software/@var{package}/}). + +@item +Your package's download location (normally +@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 +redirect to a nearby mirror. + +@item +The @t{NEWS} (@pxref{NEWS File,,, standards, GNU Coding Standards}) for +the present release. +@end itemize + + +@node Web Pages +@chapter Web Pages +@cindex web pages + +Please write web pages about your package, and install them on +@code{www.gnu.org}. They should follow our usual standards for web +pages (see @url{http://www.gnu.org/server/@/fsf-html-style-sheet.html}). +The overall goals are to support a wide variety of browsers, to focus +on information rather than flashy eye candy, and to keep the site +simple and uniform. + +We encourage you to use the standard @code{www.gnu.org} template as +the basis for your pages: +@url{http://www.gnu.org/server/@/standards/@/boilerplate-source.html}. + +Some GNU packages have just simple web pages, but the more information +you provide, the better. So please write as much as you usefully can, +and put all of it on @code{www.gnu.org}. However, pages that access +databases (including mail archives and bug tracking) are an exception; +set them up on whatever site is convenient for you, and make the pages +on @code{www.gnu.org} link to that site. + +@menu +* Hosting for Web Pages:: +* Freedom for Web Pages:: +* Manuals on Web Pages:: +* CVS Keywords in Web Pages:: +@end menu + + +@node Hosting for Web Pages +@section Hosting for Web Pages + +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 +using CVS, using the separate ``web repository'' available on +Savannah, which corresponds to +@indicateurl{http://www.gnu.org/software/@var{package}/}. You can +keep your source files there too (using any of a variety of version +control systems), but you can use @code{savannah.gnu.org} only for +your gnu.org web pages if you wish; simply register a ``web-only'' +project. + +If you don't want to use that method, please talk with +@email{webmasters@@gnu.org} about other possible methods. For +instance, you can mail them pages to install, if necessary. But that +is more work for them, so please use Savannah if you can. + +If you use Savannah, you can use a special file named @file{.symlinks} +in order to create symbolic links, which are not supported in CVS. +For details, see +@url{http://www.gnu.org/server/standards/README.webmastering.html#symlinks}. + + +@node Freedom for Web Pages +@section Freedom for Web Pages + +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 +unreleased custom software, since that is free in a trivial sense: +there's only one user and it has the four freedoms.) If the web site +for a GNU package runs on non-free software, the public will see this, +and it will have the effect of granting legitimacy to the non-free +program. + +If you use multiple sites, they should all follow that criterion. +Please don't link to a site that is about your package, which the +public might perceive as connected with it and reflecting the position +of its developers, unless it follows that criterion. + +Historically, web pages for GNU packages did not include GIF images, +because of patent problems (@pxref{Ethical and Philosophical +Consideration}). Although the GIF patents expired in 2006, using GIF +images is still not recommended, as the PNG and JPEG formats are +generally superior. See @url{http://www.gnu.org/philosophy/gif.html}. + + +@node Manuals on Web Pages +@section Manuals on Web Pages + +The web pages for the package should include its manuals, in HTML, +DVI, Info, PostScript, PDF, plain ASCII, and Texinfo format (source). +All of these can be generated automatically from the Texinfo source +using Makeinfo and other programs. + +When there is only one manual, put it in a subdirectory called +@file{manual}; the file @file{manual/index.html} should have a link to +the manual in each of its forms. + +If the package has more than one manual, put each one in a +subdirectory of @file{manual}, set up @file{index.html} in each +subdirectory to link to that manual in all its forms, and make +@file{manual/index.html} link to each manual through its subdirectory. + +See the section below for details on a script to make the job of +creating all these different formats and index pages easier. + +We would like to list all GNU manuals on the page +@url{http://www.gnu.org/manual}, so if yours isn't there, please send +mail to @code{webmasters@@gnu.org}, asking them to add yours, and they +will do so based on the contents of your @file{manual} directory. + +@menu +* Invoking gendocs.sh:: +@end menu + + +@node Invoking gendocs.sh +@subsection Invoking @command{gendocs.sh} +@pindex gendocs.sh +@cindex generating documentation output + +The script @command{gendocs.sh} eases the task of generating the +Texinfo documentation output for your web pages +section above. It has a companion template file, used as the basis +for the HTML index pages. Both are available from the Texinfo CVS +sources: + +@smallformat +@uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh} +@uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template} +@end smallformat + +There is also a minimalistic template, available from: + +@smallformat +@uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template_min} +@end smallformat + +Invoke the script like this, in the directory containing the Texinfo +source: + +@smallexample +gendocs.sh --email @var{yourbuglist} @var{yourmanual} "GNU @var{yourmanual} manual" +@end smallexample + +@noindent where @var{yourmanual} is the short name for your package +and @var{yourbuglist} is the email address for bug reports (which +should be @code{bug-@var{package}@@gnu.org}). The script processes +the file @file{@var{yourmanual}.texinfo} (or @file{.texi} or +@file{.txi}). For example: + +@smallexample +cd .../texinfo/doc +# download gendocs.sh and gendocs_template +gendocs.sh --email bug-texinfo@@gnu.org texinfo "GNU Texinfo manual" +@end smallexample + +@command{gendocs.sh} creates a subdirectory @file{manual/} containing +the manual generated in all the standard output formats: Info, HTML, +DVI, and so on, as well as the Texinfo source. You then need to move +all those files, retaining the subdirectories, into the web pages for +your package. + +You can specify the option @option{-o @var{outdir}} to override the +name @file{manual}. Any previous contents of @var{outdir} will be deleted. + +The second argument, with the description, is included as part of the +HTML @code{<title>} of the overall @file{manual/index.html} file. It +should include the name of the package being documented, as shown. +@file{manual/index.html} is created by substitution from the file +@file{gendocs_template}. (Feel free to modify the generic template +for your own purposes.) + +If you have several manuals, you'll need to run this script several +times with different arguments, specifying a different output +directory with @option{-o} each time, and moving all the output to +your web page. Then write (by hand) an overall index.html with links +to them all. For example: + +@smallexample +cd .../texinfo/doc +gendocs.sh --email bug-texinfo@@gnu.org -o texinfo texinfo "GNU Texinfo manual" +gendocs.sh --email bug-texinfo@@gnu.org -o info info "GNU Info manual" +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.: + +@smallexample +gendocs --texi2html -o texinfo texinfo "GNU Texinfo manual" +@end smallexample + +The template files will automatically produce entries for additional +HTML output generated by @command{texi2html} (i.e., split by sections +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 +@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}. + + +@node CVS Keywords in Web Pages +@section CVS Keywords in Web Pages +@cindex CVS keywords in web pages +@cindex RCS keywords in web pages +@cindex $ keywords in web pages +@cindex web pages, and CVS keywords + +Since @code{www.gnu.org} works through CVS, CVS keywords in your +manual, such as @code{@w{$}Log$}, need special treatment (even if you +don't happen to maintain your manual in CVS). + +If these keywords end up in the generated output as literal strings, +they will be expanded. The most robust way to handle this is to turn +off keyword expansion for such generated files. For existing files, +this is done with: + +@example +cvs admin -ko @var{file1} @var{file2} ... +@end example + +@noindent +For new files: + +@example +cvs add -ko @var{file1} @var{file2} ... +@end example + +@c The CVS manual is now built with numeric references and no nonsplit +@c form, so it's not worth trying to give a direct link. +See the ``Keyword Substitution'' section in the CVS manual, available +at @url{http://ximbiot.com/cvs/manual}. + +In Texinfo source, the recommended way to literally specify a +``dollar'' keyword is: + +@example +@@w@{$@}Log$ +@end example + +The @code{@@w} prevents keyword expansion in the Texinfo source +itself. Also, @code{makeinfo} notices the @code{@@w} and generates +output avoiding the literal keyword string. + + +@node Ethical and Philosophical Consideration +@chapter Ethical and Philosophical Consideration +@cindex ethics +@cindex philosophy + +The GNU project takes a strong stand for software freedom. Many +times, this means you'll need to avoid certain technologies when their +use would conflict with our long-term goals. + +Software patents threaten the advancement of free software and freedom +to program. There are so many software patents in the US that any +large program probably implements hundreds of patented techniques, +unknown to the program's developers. It would be futile and +self-defeating to try to find and avoid all these patents. But there +are some patents which we know are likely to be used to threaten free +software, so we make an effort to avoid the patented techniques. If +you are concerned about the danger of a patent and would like advice, +write to @email{licensing@@gnu.org}, and we will try to help you get +advice from a lawyer. + +Sometimes the GNU project takes a strong stand against a particular +patented technology in order to encourage society to reject it. + +For example, the MP3 audio format is covered by a software patent in +the USA and some other countries. A patent holder has threatened +lawsuits against the developers of free programs (these are not GNU +programs) to produce and play MP3, and some GNU/Linux distributors are +afraid to include them. Development of the programs continues, but we +campaign for the rejection of MP3 format in favor of Ogg Vorbis format. + +A GNU package should not recommend use of any non-free program, nor +should it require a non-free program (such as a non-free compiler or +IDE) to build. Thus, a GNU package cannot be written in a programming +language that does not have a free software implementation. Now that +GNU/Linux systems are widely available, all GNU packages should +provide full functionality on a 100% free GNU/Linux system, and should +not require any non-free software to build or function. +The GNU Coding Standards say a lot more about this issue. + +A GNU package should not refer the user to any non-free documentation +for free software. The need for free documentation to come with free +software is now a major focus of the GNU project; to show that we are +serious about the need for free documentation, we must not contradict +our position by recommending use of documentation that isn't free. + +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 +project when such issues come up. + + +@node Terminology +@chapter Terminology Issues +@cindex terminology + +This chapter explains a couple of issues of terminology which are +important for correcting two widespread and important misunderstandings +about GNU. + +@menu +* Free Software and Open Source:: +* GNU and Linux:: +@end menu + +@node Free Software and Open Source +@section Free Software and Open Source +@cindex free software movement +@cindex open source +@cindex movement, free software +@cindex development method, open source + +The terms ``free software'' and ``open source'', while describing +almost the same category of software, stand for views based on +fundamentally different values. The free software movement is +idealistic, and raises issues of freedom, ethics, principle and what +makes for a good society. The term open source, initiated in 1998, is +associated with a philosophy which studiously avoids such questions. +For a detailed explanation, see +@url{http://www.gnu.org/philosophy/open-source-misses-the-point.html}. + +The GNU Project is aligned with the free software movement. This +doesn't mean that all GNU contributors and maintainers have to agree; +your views on these issues are up to you, and you're entitled to express +them when speaking for yourself. + +However, due to the much greater publicity that the term ``open source'' +receives, the GNU Project needs to overcome a widespread +mistaken impression that GNU is @emph{and always was} an ``open +source'' activity. For this reason, please use the term ``free +software'', not ``open source'', in GNU software releases, GNU +documentation, and announcements and articles that you publish in your +role as the maintainer of a GNU package. A reference to the URL given +above, to explain the difference, is a useful thing to include as +well. + + +@node GNU and Linux +@section GNU and Linux +@cindex Linux +@cindex GNU/Linux + +The GNU Project was formed to develop a free Unix-like operating system, +GNU. The existence of this system is our major accomplishment. +However, the widely used version of the GNU system, in which Linux is +used as the kernel, is often called simply ``Linux''. As a result, most +users don't know about the GNU Project's major accomplishment---or more +precisely, they know about it, but don't realize it is the GNU Project's +accomplishment and reason for existence. Even people who believe they +know the real history often believe that the goal of GNU was to develop +``tools'' or ``utilities''. + +To correct this confusion, we have made a years-long effort to +distinguish between Linux, the kernel that Linus Torvalds wrote, and +GNU/Linux, the operating system that is the combination of GNU and +Linux. The resulting increased awareness of what the GNU Project has +already done helps every activity of the GNU Project recruit more +support and contributors. + +Please make this distinction consistently in GNU software releases, GNU +documentation, and announcements and articles that you publish in your +role as the maintainer of a GNU package. If you want to explain the +terminology and its reasons, you can refer to the URL +@url{http://www.gnu.org/gnu/linux-and-gnu.html}. + +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 +``the GNU system''. + +When referring to the collection of servers that is the higher level +of the GNU kernel, please call it ``the Hurd'' or ``the GNU Hurd''. +Note that this uses a space, not a slash. + + +@node Hosting +@chapter Hosting +@cindex CVS repository +@cindex repository +@cindex source repository +@cindex version control system +@cindex FTP site +@cindex release site +@cindex hosting + +We recommend using @code{savannah.gnu.org} for the source code +repository for your package, but that's not required. @xref{Old +Versions}, for more information about Savannah. + +We strongly urge you to use @code{ftp.gnu.org} as the standard +distribution site for releases. Doing so makes it easier for +developers and users to find the latest GNU releases. However, it is +ok to use another server if you wish, provided it allows access from +the general public without limitation (for instance, without excluding +any country). + +If you use a company's machine to hold the repository for your +program, or as its release distribution site, please put this +statement in a prominent place on the site, so as to prevent people +from getting the wrong idea about the relationship between the package +and the company: + +@smallexample +The programs <list of them> hosted here are free software packages +of the GNU Project, not products of <company name>. We call them +"free software" because you are free to copy and redistribute them, +following the rules stated in the license of each package. For more +information, see http://www.gnu.org/philosophy/free-sw.html. + +If you are looking for service or support for GNU software, see +http://www.gnu.org/gethelp/ for suggestions of where to ask. + +If you would like to contribute to the development of one of these +packages, contact the package maintainer or the bug-reporting address +of the package (which should be listed in the package itself), or look +on www.gnu.org for more information on how to contribute. +@end smallexample + + +@node Donations +@chapter Donations +@cindex Donations, for packages +@cindex Money, donated to packages + +As a maintainer, you might want to accept donations for your work, +especially if you pay for any of your own hosting/development +infrastructure. Following is some text you can adapt to your own +situation, and use on your package's web site, @file{README}, or +in wherever way you find it useful: + +@smallexample +We appreciate contributions of any size -- donations enable us to spend +more time working on the project, and help cover our infrastructure +expenses. + +If you'd like to make a small donation, please visit @var{url1} and do +it through @var{payment-service}. Since our project isn't a +tax-exempt organization, we can't offer you a tax deduction, but for +all donations over @var{amount1}, we'd be happy to recognize your +contribution on @var{url2}. + +We are also happy to consider making particular improvements or +changes, or giving specific technical assistance, in return for a +substantial donation over @var{amount2}. If you would like to discuss +this possibility, write to us at @var{address}. + +Another possibility is to pay a software maintenance fee. Again, +write to us about this at @var{address} to discuss how much you want +to pay and how much maintenance we can offer in return. If you pay +more than @var{amount1}, we can give you a document for your records. + +Thanks for your support! +@end smallexample + +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. + +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. + + +@node Free Software Directory +@chapter Free Software Directory +@cindex Free Software Directory +@cindex Directory, Free Software + +The Free Software Directory aims to be a complete list of free +software packages, within certain criteria. Every GNU package should +be listed there, so please see +@url{http://www.gnu.org/help/directory.html#adding-entries} for +information on how to write an entry for your package. Contact +@email{bug-directory@@gnu.org} with any questions or suggestions for +the Free Software Directory. + + +@node Using the Proofreaders List +@chapter Using the Proofreaders List +@cindex proofreading + +If you want help finding errors in documentation, +or help improving the quality of writing, +or if you are not a native speaker of English +and want help producing good English documentation, +you can use the GNU proofreaders mailing list: +@email{proofreaders@@gnu.org}. + +But be careful when you use the list, +because there are over 200 people on it. +If you simply ask everyone on the list to read your work, +there will probably be tremendous duplication of effort +by the proofreaders, +and you will probably get the same errors reported 100 times. +This must be avoided. + +Also, the people on the list do not want to get +a large amount of mail from it. +So do not ever ask people on the list to send mail to the list! + +Here are a few methods that seem reasonable to use: + +@itemize @bullet +@item +For something small, mail it to the list, +and ask people to pick a random number from 1 to 20, +and read it if the number comes out as 10. +This way, assuming 50% response, some 5 people will read the piece. + +@item +For a larger work, divide your work into around 20 equal-sized parts, +tell people where to get it, +and ask each person to pick randomly which part to read. + +Be sure to specify the random choice procedure; +otherwise people will probably use a mental procedure +that is not really random, +such as ``pick a part near the middle'', +and you will not get even coverage. + +You can either divide up the work physically, into 20 separate files, +or describe a virtual division, such as by sections +(if your work has approximately 20 sections). +If you do the latter, be sure to be precise about it---for example, +do you want the material before the first section heading +to count as a section, or not? + +@item +For a job needing special skills, send an explanation of it, +and ask people to send you mail if they volunteer for the job. +When you get enough volunteers, send another message to the list saying +``I have enough volunteers, no more please.'' +@end itemize + + +@node GNU Free Documentation License +@appendix GNU Free Documentation License + +@cindex FDL, GNU Free Documentation License +@include fdl.texi + + +@node Index +@unnumbered Index +@printindex cp + +@bye + +Local variables: +eval: (add-hook 'write-file-hooks 'time-stamp) +time-stamp-start: "@set lastupdate " +time-stamp-start: "@set lastupdate " +time-stamp-end: "$" +time-stamp-format: "%:b %:d, %:y" +compile-command: "make -C work.m" +End: |