1 \input texinfo.tex @c -*-texinfo-*-
3 @setfilename maintain.info
4 @settitle Information for Maintainers of GNU Software
5 @c For double-sided printing, uncomment:
6 @c @setchapternewpage odd
7 @c This date is automagically updated when you save this file:
8 @set lastupdate May 17, 2012
11 @dircategory GNU organization
13 * Maintaining: (maintain). Maintaining GNU software.
16 @setchapternewpage off
18 @c Put everything in one index (arbitrarily chosen to be the concept index).
23 Information for maintainers of GNU software, last updated @value{lastupdate}.
25 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
26 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
27 2010, 2011, 2012 Free Software Foundation, Inc.
30 Permission is granted to copy, distribute and/or modify this document
31 under the terms of the GNU Free Documentation License, Version 1.3 or
32 any later version published by the Free Software Foundation; with no
33 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
34 Texts. A copy of the license is included in the section entitled
35 ``GNU Free Documentation License''.
40 @title Information for Maintainers of GNU Software
41 @author Richard Stallman
42 @author last updated @value{lastupdate}
44 @vskip 0pt plus 1filll
60 * GNU Accounts and Resources::
62 * Recruiting Developers::
70 * Ethical and Philosophical Consideration::
72 * Interviews and Speeches::
75 * Free Software Directory::
76 * Using the Proofreaders List::
77 * GNU Free Documentation License::
83 @chapter About This Document
85 This file contains guidelines and advice for someone who is the
86 maintainer of a GNU program on behalf of the GNU Project. Everyone is
87 entitled to change and redistribute GNU software; you need not pay
88 attention to this file to get permission. But if you want to maintain
89 a version for widespread distribution, we suggest you follow these
90 guidelines. If you are or would like to be a GNU maintainer, then it
91 is essential to follow these guidelines.
93 In addition to this document, please read and follow the GNU Coding
94 Standards (@pxref{Top, , Contents, standards, GNU Coding Standards}).
96 @cindex @code{bug-standards@@gnu.org} email address
97 @cindex Savannah repository for @code{gnustandards}
98 @cindex @code{gnustandards} project repository
99 Please send corrections or suggestions for this document to
100 @email{bug-standards@@gnu.org}. If you make a suggestion, please
101 include suggested new wording if you can. We prefer a context diff to
102 the Texinfo source, but if that's difficult for you, you can make a
103 diff for some other version of this document, or propose it in any way
104 that makes it clear. The source repository for this document can be
105 found at @url{http://savannah.gnu.org/projects/gnustandards}.
107 @cindex @code{gnustandards-commit@@gnu.org} mailing list
108 If you want to receive diffs for every change to these GNU documents,
109 join the mailing list @code{gnustandards-commit@@gnu.org}, for
110 instance via the web interface at
111 @url{http://lists.gnu.org/mailman/listinfo/gnustandards-commit}.
112 Archives are also available there.
114 @cindex Piercy, Marge
115 This document uses the gender-neutral third-person pronouns ``person'',
116 ``per'', ``pers'' and ``perself'' which were promoted, and perhaps
117 invented, by Marge Piercy in @cite{Woman on the Edge of Time}. They are
118 used just like ``she'', ``her'', ``hers'' and ``herself'', except that
119 they apply equally to males and females. For example, ``Person placed
120 per new program under the GNU GPL, to let the public benefit from per
121 work, and to enable per to feel person has done the right thing.''
123 This release of the GNU Maintainer Information was last updated
128 @chapter Getting Help
129 @cindex help, getting
131 @cindex @code{mentors@@gnu.org} mailing list
132 If you have any general questions or encounter a situation where it
133 isn't clear how to get something done or who to ask, you (as a GNU
134 contributor) can always write to @email{mentors@@gnu.org}, which is a
135 list of a few experienced GNU folks who have volunteered to answer
136 questions. Any GNU-related question is fair game for the
139 @cindex advisory committee
140 The GNU Advisory Committee helps to coordinate activities in the GNU
141 project on behalf of RMS (Richard Stallman, the Chief GNUisance). If
142 you have any organizational questions or concerns you can contact the
143 committee at @email{gnu-advisory@@gnu.org}. See
144 @url{http://www.gnu.org/contact/gnu-advisory.html} for the current
145 committee members. Additional information is in
146 @file{/gd/gnuorg/advisory}.
148 @cindex down, when GNU machines are
149 @cindex outage, of GNU machines
150 @cindex @url{http://identi.ca/group/fsfstatus}
151 If you find that any GNU computer systems (@code{fencepost.gnu.org},
152 @code{ftp.gnu.org}, @code{www.gnu.org}, @code{savannah.gnu.org},
153 @dots{}) seem to be down, you can check the current status at
154 @url{http://identi.ca/group/fsfstatus}. Most likely the problem, if
155 it can be alleviated at the FSF end, is already being worked on.
157 @cindex sysadmin, FSF
158 @cindex FSF system administrators
159 @cindex GNU system administrators
160 The FSF system administrators are responsible for the network and GNU
161 hardware. You can email them at @email{sysadmin@@fsf.org}, but please
162 try not to burden them unnecessarily.
165 @node GNU Accounts and Resources
166 @chapter GNU Accounts and Resources
167 @cindex shell account, on fencepost
168 @cindex @code{fencepost.gnu.org} GNU login host
169 @cindex resources for GNU developers
170 @cindex development resources
172 @c We want to repeat this text later, so define a macro.
174 The directory @file{/gd/gnuorg} mentioned throughout this document is
175 available on the general GNU server, currently
176 @code{fencepost.gnu.org}. If you are the maintainer of a GNU package,
177 you should have an account there. If you don't have one already,
178 @url{http://www.gnu.org/software/README.accounts.html}. You can also
179 ask for accounts for people who significantly help you in working on
185 Other resources available to GNU maintainers are described at
186 @url{http://www.gnu.org/software/devel.html}, as well as throughout
187 this document. In brief:
190 @item Login accounts (see above).
192 @item Version control (@pxref{Old Versions}).
194 @item Mailing lists (@pxref{Mail}).
196 @item Web pages (@pxref{Web Pages}).
198 @item Mirrored release areas (@pxref{Distributions}).
201 @cindex @code{platform-testers} mailing list
202 @item Pre-release portability testing, both automated (via Hydra) and
203 on request (via volunteers).
209 @chapter Stepping Down
210 @cindex stepping down as maintainer
211 @cindex resigning as maintainer
213 With good fortune, you will continue maintaining your package for many
214 decades. But sometimes for various reasons maintainers decide to step
217 If you're the official maintainer of a GNU package and you decide to
218 step down, please inform the GNU Project (@email{maintainers@@gnu.org}).
219 We need to know that the package no longer has a maintainer, so we can
220 look for and appoint a new maintainer.
222 @cindex @email{maintainers@@gnu.org}
223 If you have an idea for who should take over, please tell
224 @email{maintainers@@gnu.org} your suggestion. The appointment of a new
225 maintainer needs the GNU Project's confirmation, but your judgment that
226 a person is capable of doing the job will carry a lot of weight.
228 As your final act as maintainer, it would be helpful to set up or
229 update the package under @code{savannah.gnu.org} (@pxref{Old
230 Versions}). This will make it much easier for the new maintainer to
231 pick up where you left off and will ensure that the source tree is not
232 misplaced if it takes us a while to find a new maintainer.
235 @node Recruiting Developers
236 @chapter Recruiting Developers
238 Unless your package is a fairly small, you probably won't do all the
239 work on it yourself. Most maintainers recruit other developers to help.
241 Sometimes people will offer to help. Some of them will be capable,
242 while others will not. It's up to you to determine who provides useful
243 help, and encourage those people to participate more.
245 Some of the people who offer to help will support the GNU Project, while
246 others may be interested for other reasons. Some will support the goals
247 of the Free Software Movement, but some may not. They are all welcome
248 to help with the work---we don't ask people's views or motivations
249 before they contribute to GNU packages.
251 As a consequence, you cannot expect all contributors to support the GNU
252 Project, or to have a concern for its policies and standards. So part
253 of your job as maintainer is to exercise your authority on these points
254 when they arise. No matter how much of the work other people do, you
255 are in charge of what goes in the release. When a crucial point arises,
256 you should calmly state your decision and stick to it.
258 Sometimes a package has several co-maintainers who share the role of
259 maintainer. Unlike developers who help, co-maintainers have actually
260 been appointed jointly as the maintainers of the package, and they carry
261 out the maintainer's functions together. If you would like to propose
262 some of your developers as co-maintainers, please contact
263 @email{maintainers@@gnu.org}.
265 We're happy to acknowledge all major contributors to GNU packages on
266 the @url{http://www.gnu.org/people/people.html} web page. Please send
267 an entry for yourself to @email{webmasters@@gnu.org}, and feel free to
268 suggest it to other significant developers on your package.
272 @chapter Legal Matters
273 @cindex legal matters
275 This chapter describes procedures you should follow for legal reasons
276 as you maintain the program, to avoid legal difficulties.
280 * Legally Significant::
281 * Recording Contributors::
282 * Copying from Other Packages::
283 * Copyright Notices::
285 * External Libraries::
288 @node Copyright Papers
289 @section Copyright Papers
290 @cindex copyright papers
291 @cindex assignments, copyright
294 If you maintain an FSF-copyrighted package
295 certain legal procedures are required when incorporating legally significant
296 changes written by other people. This ensures that the FSF has the
297 legal right to distribute the package, and the standing to defend its
298 GPL-covered status in court if necessary.
300 @strong{Before} incorporating significant changes, make sure that the
301 person who wrote the changes has signed copyright papers and that the
302 Free Software Foundation has received and signed them. We may also
303 need an employer's disclaimer from the person's employer, which
304 confirms that the work was not part of the person's job and the
305 employer makes no claim on it. However, a copy of the person's
306 employment contract, showing that the employer can't claim any rights
307 to this work, is often sufficient.
309 If the employer does claim the work was part of the person's job, and
310 there is no clear basis to say that claim is invalid, then we have to
311 consider it valid. Then the person cannot assign copyright, but the
312 employer can. Many companies have done this. Please ask the
313 appropriate managers to contact @code{assign@@gnu.org}.
315 @cindex data base of GNU copyright assignments
316 To check whether papers have been received, look in
317 @file{/gd/gnuorg/copyright.list}. If you can't look there directly,
318 @email{fsf-records@@gnu.org} can check for you. Our clerk can also
319 check for papers that are waiting to be entered and inform you when
320 expected papers arrive.
322 @cindex @file{/gd/gnuorg} directory
323 @c This paragraph intentionally duplicates information given
324 @c near the beginning of the file--to make sure people don't miss it.
327 In order for the contributor to know person should sign papers, you need
328 to ask per for the necessary papers. If you don't know per well, and you
329 don't know that person is used to our ways of handling copyright papers,
330 then it might be a good idea to raise the subject with a message like
334 Would you be willing to assign the copyright to the Free Software
335 Foundation, so that we could install it in @var{package}?
342 Would you be willing to sign a copyright disclaimer to put this change
343 in the public domain, so that we can install it in @var{package}?
346 If the contributor then wants more information, you can send per the file
347 @file{/gd/gnuorg/conditions.text}, which explains per options (assign
348 vs.@: disclaim) and their consequences.
350 Once the conversation is under way and the contributor is ready for
351 more details, you should send one of the templates that are found in
352 the directory @file{/gd/gnuorg/Copyright/}; they are also available
353 from the @file{doc/Copyright/} directory of the @code{gnulib} project
354 at @url{http://savannah.gnu.org/projects/gnulib}. This section
355 explains which templates you should use in which circumstances.
356 @strong{Please don't use any of the templates except for those listed
357 here, and please don't change the wording.}
359 Once the conversation is under way, you can send the contributor the
360 precise wording and instructions by email. Before you do this, make
361 sure to get the current version of the template you will use! We change
362 these templates occasionally---don't keep using an old version.
364 For large changes, ask the contributor for an assignment. Send per a
365 copy of the file @file{request-assign.changes}. (Like all the
366 @samp{request-} files, it is in @file{/gd/gnuorg/Copyright} and in
369 For medium to small changes, request a personal disclaimer by sending
370 per the file @file{request-disclaim.changes}.
372 If the contributor is likely to keep making changes, person might want
373 to sign an assignment for all per future changes to the program. So it
374 is useful to offer per that alternative. If person wants to do it that
375 way, send per the @file{request-assign.future}.
377 When you send a @file{request-} file, you don't need to fill in anything
378 before sending it. Just send the file verbatim to the contributor. The
379 file gives per instructions for how to ask the FSF to mail per the
380 papers to sign. The @file{request-} file also raises the issue of
381 getting an employer's disclaimer from the contributor's employer.
383 When the contributor emails the form to the FSF, the FSF sends per an
384 electronic (usually PDF) copy of the assignment. This, or whatever
385 response is required, should happen within five business days of the
386 initial request. If no reply from the FSF comes after that time,
387 please send a reminder. If you still get no response after an
388 additional week, please write to @email{maintainers@@gnu.org} about it.
390 After receiving the necessary form, all contributors then print it and
391 sign it. Contributors residing outside the U.S. must mail the signed
392 form to the FSF via the post. Contributors located in the U.S. can
393 then email or fax a scanned copy back to the FSF (or use postal mail,
394 if they prefer). (To emphasize, the necessary distinction is between
395 US residents and non-residents; citizenship does not matter.)
397 For less common cases, we have template files you should send to the
398 contributor. Be sure to fill in the name of the person and the name
399 of the program in these templates, where it says @samp{NAME OF PERSON}
400 and @samp{NAME OF PROGRAM}, before sending; otherwise person might
401 sign without noticing them, and the papers would be useless. Note
402 that in some templates there is more than one place to put the name of
403 the program or the name of the person; be sure to change all of them.
404 All the templates raise the issue of an employer's disclaimer as well.
406 @cindex legal papers for changes in manuals
407 You do not need to ask for separate papers for a manual that is
408 distributed only in the software package it describes. But if we
409 sometimes distribute the manual separately (for instance, if we publish
410 it as a book), then we need separate legal papers for changes in the
411 manual. For smaller changes, use
412 @file{disclaim.changes.manual}; for larger ones, use
413 @file{assign.changes.manual}. To cover both past and future
414 changes to a manual, you can use @file{assign.future.manual}.
415 For a translation of a manual, use @file{assign.translation.manual}.
417 For translations of program strings (as used by GNU Gettext, for
418 example; @pxref{Internationalization,,, standards, GNU Coding
419 Standards}), use @file{disclaim.translation}. If you make use of the
420 Translation Project (@url{http://translationproject.org}) facilities,
421 please check with the TP coordinators that they have sent the
422 contributor the papers; if they haven't, then you should send the
423 papers. In any case, you should wait for the confirmation from the
424 FSF that the signed papers have been received and accepted before
425 integrating the new contributor's material, as usual.
427 If a contributor is reluctant to sign an assignment for a large change,
428 and is willing to sign a disclaimer instead, that is acceptable, so you
429 should offer this alternative if it helps you reach agreement. We
430 prefer an assignment for a larger change, so that we can enforce the GNU
431 GPL for the new text, but a disclaimer is enough to let us use the text.
433 If you maintain a collection of programs, occasionally someone will
434 contribute an entire separate program or manual that should be added to
435 the collection. Then you can use the files
436 @file{request-assign.program}, @file{disclaim.program},
437 @file{assign.manual}, and @file{disclaim.manual}. We very much prefer
438 an assignment for a new separate program or manual, unless it is quite
439 small, but a disclaimer is acceptable if the contributor insists on
440 handling the matter that way.
442 If a contributor wants the FSF to publish only a pseudonym, that is
443 ok. The contributor should say this, and state the desired pseudonym,
444 when answering the @file{request-} form. The actual legal papers will
445 use the real name, but the FSF will publish only the pseudonym. When
446 using one of the other forms, fill in the real name but ask the
447 contributor to discuss the use of a pseudonym with
448 @email{assign@@gnu.org} before sending back the signed form.
450 @strong{Although there are other templates besides the ones listed here,
451 they are for special circumstances; please do not use them without
452 getting advice from @email{assign@@gnu.org}.}
454 If you are not sure what to do, then please ask @email{assign@@gnu.org} for
455 advice; if the contributor asks you questions about the meaning and
456 consequences of the legal papers, and you don't know the answers, you
457 can forward them to @email{assign@@gnu.org} and we will answer.
459 @strong{Please do not try changing the wording of a template yourself.
460 If you think a change is needed, please talk with @email{assign@@gnu.org},
461 and we will work with a lawyer to decide what to do.}
463 @node Legally Significant
464 @section Legally Significant Changes
466 If a person contributes more than around 15 lines of code and/or text
467 that is legally significant for copyright purposes, we
468 need copyright papers for that contribution, as described above.
470 A change of just a few lines (less than 15 or so) is not legally
471 significant for copyright. A regular series of repeated changes, such
472 as renaming a symbol, is not legally significant even if the symbol
473 has to be renamed in many places. Keep in mind, however, that a
474 series of minor changes by the same person can add up to a significant
475 contribution. What counts is the total contribution of the person; it
476 is irrelevant which parts of it were contributed when.
478 Copyright does not cover ideas. If someone contributes ideas but no
479 text, these ideas may be morally significant as contributions, and
480 worth giving credit for, but they are not significant for copyright
481 purposes. Likewise, bug reports do not count for copyright purposes.
483 When giving credit to people whose contributions are not legally
484 significant for copyright purposes, be careful to make that fact
485 clear. The credit should clearly say they did not contribute
486 significant code or text.
488 When people's contributions are not legally significant because they
489 did not write code, do this by stating clearly what their contribution
490 was. For instance, you could write this:
495 * Richard Mlynarik <mly@@adoc.xerox.com> (1997)
496 * Masatake Yamato <masata-y@@is.aist-nara.ac.jp> (1999)
501 @code{Ideas by:} makes it clear that Mlynarik and Yamato here
502 contributed only ideas, not code. Without the @code{Ideas by:} note,
503 several years from now we would find it hard to be sure whether they
504 had contributed code, and we might have to track them down and ask
507 When you record a small patch in a change log file, first search for
508 previous changes by the same person, and see if per past
509 contributions, plus the new one, add up to something legally
510 significant. If so, you should get copyright papers for all per
511 changes before you install the new change.
513 If that is not so, you can install the small patch. Write @samp{(tiny
514 change)} after the patch author's name, like this:
517 2002-11-04 Robert Fenk <Robert.Fenk@@gmx.de> (tiny change)
520 @node Recording Contributors
521 @section Recording Contributors
522 @cindex recording contributors
524 @strong{Keep correct records of which portions were written by whom.}
525 This is very important. These records should say which files or
526 parts of files were written by each person, and which files or
527 parts of files were revised by each person. This should include
528 installation scripts as well as manuals and documentation
531 These records don't need to be as detailed as a change log. They
532 don't need to distinguish work done at different times, only different
533 people. They don't need describe changes in more detail than which
534 files or parts of a file were changed. And they don't need to say
535 anything about the function or purpose of a file or change---the
536 Register of Copyrights doesn't care what the text does, just who wrote
537 or contributed to which parts.
539 The list should also mention if certain files distributed in the same
540 package are really a separate program.
542 Only the contributions that are legally significant for copyright
543 purposes (@pxref{Legally Significant}) need to be listed. Small
544 contributions, bug reports, ideas, etc., can be omitted.
546 For example, this would describe an early version of GAS:
549 Dean Elsner first version of all files except gdb-lines.c and m68k.c.
550 Jay Fenlason entire files gdb-lines.c and m68k.c, most of app.c,
551 plus extensive changes in messages.c, input-file.c, write.c
552 and revisions elsewhere.
554 Note: GAS is distributed with the files obstack.c and obstack.h, but
555 they are considered a separate package, not part of GAS proper.
558 @cindex @file{AUTHORS} file
559 Please keep these records in a file named @file{AUTHORS} in the source
560 directory for the program itself.
562 You can use the change log as the basis for these records, if you
563 wish. Just make sure to record the correct author for each change
564 (the person who wrote the change, @emph{not} the person who installed
565 it), and add @samp{(tiny change)} for those changes that are too
566 trivial to matter for copyright purposes. Later on you can update the
567 @file{AUTHORS} file from the change log. This can even be done
568 automatically, if you are careful about the formatting of the change
571 It is ok to include other email addresses, names, and program
572 information in @file{AUTHORS}, such as bug-reporting information.
573 @xref{Standard Mailing Lists}.
576 @node Copying from Other Packages
577 @section Copying from Other Packages
579 This section explains legal considerations when merging code from
580 other packages into your package. Using an entire module as a whole,
581 and maintaining its separate identity, is a different issue;
582 see @ref{External Libraries}.
585 * Non-FSF-Copyrighted Package::
586 * FSF-Copyrighted Package::
589 @node Non-FSF-Copyrighted Package
590 @subsection Non-FSF-Copyrighted Package
592 Here we suppose that your package is not FSF-copyrighted.
594 When you copy legally significant code from another free software
595 package with a GPL-compatible license, you should look in the
596 package's records to find out the authors of the part you are copying,
597 and list them as the contributors of the code that you copied. If all
598 you did was copy it, not write it, then for copyright purposes you are
599 @emph{not} one of the contributors of @emph{this} code.
601 If the code is supposed to be in the public domain, make sure that is
602 really true: that all the authors of the code have disclaimed
603 copyright interest. Then, when copying the new files into your
604 project, add a brief note at the beginning of the files recording the
605 authors, the public domain status, and anything else relevant.
607 On the other hand, when merging some public domain code into an
608 existing file covered by the GPL (or LGPL or other free software
609 license), there is no reason to indicate the pieces which are public
610 domain. The notice saying that the whole file is under the GPL (or
611 other license) is legally sufficient.
613 Using code that is not in the public domain, but rather released under
614 a GPL-compatible free license, may require preserving copyright
615 notices or other steps. Of course, you should follow the requirements
618 @node FSF-Copyrighted Package
619 @subsection FSF-Copyrighted Package
621 If you are maintaining an FSF-copyrighted package, please don't copy
622 in any code without verifying first that we have suitable legal papers
625 If you are copying from another FSF-copyrighted package, then we
626 presumably have papers for that package's own code, but you must check
627 whether the code you are copying is part of an external library; if
628 that is the case, we don't have papers for it, so you should not copy
629 it. It can't hurt in any case to double-check with the developer of
632 When you are copying code for which we do not already have papers, you
633 need to get papers for it. It may be difficult to get the papers if
634 the code was not written as a contribution to your package, but that
635 doesn't mean it is ok to do without them. If you cannot get papers
636 for the code, you can only use it as an external library
637 (@pxref{External Libraries}).
640 @node Copyright Notices
641 @section Copyright Notices
642 @cindex copyright notices in program files
644 You should maintain a proper copyright notice and a license
645 notice in each nontrivial file in the package. (Any file more than ten
646 lines long is nontrivial for this purpose.) This includes header files
647 and interface definitions for
648 building or running the program, documentation files, and any supporting
649 files. If a file has been explicitly placed in the public domain, then
650 instead of a copyright notice, it should have a notice saying explicitly
651 that it is in the public domain.
653 Even image files and sound files should contain copyright notices and
654 license notices, if their format permits. Some formats do not have
655 room for textual annotations; for these files, state the copyright and
656 copying permissions in a @file{README} file in the same directory.
658 Change log files should have a copyright notice and license notice at
659 the end, since new material is added at the beginning but the end
662 When a file is automatically generated from some other file in the
663 distribution, it is useful for the automatic procedure to copy the
664 copyright notice and permission notice of the file it is generated
665 from, if possible. Alternatively, put a notice at the beginning saying
666 which file it is generated from.
668 A copyright notice looks like this:
671 Copyright (C) @var{year1}, @var{year2}, @var{year3} @var{copyright-holder}
674 The word @samp{Copyright} must always be in English, by international
677 The @var{copyright-holder} may be the Free Software Foundation, Inc., or
678 someone else; you should know who is the copyright holder for your
681 Replace the @samp{(C)} with a C-in-a-circle symbol if it is available.
682 For example, use @samp{@@copyright@{@}} in a Texinfo file. However,
683 stick with parenthesized @samp{C} unless you know that C-in-a-circle
684 will work. For example, a program's standard @option{--version}
685 message should use parenthesized @samp{C} by default, though message
686 translations may use C-in-a-circle in locales where that symbol is
687 known to work. Alternatively, the @samp{(C)} or C-in-a-circle can be
688 omitted entirely; the word @samp{Copyright} suffices.
690 To update the list of year numbers, add each year in which you have
691 made nontrivial changes to the package. (Here we assume you're using
692 a publicly accessible revision control server, so that every revision
693 installed is also immediately and automatically published.) When you
694 add the new year, it is not required to keep track of which files have
695 seen significant changes in the new year and which have not. It is
696 recommended and simpler to add the new year to all files in the
697 package, and be done with it for the rest of the year.
699 Don't delete old year numbers, though; they are significant since they
700 indicate when older versions might theoretically go into the public
701 domain, if the movie companies don't continue buying laws to further
702 extend copyright. If you copy a file into the package from some other
703 program, keep the copyright years that come with the file.
705 You can use a range (@samp{2008-2010}) instead of listing individual
706 years (@samp{2008, 2009, 2010}) if and only if: 1)@tie{}every year in
707 the range, inclusive, really is a ``copyrightable'' year that would be
708 listed individually; @emph{and} 2)@tie{}you make an explicit statement
709 in a @file{README} file about this usage.
711 For files which are regularly copied from another project (such as
712 @samp{gnulib}), leave the copyright notice as it is in the original.
714 The copyright statement may be split across multiple lines, both in
715 source files and in any generated output. This often happens for
716 files with a long history, having many different years of
719 For an FSF-copyrighted package, if you have followed the procedures to
720 obtain legal papers, each file should have just one copyright holder:
721 the Free Software Foundation, Inc. You should edit the file's
722 copyright notice to list that name and only that name.
724 But if contributors are not all assigning their copyrights to a single
725 copyright holder, it can easily happen that one file has several
726 copyright holders. Each contributor of nontrivial text is a copyright
729 In that case, you should always include a copyright notice in the name
730 of main copyright holder of the file. You can also include copyright
731 notices for other copyright holders as well, and this is a good idea
732 for those who have contributed a large amount and for those who
733 specifically ask for notices in their names. (Sometimes the license
734 on code that you copy in may require preserving certain copyright
735 notices.) But you don't have to include a notice for everyone who
736 contributed to the file (which would be rather inconvenient).
738 Sometimes a program has an overall copyright notice that refers to the
739 whole program. It might be in the @file{README} file, or it might be
740 displayed when the program starts up. This copyright notice should
741 mention the year of completion of the most recent major version; it
742 can mention years of completion of previous major versions, but that
746 @node License Notices
747 @section License Notices
748 @cindex license notices in program files
750 Every nontrivial file needs a license notice as well as the copyright
751 notice. (Without a license notice giving permission to copy and
752 change the file, the file is non-free.)
754 The package itself should contain a full copy of GPL in plain text
755 (conventionally in a file named @file{COPYING}) and the GNU Free
756 Documentation License (included within your documentation, so there is
757 no need for a separate plain text version). If the package contains
758 any files distributed under the Lesser GPL, it should contain a full
759 copy of its plain text version also (conventionally in a file named
760 @file{COPYING.LESSER}).
762 If you have questions about licensing issues for your GNU package,
763 please write @email{licensing@@gnu.org}.
766 * Which: Licensing of GNU Packages.
767 * Canonical: Canonical License Sources.
768 * Code: License Notices for Code.
769 * Documentation: License Notices for Documentation.
770 * Other: License Notices for Other Files.
774 @node Licensing of GNU Packages
775 @subsection Licensing of GNU Packages
777 Normally, GNU packages should use the latest version of the GNU GPL,
778 with the ``or any later version'' formulation. @xref{License Notices
779 for Code}, for the exact wording of the license notice.
781 Occasionally, a GNU library may provide functionality which is already
782 widely available to proprietary programs through alternative
783 implementations; for example, the GNU C Library. In such cases, the
784 Lesser GPL should be used (again, for the notice wording,
785 @pxref{License Notices for Code}). If a GNU library provides unique
786 functionality, however, the GNU GPL should be used.
787 @url{http://www.gnu.org/licenses/why-not-lgpl.html} discusses this
790 Some of these libraries need to work with programs released under
791 GPLv2-only; that is, which allow the GNU GPL version 2 but not later
792 versions. In this case, the GNU package should be released under a
793 dual license: GNU GPL version 2 (or any later version) and the GNU
794 Lesser GPL version 3 (or any later version). Here is the notice for
798 This file is part of GNU @var{package}.
800 GNU @var{package} is free software: you can redistribute it and/or
801 modify it under the terms of either:
803 * the GNU Lesser General Public License as published by the Free
804 Software Foundation; either version 3 of the License, or (at your
805 option) any later version.
809 * the GNU General Public License as published by the Free
810 Software Foundation; either version 2 of the License, or (at your
811 option) any later version.
813 or both in parallel, as here.
815 GNU @var{package} is distributed in the hope that it will be useful,
816 but WITHOUT ANY WARRANTY; without even the implied warranty of
817 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
818 General Public License for more details.
820 You should have received copies of the GNU General Public License and
821 the GNU Lesser General Public License along with this program. If
822 not, see @url{http://www.gnu.org/licenses/}.
825 For small packages, you can use ``This program'' instead of ``GNU
829 @node Canonical License Sources
830 @subsection Canonical License Sources
832 You can get the official versions of these files from several places.
833 You can use whichever is the most convenient for you.
837 @uref{http://www.gnu.org/licenses/}.
840 The @code{gnulib} project on @code{savannah.gnu.org}, which you
841 can access via anonymous Git or CVS. See
842 @uref{http://savannah.gnu.org/projects/gnulib}.
846 The official Texinfo sources for the licenses are also available in
847 those same places, so you can include them in your documentation. A
848 GFDL-covered manual should include the GFDL in this way. @xref{GNU
849 Sample Texts,,, texinfo, Texinfo}, for a full example in a Texinfo
853 @node License Notices for Code
854 @subsection License Notices for Code
856 Typically the license notice for program files (including build scripts,
857 configure files and makefiles) should cite the GPL, like this:
860 This file is part of GNU @var{package}.
862 GNU @var{package} is free software: you can redistribute it and/or
863 modify it under the terms of the GNU General Public License as
864 published by the Free Software Foundation, either version 3 of the
865 License, or (at your option) any later version.
867 GNU @var{package} is distributed in the hope that it will be useful,
868 but WITHOUT ANY WARRANTY; without even the implied warranty of
869 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
870 GNU General Public License for more details.
872 You should have received a copy of the GNU General Public License
873 along with this program. If not, see @url{http://www.gnu.org/licenses/}.
876 But in a small program which is just a few files, you can use
880 This program is free software: you can redistribute it and/or modify
881 it under the terms of the GNU General Public License as published by
882 the Free Software Foundation; either version 3 of the License, or
883 (at your option) any later version.
885 This program is distributed in the hope that it will be useful,
886 but WITHOUT ANY WARRANTY; without even the implied warranty of
887 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
888 GNU General Public License for more details.
890 You should have received a copy of the GNU General Public License
891 along with this program. If not, see @url{http://www.gnu.org/licenses/}.
894 In either case, for those few packages which use the Lesser GPL
895 (@pxref{Licensing of GNU Packages}), insert the word ``Lesser'' before
896 ``General'' in @emph{all three} places.
897 @url{http://@/www.gnu.org/@/licenses/@/gpl-howto.html} discusses application
898 the GPL in more detail.
901 @node License Notices for Documentation
902 @subsection License Notices for Documentation
904 Documentation files should have license notices also. Manuals should
905 use the GNU Free Documentation License. Following is an example of the
906 license notice to use after the copyright line(s) using all the
907 features of the GFDL.
910 Permission is granted to copy, distribute and/or modify this document
911 under the terms of the GNU Free Documentation License, Version 1.3 or
912 any later version published by the Free Software Foundation; with the
913 Invariant Sections being ``GNU General Public License'', with the
914 Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts
915 as in (a) below. A copy of the license is included in the section
916 entitled ``GNU Free Documentation License''.
918 (a) The FSF's Back-Cover Text is: ``You have the freedom to
919 copy and modify this GNU manual. Buying copies from the FSF
920 supports it in developing GNU and promoting software freedom.''
923 If the FSF does not publish this manual on paper, then omit the last
924 sentence in (a) that talks about copies from GNU Press. If the FSF is
925 not the copyright holder, then replace @samp{FSF} with the appropriate
928 Please adjust the list of invariant sections as appropriate for your
929 manual. If there are none, then say ``with no Invariant Sections''.
930 If your manual is not published by the FSF, and under 400 pages, you
931 can omit both cover texts.
933 @xref{GNU Sample Texts,,, texinfo, Texinfo}, for a full example in a
934 Texinfo manual, and see
935 @url{http://www.gnu.org/licenses/fdl-howto.html} for more advice about
936 how to use the GNU FDL.
938 If you write a manual that people might want to buy on paper, please
939 write to @email{maintainers@@gnu.org} to tell the FSF about it. We
940 might want to publish it.
942 If the manual is over 400 pages, or if the FSF thinks it might be a
943 good choice for publishing on paper, then please include the GNU GPL,
944 as in the notice above. Please also include our standard invariant
945 section which explains the importance of free documentation. Write to
946 @email{assign@@gnu.org} to get a copy of this section.
948 When you distribute several manuals together in one software package,
949 their on-line forms can share a single copy of the GFDL (see
950 section@tie{}6). However, the printed (@samp{.dvi}, @samp{.pdf},
951 @dots{}) forms should each contain a copy of the GFDL, unless they are
952 set up to be printed and published only together. Therefore, it is
953 usually simplest to include the GFDL in each manual.
956 @node License Notices for Other Files
957 @subsection License Notices for Other Files
959 Small supporting files, short manuals (under 300 lines long) and rough
960 documentation (@file{README} files, @file{INSTALL} files, etc.)@: can
961 use a simple all-permissive license like this one:
964 Copying and distribution of this file, with or without modification,
965 are permitted in any medium without royalty provided the copyright
966 notice and this notice are preserved. This file is offered as-is,
967 without any warranty.
970 Older versions of this license did not have the second sentence with
971 the express warranty disclaimer. There is no urgent need to update
972 existing files, but new files should use the new text.
974 If your package distributes Autoconf macros that are intended to be
975 used (hence distributed) by third-party packages under possibly
976 incompatible licenses, you may also use the above all-permissive
977 license for these macros.
980 @node External Libraries
981 @section External Libraries
983 When maintaining an FSF-copyrighted GNU package, you may occasionally
984 want to use a general-purpose free software module which offers a
985 useful functionality, as a ``library'' facility (though the module is
986 not always packaged technically as a library).
988 Make sure the license of the module is compatible with current @emph{and
989 future} GPL versions. ``GNU GPL version 3 or later'' is good, and
990 so is anything which includes permission for use under those GPL
991 versions (including ``GNU GPL version 2 or later'', ``LGPL version
992 @var{n} or later'', ``LGPL version 2.1'', ``GNU Affero GPL version 3
993 or later''). Lax permissive licenses are ok too, since they are
994 compatible with all GPL versions.
996 ``GPL version 2 only'' is obviously unacceptable because it is
997 incompatble with GPL version 3. ``GPL version 3 only'' and ``GPL
998 version 2 or 3 only'' have a subtler problem: they will be incompatble
999 with GPL version 4, if we ever make one, so the module would become an
1000 obstacle to upgrading your package's license to ``GPL version 4 or
1003 One package you need to avoid is @code{goffice}, since it allows only
1004 GPL versions 2 and 3.
1006 It would be unreasonable to ask the author of the external module to
1007 assign its the copyright to the FSF. After all, person did not write
1008 it specifically as a contribution to your package, so it would be
1009 impertinent to ask per, out of the blue, ``Please give the FSF your
1012 So make your program use the module but without treating the module as
1013 a part of your program. There are two reasonable methods of doing
1018 Assume the module is already installed on the system, and use it when
1019 linking your program. This is only reasonable if the module really has
1020 the form of a library.
1023 Include the module in your package, putting the source in a separate
1024 subdirectory whose @file{README} file says, ``This is not part of the
1025 GNU FOO program, but is used with GNU FOO.'' Then set up your makefiles
1026 to build this module and link it into the executable.
1028 For this method, it is not necessary to treat the module as a library
1029 and make a @samp{.a} file from it. You can link with the @samp{.o}
1030 files directly in the usual manner.
1033 Both of these methods create an irregularity, and our lawyers have told
1034 us to minimize the amount of such irregularity. So consider using these
1035 methods only for general-purpose modules that were written for other
1036 programs and released separately for general use. For anything that was
1037 written as a contribution to your package, please get papers signed.
1041 @chapter Cleaning Up Changes
1042 @cindex contributions, accepting
1043 @cindex quality of changes suggested by others
1045 Don't feel obligated to include every change that someone asks you to
1046 include. You must judge which changes are improvements---partly based
1047 on what you think the users will like, and partly based on your own
1048 judgment of what is better. If you think a change is not good, you
1051 If someone sends you changes which are useful, but written in an ugly
1052 way or hard to understand and maintain in the future, don't hesitate to
1053 ask per to clean up their changes before you merge them. Since the
1054 amount of work we can do is limited, the more we convince others to help
1055 us work efficiently, the faster GNU will advance.
1057 If the contributor will not or can not make the changes clean enough,
1058 then it is legitimate to say ``I can't install this in its present form;
1059 I can only do so if you clean it up.'' Invite per to distribute per
1060 changes another way, or to find other people to make them clean enough
1061 for you to install and maintain.
1063 The only reason to do these cleanups yourself is if (1) it is easy, less
1064 work than telling the author what to clean up, or (2) the change is an
1065 important one, important enough to be worth the work of cleaning it up.
1067 The GNU Coding Standards are a good thing to send people when you ask
1068 them to clean up changes (@pxref{Top, , Contents, standards, GNU Coding
1069 Standards}). The Emacs Lisp manual contains an appendix that gives
1070 coding standards for Emacs Lisp programs; it is good to urge Lisp authors to
1071 read it (@pxref{Tips, , Tips and Conventions, elisp, The GNU Emacs Lisp
1076 @chapter Platforms to Support
1078 Most GNU packages run on a wide range of platforms. These platforms are
1079 not equally important.
1081 The most important platforms for a GNU package to support are GNU and
1082 GNU/Linux. Developing the GNU operating system is the whole point of
1083 the GNU Project; a GNU package exists to make the whole GNU system more
1084 powerful. So please keep that goal in mind and let it shape your work.
1085 For instance, every new feature you add should work on GNU, and
1086 GNU/Linux if possible too. If a new feature only runs on GNU and
1087 GNU/Linux, it could still be acceptable. However, a feature that runs
1088 only on other systems and not on GNU or GNU/Linux makes no sense in a
1091 You will naturally want to keep the program running on all the platforms
1092 it supports. But you personally will not have access to most of these
1093 platforms---so how should you do it?
1095 Don't worry about trying to get access to all of these platforms. Even
1096 if you did have access to all the platforms, it would be inefficient for
1097 you to test the program on each platform yourself. Instead, you should
1098 test the program on a few platforms, including GNU or GNU/Linux, and let
1099 the users test it on the other platforms. You can do this through a
1100 pretest phase before the real release; when there is no reason to expect
1101 problems, in a package that is mostly portable, you can just make a
1102 release and let the users tell you if anything unportable was
1105 It is important to test the program personally on GNU or GNU/Linux,
1106 because these are the most important platforms for a GNU package. If
1107 you don't have access to one of these platforms, as a GNU maintainer
1108 you can get access to the general GNU login machine; see
1109 @url{http://www.gnu.org/software/README.accounts.html}.
1111 Supporting other platforms is optional---we do it when that seems like
1112 a good idea, but we don't consider it obligatory. If the users don't
1113 take care of a certain platform, you may have to desupport it unless
1114 and until users come forward to help. Conversely, if a user offers
1115 changes to support an additional platform, you will probably want to
1116 install them, but you don't have to. If you feel the changes are
1117 complex and ugly, if you think that they will increase the burden of
1118 future maintenance, you can and should reject them. This includes
1119 both free or mainly-free platforms such as OpenBSD, FreeBSD, and
1120 NetBSD, and non-free platforms such as Windows.
1124 @chapter Dealing With Mail
1127 This chapter describes setting up mailing lists for your package, and
1128 gives advice on how to handle bug reports and random requests once you
1132 * Standard Mailing Lists:: @samp{bug-pkg@@gnu.org} and other standard names.
1133 * Creating Mailing Lists:: The best way is to use Savannah.
1134 * Replying to Mail:: Advice on replying to incoming mail.
1138 @node Standard Mailing Lists
1139 @section Standard Mailing Lists
1141 @cindex standard mailing lists
1142 @cindex mailing lists, standard names of
1144 @cindex mailing list for bug reports
1145 Once a program is in use, you will get bug reports for it. Most GNU
1146 programs have their own special lists for sending bug reports. The
1147 advertised bug-reporting email address should always be
1148 @samp{bug-@var{package}@@gnu.org}, to help show users that the program
1149 is a GNU package, but it is ok to set up that list to forward to another
1152 @cindex @email{bug-gnu-utils@@gnu.org}
1153 We also have a catch-all list, @email{bug-gnu-utils@@gnu.org}, which is
1154 used for all GNU programs that don't have their own specific lists. But
1155 nowadays we want to give each program its own bug-reporting list and
1156 move away from using @email{bug-gnu-utils}.
1158 @xref{Replying to Mail}, for more about handling and tracking bug
1161 @cindex help for users, mailing list for
1162 Some GNU programs with many users have another mailing list,
1163 @samp{help-@var{package}.org}, for people to ask other users for help.
1164 If your program has many users, you should create such a list for it.
1165 For a fairly new program, which doesn't have a large user base yet, it
1166 is better not to bother with this.
1168 @cindex announcements, mailing list for
1169 If you wish, you can also have a mailing list
1170 @samp{info-@var{package}} for announcements (@pxref{Announcements}).
1171 Any other mailing lists you find useful can also be created.
1173 The package distribution should state the name of all the package's
1174 mailing lists in a prominent place, and ask users to help us by
1175 reporting bugs appropriately. The top-level @file{README} file and/or
1176 @file{AUTHORS} file are good places. Mailing list information should
1177 also be included in the manual and the package web pages (@pxref{Web
1182 @node Creating Mailing Lists
1183 @section Creating Mailing Lists
1185 @cindex creating mailing lists
1186 @cindex mailing lists, creating
1188 Using the web interface on @code{savannah.gnu.org} is by far the
1189 easiest way to create normal mailing lists, managed through Mailman on
1190 the GNU mail server. Once you register your package on Savannah, you
1191 can create (and remove) lists yourself through the `Mailing Lists'
1192 menu, without needing to wait for intervention by anyone else.
1193 Furthermore, lists created through Savannah will have a reasonable
1194 default configuration for antispam purposes (see below).
1196 To create and maintain simple aliases and unmanaged lists, you can
1197 edit @file{/com/mailer/aliases} on the main GNU server. If you don't
1198 have an account there, please read
1199 @url{http://www.gnu.org/software/README.accounts.html} (@pxref{GNU
1200 Accounts and Resources}).
1202 But if you don't want to learn how to do those things, you can
1203 alternatively ask @email{alias-file@@gnu.org} to add you to the
1204 bug-reporting list for your program. To set up a new list, contact
1205 @email{new-mailing-list@@gnu.org}. You can subscribe to a list managed
1206 by Mailman by sending mail to the corresponding @samp{-request} address.
1208 @cindex spam prevention
1209 You should moderate postings from non-subscribed addresses on your
1210 mailing lists, to prevent propagation of unwanted messages (``spam'')
1211 to subscribers and to the list archives. For lists controlled by
1212 Mailman, you can do this by setting @code{Privacy Options - Sender
1213 Filter - generic_nonmember_action} to @code{Hold}, and then
1214 periodically (daily is best) reviewing the held messages, accepting
1215 the real ones and discarding the junk.
1217 Lists created through Savannah will have this setting, and a number of
1218 others, such that spam will be automatically deleted (after a short
1219 delay). The Savannah mailing list page describes all the details.
1220 You should still review the held messages in order to approve any that
1224 @node Replying to Mail
1225 @section Replying to Mail
1227 @cindex responding to bug reports
1228 @cindex bug reports, handling
1229 @cindex help requests, handling
1231 When you receive bug reports, keep in mind that bug reports are crucial
1232 for your work. If you don't know about problems, you cannot fix them.
1233 So always thank each person who sends a bug report.
1235 You don't have an obligation to give more response than that, though.
1236 The main purpose of bug reports is to help you contribute to the
1237 community by improving the next version of the program. Many of the
1238 people who report bugs don't realize this---they think that the point is
1239 for you to help them individually. Some will ask you to focus on that
1240 @emph{instead of} on making the program better. If you comply with
1241 their wishes, you will have been distracted from the job of maintaining
1244 For example, people sometimes report a bug in a vague (and therefore
1245 useless) way, and when you ask for more information, they say, ``I just
1246 wanted to see if you already knew the solution'' (in which case the bug
1247 report would do nothing to help improve the program). When this
1248 happens, you should explain to them the real purpose of bug reports. (A
1249 canned explanation will make this more efficient.)
1251 When people ask you to put your time into helping them use the program,
1252 it may seem ``helpful'' to do what they ask. But it is much @emph{less}
1253 helpful than improving the program, which is the maintainer's real job.
1255 By all means help individual users when you feel like it, if you feel
1256 you have the time available. But be careful to limit the amount of time
1257 you spend doing this---don't let it eat away the time you need to
1258 maintain the program! Know how to say no; when you are pressed for
1259 time, just ``thanks for the bug report---I will fix it'' is enough
1262 Some GNU packages, such as Emacs and GCC, come with advice about how
1263 to make bug reports useful. Copying and adapting that could be very
1264 useful for your package.
1266 @cindex @url{http://bugs.gnu.org}
1267 @cindex bug reports, email tracker for
1268 @cindex bug reports, web tracker for
1269 If you would like to use an email-based bug tracking system, see
1270 @url{http://bugs.gnu.org}; this can be connected with the regular
1271 bug-reporting address. Alternatively, if you would like to use a
1272 web-based bug tracking system, Savannah supports this (@pxref{Old
1273 Versions}), but please don't fail to accept bugs by regular email as
1274 well---we don't want to put up unnecessary barriers against users
1279 @chapter Recording Old Versions
1280 @cindex version control
1282 It is very important to keep backup files of all source files of GNU.
1283 You can do this using a source control system (such as Bazaar, RCS,
1284 CVS, Git, Subversion, @dots{}) if you like. An easy way to use
1285 many such systems is via the Version Control library in Emacs
1286 (@pxref{Introduction to VC,, Introduction to Version Control, emacs,
1287 The GNU Emacs Manual}).
1289 The history of previous revisions and log entries is very important for
1290 future maintainers of the package, so even if you do not make it
1291 publicly accessible, be careful not to put anything in the repository or
1292 change log that you would not want to hand over to another maintainer
1295 @cindex @code{savannah-hackers@@gnu.org}
1296 The GNU Project provides a server that GNU packages can use
1297 for source control and other package needs: @code{savannah.gnu.org}.
1298 Savannah is managed by @email{savannah-hackers@@gnu.org}. For more
1299 details on using and contributing to Savannah, see
1300 @url{http://savannah.gnu.org/maintenance}.
1302 It's not an absolute requirement, but all GNU maintainers are strongly
1303 encouraged to take advantage of Savannah, as sharing such a central
1304 point can serve to foster a sense of community among GNU developers as
1305 well as help in keeping up with project management. Please don't mark
1306 Savannah projects for GNU packages as private; that defeats a large
1307 part of the purpose of using Savannah in the first place.
1309 @cindex @code{savannah-announce@@gnu.org} mailing list
1310 If you do use Savannah, please subscribe to the
1311 @email{savannah-announce@@gnu.org} mailing list
1312 (@url{http://lists.gnu.org/mailman/listinfo/savannah-announce}). This
1313 is a very low-volume list to keep Savannah users informed of system
1314 upgrades, problems, and the like.
1318 @chapter Distributions
1320 Please follow the GNU conventions when making GNU software
1324 * Distribution tar Files::
1325 * Distribution Patches::
1326 * Distribution on ftp.gnu.org::
1328 * Automated FTP Uploads::
1332 @node Distribution tar Files
1333 @section Distribution tar Files
1334 @cindex distribution, tar files
1336 The tar file for version @var{m}.@var{n} of program @code{foo} should be
1337 named @file{foo-@var{m}.@var{n}.tar}. It should unpack into a
1338 subdirectory named @file{foo-@var{m}.@var{n}}. Tar files should not
1339 unpack into files in the current directory, because this is inconvenient
1340 if the user happens to unpack into a directory with other files in it.
1342 Here is how the @file{Makefile} for Bison creates the tar file.
1343 This method is good for other programs.
1347 echo bison-`sed -e '/version_string/!d' \
1348 -e 's/[^0-9.]*\([0-9.]*\).*/\1/' -e q version.c` > .fname
1349 -rm -rf `cat .fname`
1351 dst=`cat .fname`; for f in $(DISTFILES); do \
1352 ln $(srcdir)/$$f $$dst/$$f || @{ echo copying $$f; \
1353 cp -p $(srcdir)/$$f $$dst/$$f ; @} \
1355 tar --gzip -chf `cat .fname`.tar.gz `cat .fname`
1356 -rm -rf `cat .fname` .fname
1359 Source files that are symbolic links to other file systems cannot be
1360 installed in the temporary directory using @code{ln}, so use @code{cp}
1364 Using Automake is a good way to take care of writing the @code{dist}
1367 @node Distribution Patches
1368 @section Distribution Patches
1369 @cindex patches, against previous releases
1371 If the program is large, it is useful to make a set of diffs for each
1372 release, against the previous important release.
1374 At the front of the set of diffs, put a short explanation of which
1375 version this is for and which previous version it is relative to.
1376 Also explain what else people need to do to update the sources
1377 properly (for example, delete or rename certain files before
1378 installing the diffs).
1380 The purpose of having diffs is that they are small. To keep them
1381 small, exclude files that the user can easily update. For example,
1382 exclude info files, DVI files, tags tables, output files of Bison or
1383 Flex. In Emacs diffs, we exclude compiled Lisp files, leaving it up
1384 to the installer to recompile the patched sources.
1386 When you make the diffs, each version should be in a directory suitably
1387 named---for example, @file{gcc-2.3.2} and @file{gcc-2.3.3}. This way,
1388 it will be very clear from the diffs themselves which version is which.
1392 @cindex time stamp in diffs
1393 If you use GNU @code{diff} to make the patch, use the options
1394 @samp{-rc2P}. That will put any new files into the output as ``entirely
1395 different''. Also, the patch's context diff headers should have dates
1396 and times in Universal Time using traditional Unix format, so that patch
1397 recipients can use GNU @code{patch}'s @samp{-Z} option. For example,
1398 you could use the following Bourne shell command to create the patch:
1401 LC_ALL=C TZ=UTC0 diff -rc2P gcc-2.3.2 gcc-2.3.3 | \
1402 gzip -9 >gcc-2.3.2-2.3.3.patch.gz
1405 If the distribution has subdirectories in it, then the diffs probably
1406 include some files in the subdirectories. To help users install such
1407 patches reliably, give them precise directions for how to run patch.
1408 For example, say this:
1411 To apply these patches, cd to the main directory of the program
1412 and then use `patch -p1'. `-p1' avoids guesswork in choosing
1413 which subdirectory to find each file in.
1416 It's wise to test your patch by applying it to a copy of the old
1417 version, and checking that the result exactly matches the new version.
1420 @node Distribution on ftp.gnu.org
1421 @section Distribution on @code{ftp.gnu.org}
1422 @cindex GNU ftp site
1423 @cindex @code{ftp.gnu.org}, the GNU release site
1425 We strongly recommend using @code{ftp.gnu.org} to distribute official
1426 releases. If you want to also distribute the package from a site of
1427 your own, that is fine. To use some other site instead of
1428 @code{ftp.gnu.org} is acceptable, provided it allows connections from
1431 @xref{Automated FTP Uploads}, for the procedural details of putting
1432 new versions on @code{ftp.gnu.org}.
1436 @section Test Releases
1437 @cindex test releases
1438 @cindex beta releases
1439 @cindex pretest releases
1441 @cindex @code{alpha.gnu.org}, test release site
1442 When you release a greatly changed new major version of a program, you
1443 might want to do so as a pretest. This means that you make a tar file,
1444 but send it only to a group of volunteers that you have recruited. (Use
1445 a suitable GNU mailing list/newsgroup to recruit them.)
1447 We normally use the server @code{alpha.gnu.org} for pretests and
1448 prerelease versions. @xref{Automated FTP Uploads}, for the procedural
1449 details of putting new versions on @code{alpha.gnu.org}.
1451 Once a program gets to be widely used and people expect it to work
1452 solidly, it is a good idea to do pretest releases before each ``real''
1455 There are two ways of handling version numbers for pretest versions.
1456 One method is to treat them as versions preceding the release you are going
1459 In this method, if you are about to release version 4.6 but you want
1460 to do a pretest first, call it 4.5.90. If you need a second pretest,
1461 call it 4.5.91, and so on. If you are really unlucky and ten pretests
1462 are not enough, after 4.5.99 you could advance to 4.5.990 and so on.
1463 (You could also use 4.5.100, but 990 has the advantage of sorting in
1466 The other method is to attach a date to the release number that is
1467 coming. For a pretest for version 4.6, made on Dec 10, 2002, this
1468 would be 4.6.20021210. A second pretest made the same day could be
1471 For development snapshots that are not formal pretests, using just
1472 the date without the version numbers is ok too.
1474 One thing that you should never do is to release a pretest with the same
1475 version number as the planned real release. Many people will look only
1476 at the version number (in the tar file name, in the directory name that
1477 it unpacks into, or wherever they can find it) to determine whether a
1478 tar file is the latest version. People might look at the test release
1479 in this way and mistake it for the real release. Therefore, always
1480 change the number when you release changed code.
1483 @node Automated FTP Uploads
1484 @section Automated FTP Uploads
1486 @cindex ftp uploads, automated
1487 In order to upload new releases to @code{ftp.gnu.org} or
1488 @code{alpha.gnu.org}, you first need to register the necessary
1489 information. Then, you can perform uploads yourself, with no
1490 intervention needed by the system administrators.
1492 The general idea is that releases should be cryptographically signed
1493 before they are made publicly available.
1496 * Automated Upload Registration::
1497 * Automated Upload Procedure::
1498 * FTP Upload Directive File - v1.1::
1499 * FTP Upload Directive File - v1.0::
1503 @node Automated Upload Registration
1504 @subsection Automated Upload Registration
1506 @cindex registration for uploads
1507 @cindex uploads, registration for
1509 Here is how to register your information so you can perform uploads
1510 for your GNU package:
1515 Create an account for yourself at @url{http://savannah.gnu.org}, if
1516 you don't already have one. By the way, this is also needed to
1517 maintain the web pages at @url{http://www.gnu.org} for your project
1518 (@pxref{Web Pages}).
1521 In the @samp{My Account Conf} page on @code{savannah}, upload the GPG
1522 key you will use to sign your packages. If you haven't created one
1523 before, you can do so with the command @code{gpg --gen-key} (you can
1524 accept all the default answers to its questions).
1526 Optional but recommended: Send your key to a GPG public key server:
1527 @code{gpg --keyserver keys.gnupg.net --send-keys @var{keyid}}, where
1528 @var{keyid} is the eight hex digits reported by @code{gpg
1529 --list-public-keys} on the @code{pub} line before the date. For full
1530 information about GPG, see @url{http://www.gnu.org/software/gpg}.
1533 Compose a message with the following items in some @var{msgfile}.
1534 Then GPG-sign it by running @code{gpg --clearsign @var{msgfile}}, and
1535 finally email the resulting @file{@var{msgfile}.asc} to
1536 @email{ftp-upload@@gnu.org}.
1540 Name of package(s) that you are the maintainer for, your
1541 preferred email address, and your Savannah username.
1544 An ASCII armored copy of your GPG key, as an attachment. (@samp{gpg
1545 --export -a @var{your_key_id} >mykey.asc} should give you this.)
1548 A list of names and preferred email addresses of other individuals you
1549 authorize to make releases for which packages, if any (in the case that you
1550 don't make all releases yourself).
1553 ASCII armored copies of GPG keys for any individuals listed in (3).
1557 The administrators will acknowledge your message when they have added
1558 the proper GPG keys as authorized to upload files for the
1559 corresponding packages.
1561 The upload system will email receipts to the given email addresses
1562 when an upload is made, either successfully or unsuccessfully.
1565 @node Automated Upload Procedure
1566 @subsection Automated Upload Procedure
1570 Once you have registered your information as described in the previous
1571 section, you will be able to do ftp uploads for yourself using the
1572 following procedure.
1574 For each upload destined for @code{ftp.gnu.org} or
1575 @code{alpha.gnu.org}, three files (a @dfn{triplet}) need to be
1576 uploaded via ftp to the host @code{ftp-upload.gnu.org}.
1580 The file to be distributed; for example, @file{foo.tar.gz}.
1583 Detached GPG binary signature file for (1); for example,
1584 @file{foo.tar.gz.sig}. Make this with @samp{gpg -b foo.tar.gz}.
1587 A clearsigned @dfn{directive file}; for example,
1588 @file{foo.tar.gz.directive.asc}. Make this by preparing the plain
1589 text file @file{foo.tar.gz.directive} and then run @samp{gpg
1590 --clearsign foo.tar.gz.directive}. @xref{FTP Upload Directive File -
1591 v1.1}, for the contents of the directive file.
1594 The names of the files are important. The signature file must have the
1595 same name as the file to be distributed, with an additional
1596 @file{.sig} extension. The directive file must have the same name as
1597 the file to be distributed, with an additional @file{.directive.asc}
1598 extension. If you do not follow this naming convention, the upload
1599 @emph{will not be processed}.
1601 Since v1.1 of the upload script, it is also possible to upload a
1602 clearsigned directive file on its own (no accompanying @file{.sig} or
1603 any other file) to perform certain operations on the server.
1604 @xref{FTP Upload Directive File - v1.1}, for more information.
1606 Upload the file(s) via anonymous ftp to @code{ftp-upload.gnu.org}. If
1607 the upload is destined for @code{ftp.gnu.org}, place the file(s) in
1608 the @file{/incoming/ftp} directory. If the upload is destined for
1609 @code{alpha.gnu.org}, place the file(s) in the @file{/incoming/alpha}
1612 Uploads are processed every five minutes. Uploads that are in
1613 progress while the upload processing script is running are handled
1614 properly, so do not worry about the timing of your upload. Uploaded
1615 files that belong to an incomplete triplet are deleted automatically
1618 Your designated upload email addresses (@pxref{Automated Upload Registration})
1619 are sent a message if there are any problems processing an upload for your
1620 package. You also receive a message when your upload has been successfully
1623 One automated way to create and transfer the necessary files is to use
1624 the @code{gnupload} script, which is available from the
1625 @file{build-aux/} directory of the @code{gnulib} project at
1626 @url{http://savannah.gnu.org/projects/gnulib}. @code{gnupload} can
1627 also remove uploaded files. Run @code{gnupload --help} for a
1628 description and examples.
1630 @code{gnupload} uses the @code{ncftpput} program to do the actual
1631 transfers; if you don't happen to have the @code{ncftp} package
1632 installed, the @code{ncftpput-ftp} script in the @file{build-aux/}
1633 directory of @code{gnulib} serves as a replacement which uses plain
1634 command line @code{ftp}.
1636 If you have difficulties with an upload, email
1637 @email{ftp-upload@@gnu.org}. You can check the archive of uploads
1639 @url{https://lists.gnu.org/archive/html/ftp-upload-report}.
1642 @node FTP Upload Directive File - v1.1
1643 @subsection FTP Upload Directive File - v1.1
1645 The directive file name must end in @file{directive.asc}.
1647 When part of a triplet, the directive file must always contain the
1648 directives @code{version}, @code{directory} and @code{filename}, as
1649 described. In addition, a 'comment' directive is allowed.
1651 The @code{version} directive must always have the value @samp{1.1}.
1653 The @code{directory} directive specifies the final destination
1654 directory where the uploaded file and its @file{.sig} companion are to
1657 The @code{filename} directive must contain the name of the file to be
1658 distributed (item@tie{}(1) above).
1660 For example, as part of an uploaded triplet, a
1661 @file{foo.tar.gz.directive.asc} file might contain these lines (before
1662 being gpg clearsigned):
1667 filename: foo.tar.gz
1668 comment: hello world!
1671 This directory line indicates that @file{foo.tar.gz} and
1672 @file{foo.tar.gz.sig} are part of package @code{bar}. If you uploaded
1673 this triplet to @file{/incoming/ftp} and the system positively
1674 authenticates the signatures, the files @file{foo.tar.gz} and
1675 @file{foo.tar.gz.sig} will be placed in the directory
1676 @file{gnu/bar/v1} of the @code{ftp.gnu.org} site.
1678 The directive file can be used to create currently non-existent
1679 directory trees, as long as they are under the package directory for
1680 your package (in the example above, that is @code{bar}).
1682 If you upload a file that already exists in the FTP directory, the
1683 original will simply be archived and replaced with the new upload.
1685 @subheading Standalone directives
1687 When uploaded by itself, the directive file must contain one or more
1688 of the directives @code{symlink}, @code{rmsymlink} or @code{archive},
1689 in addition to the obligatory @code{directory} and @code{version}
1690 directives. A @code{filename} directive is not allowed, and a
1691 @code{comment} directive remains optional.
1693 If you use more than one directive, the directives are executed in the
1694 sequence they are specified in. If a directive results in an error,
1695 further execution of the upload is aborted.
1697 Removing a symbolic link (with @code{rmsymlink}) which does not exist
1698 results in an error. However, attempting to create a symbolic link
1699 that already exists (with @code{symlink}) is not an error. In this
1700 case @code{symlink} behaves like the command @command{ln -s -f}: any
1701 existing symlink is removed before creating the link. (But an
1702 existing regular file or directory is not removed.)
1704 Here are a few examples. The first removes a symlink:
1709 rmsymlink: foo-latest.tgz
1710 comment: remove a symlink
1714 Archive an old file, taking it offline:
1719 archive: foo-1.1.tar.gz
1720 comment: archive an old file; it will not be
1721 comment: available through FTP any more.
1725 Archive an old directory (with all contents), taking it offline:
1731 comment: archive an old directory; it and its entire
1732 comment: contents will not be available through FTP anymore
1736 Create a new symlink:
1741 symlink: foo-1.2.tar.gz foo-latest.tgz
1742 comment: create a new symlink
1746 Do everything at once:
1751 rmsymlink: foo-latest.tgz
1752 symlink: foo-1.2.tar.gz foo-latest.tgz
1753 archive: foo-1.1.tar.gz
1754 comment: now do everything at once
1758 @node FTP Upload Directive File - v1.0
1759 @subsection FTP Upload Directive File - v1.0
1761 @dfn{As of June 2006, the upload script is running in compatibility
1762 mode, allowing uploads with either version@tie{}1.1 or
1763 version@tie{}1.0 of the directive file syntax. Support for v1.0
1764 uploads will be phased out by the end of 2006, so please upgrade
1767 The directive file should contain one line, excluding the clearsigned
1768 data GPG that inserts, which specifies the final destination directory
1769 where items (1) and (2) are to be placed.
1771 For example, the @file{foo.tar.gz.directive.asc} file might contain the
1778 This directory line indicates that @file{foo.tar.gz} and
1779 @file{foo.tar.gz.sig} are part of package @code{bar}. If you were to
1780 upload the triplet to @file{/incoming/ftp}, and the system can
1781 positively authenticate the signatures, then the files
1782 @file{foo.tar.gz} and @file{foo.tar.gz.sig} will be placed in the
1783 directory @file{gnu/bar/v1} of the @code{ftp.gnu.org} site.
1785 The directive file can be used to create currently non-existent
1786 directory trees, as long as they are under the package directory for
1787 your package (in the example above, that is @code{bar}).
1791 @section Announcing Releases
1792 @cindex announcements
1794 @cindex @code{info-gnu} mailing list
1795 When you have a new release, please make an announcement. For
1796 official new releases, including those made just to fix bugs, we
1797 strongly recommend using the (moderated) general GNU announcements
1798 list, @email{info-gnu@@gnu.org}. Doing so makes it easier for users
1799 and developers to find the latest GNU releases. On the other hand,
1800 please do not announce test releases on @code{info-gnu} unless it's a
1801 highly unusual situation.
1803 @cindex @url{http://planet.gnu.org}
1804 @cindex Savannah, news area
1805 Please also post release announcements in the news section of your
1806 Savannah project site. Here, it is fine to also write news entries
1807 for test releases and any other newsworthy events. The news feeds
1808 from all GNU projects at savannah are aggregated at
1809 @url{http://planet.gnu.org} (GNU Planet). You can also post items
1810 directly, or arrange for feeds from other locations; see information
1811 on the GNU Planet web page.
1813 @cindex announcement mailing list, project-specific
1814 You can maintain your own mailing list (typically
1815 @indicateurl{info-@var{package}@@gnu.org}) for announcements as well if you
1816 like. For your own list, of course you decide as you see fit what
1817 events are worth announcing. (@xref{Mail}, for setting this up, and
1818 more suggestions on handling mail for your package.)
1820 @cindex contents of announcements
1821 When writing an announcement, please include the following:
1825 A very brief description (a few sentences at most) of the general
1826 purpose of your package.
1829 Your package's web page (normally
1830 @indicateurl{http://www.gnu.org/software/@var{package}/}).
1833 Your package's download location (normally
1834 @indicateurl{http://ftp.gnu.org/gnu/@var{package}/}). It is also
1835 useful to mention the mirror list at
1836 @url{http://www.gnu.org/order/ftp.html}, and that
1837 @indicateurl{http://ftpmirror.gnu.org/@var{package/}} will automatically
1838 redirect to a nearby mirror.
1841 The @t{NEWS} (@pxref{NEWS File,,, standards, GNU Coding Standards}) for
1842 the present release.
1850 Please write web pages about your package, and install them on
1851 @code{www.gnu.org}. They should follow our usual standards for web
1852 pages (see @url{http://www.gnu.org/server/@/fsf-html-style-sheet.html}).
1853 The overall goals are to support a wide variety of browsers, to focus
1854 on information rather than flashy eye candy, and to keep the site
1857 We encourage you to use the standard @code{www.gnu.org} template as
1858 the basis for your pages:
1859 @url{http://www.gnu.org/server/@/standards/@/boilerplate-source.html}.
1861 Some GNU packages have just simple web pages, but the more information
1862 you provide, the better. So please write as much as you usefully can,
1863 and put all of it on @code{www.gnu.org}. However, pages that access
1864 databases (including mail archives and bug tracking) are an exception;
1865 set them up on whatever site is convenient for you, and make the pages
1866 on @code{www.gnu.org} link to that site.
1869 * Hosting for Web Pages::
1870 * Freedom for Web Pages::
1871 * Manuals on Web Pages::
1872 * CVS Keywords in Web Pages::
1876 @node Hosting for Web Pages
1877 @section Hosting for Web Pages
1879 The best way to maintain the web pages for your project is to register
1880 the project on @code{savannah.gnu.org}. Then you can edit the pages
1881 using CVS, using the separate ``web repository'' available on
1882 Savannah, which corresponds to
1883 @indicateurl{http://www.gnu.org/software/@var{package}/}. You can
1884 keep your source files there too (using any of a variety of version
1885 control systems), but you can use @code{savannah.gnu.org} only for
1886 your gnu.org web pages if you wish; simply register a ``web-only''
1889 If you don't want to use that method, please talk with
1890 @email{webmasters@@gnu.org} about other possible methods. For
1891 instance, you can mail them pages to install, if necessary. But that
1892 is more work for them, so please use Savannah if you can.
1894 If you use Savannah, you can use a special file named @file{.symlinks}
1895 in order to create symbolic links, which are not supported in CVS.
1897 @url{http://www.gnu.org/server/standards/README.webmastering.html#symlinks}.
1900 @node Freedom for Web Pages
1901 @section Freedom for Web Pages
1903 If you use a site other than @code{www.gnu.org}, please make sure that
1904 the site runs on free software alone. (It is ok if the site uses
1905 unreleased custom software, since that is free in a trivial sense:
1906 there's only one user and it has the four freedoms.) If the web site
1907 for a GNU package runs on non-free software, the public will see this,
1908 and it will have the effect of granting legitimacy to the non-free
1911 If you use multiple sites, they should all follow that criterion.
1912 Please don't link to a site that is about your package, which the
1913 public might perceive as connected with it and reflecting the position
1914 of its developers, unless it follows that criterion.
1916 Historically, web pages for GNU packages did not include GIF images,
1917 because of patent problems (@pxref{Ethical and Philosophical
1918 Consideration}). Although the GIF patents expired in 2006, using GIF
1919 images is still not recommended, as the PNG and JPEG formats are
1920 generally superior. See @url{http://www.gnu.org/philosophy/gif.html}.
1923 @node Manuals on Web Pages
1924 @section Manuals on Web Pages
1926 The web pages for the package should include its manuals, in HTML,
1927 DVI, Info, PostScript, PDF, plain ASCII, and Texinfo format (source).
1928 All of these can be generated automatically from the Texinfo source
1929 using Makeinfo and other programs.
1931 When there is only one manual, put it in a subdirectory called
1932 @file{manual}; the file @file{manual/index.html} should have a link to
1933 the manual in each of its forms.
1935 If the package has more than one manual, put each one in a
1936 subdirectory of @file{manual}, set up @file{index.html} in each
1937 subdirectory to link to that manual in all its forms, and make
1938 @file{manual/index.html} link to each manual through its subdirectory.
1940 See the section below for details on a script to make the job of
1941 creating all these different formats and index pages easier.
1943 We would like to list all GNU manuals on the page
1944 @url{http://www.gnu.org/manual}, so if yours isn't there, please send
1945 mail to @code{webmasters@@gnu.org}, asking them to add yours, and they
1946 will do so based on the contents of your @file{manual} directory.
1949 * Invoking gendocs.sh::
1953 @node Invoking gendocs.sh
1954 @subsection Invoking @command{gendocs.sh}
1956 @cindex generating documentation output
1958 The script @command{gendocs.sh} eases the task of generating the
1959 Texinfo documentation output for your web pages
1960 section above. It has a companion template file, used as the basis
1961 for the HTML index pages. Both are available from the Texinfo CVS
1965 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh}
1966 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template}
1969 There is also a minimalistic template, available from:
1972 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template_min}
1975 Invoke the script like this, in the directory containing the Texinfo
1979 gendocs.sh --email @var{yourbuglist} @var{yourmanual} "GNU @var{yourmanual} manual"
1982 @noindent where @var{yourmanual} is the short name for your package
1983 and @var{yourbuglist} is the email address for bug reports (which
1984 should be @code{bug-@var{package}@@gnu.org}). The script processes
1985 the file @file{@var{yourmanual}.texinfo} (or @file{.texi} or
1986 @file{.txi}). For example:
1990 # download gendocs.sh and gendocs_template
1991 gendocs.sh --email bug-texinfo@@gnu.org texinfo "GNU Texinfo manual"
1994 @command{gendocs.sh} creates a subdirectory @file{manual/} containing
1995 the manual generated in all the standard output formats: Info, HTML,
1996 DVI, and so on, as well as the Texinfo source. You then need to move
1997 all those files, retaining the subdirectories, into the web pages for
2000 You can specify the option @option{-o @var{outdir}} to override the
2001 name @file{manual}. Any previous contents of @var{outdir} will be deleted.
2003 The second argument, with the description, is included as part of the
2004 HTML @code{<title>} of the overall @file{manual/index.html} file. It
2005 should include the name of the package being documented, as shown.
2006 @file{manual/index.html} is created by substitution from the file
2007 @file{gendocs_template}. (Feel free to modify the generic template
2008 for your own purposes.)
2010 If you have several manuals, you'll need to run this script several
2011 times with different arguments, specifying a different output
2012 directory with @option{-o} each time, and moving all the output to
2013 your web page. Then write (by hand) an overall index.html with links
2014 to them all. For example:
2018 gendocs.sh --email bug-texinfo@@gnu.org -o texinfo texinfo "GNU Texinfo manual"
2019 gendocs.sh --email bug-texinfo@@gnu.org -o info info "GNU Info manual"
2020 gendocs.sh --email bug-texinfo@@gnu.org -o info-stnd info-stnd "GNU info-stnd manual"
2023 By default, the script uses @command{makeinfo} for generating
2024 @acronym{HTML} output. If you prefer to use @command{texi2html}, use
2025 the @option{--texi2html} command line option, e.g.:
2028 gendocs --texi2html -o texinfo texinfo "GNU Texinfo manual"
2031 The template files will automatically produce entries for additional
2032 HTML output generated by @command{texi2html} (i.e., split by sections
2035 You can set the environment variables @env{MAKEINFO}, @env{TEXI2DVI},
2036 @env{TEXI2HTML} and @env{DVIPS} to control the programs that get
2037 executed, and @env{GENDOCS_TEMPLATE_DIR} to control where the
2038 @file{gendocs_template} file is found.
2040 As usual, run @samp{gendocs.sh --help} for a description of all the
2041 options, environment variables, and more information.
2043 Please email bug reports, enhancement requests, or other
2044 correspondence to @email{bug-texinfo@@gnu.org}.
2047 @node CVS Keywords in Web Pages
2048 @section CVS Keywords in Web Pages
2049 @cindex CVS keywords in web pages
2050 @cindex RCS keywords in web pages
2051 @cindex $ keywords in web pages
2052 @cindex web pages, and CVS keywords
2054 Since @code{www.gnu.org} works through CVS, CVS keywords in your
2055 manual, such as @code{@w{$}Log$}, need special treatment (even if you
2056 don't happen to maintain your manual in CVS).
2058 If these keywords end up in the generated output as literal strings,
2059 they will be expanded. The most robust way to handle this is to turn
2060 off keyword expansion for such generated files. For existing files,
2064 cvs admin -ko @var{file1} @var{file2} ...
2071 cvs add -ko @var{file1} @var{file2} ...
2074 @c The CVS manual is now built with numeric references and no nonsplit
2075 @c form, so it's not worth trying to give a direct link.
2076 See the ``Keyword Substitution'' section in the CVS manual, available
2077 at @url{http://ximbiot.com/cvs/manual}.
2079 In Texinfo source, the recommended way to literally specify a
2080 ``dollar'' keyword is:
2086 The @code{@@w} prevents keyword expansion in the Texinfo source
2087 itself. Also, @code{makeinfo} notices the @code{@@w} and generates
2088 output avoiding the literal keyword string.
2091 @node Ethical and Philosophical Consideration
2092 @chapter Ethical and Philosophical Consideration
2096 The GNU project takes a strong stand for software freedom. Many
2097 times, this means you'll need to avoid certain technologies when their
2098 use would conflict with our long-term goals.
2100 Software patents threaten the advancement of free software and freedom
2101 to program. There are so many software patents in the US that any
2102 large program probably implements hundreds of patented techniques,
2103 unknown to the program's developers. It would be futile and
2104 self-defeating to try to find and avoid all these patents. But there
2105 are some patents which we know are likely to be used to threaten free
2106 software, so we make an effort to avoid the patented techniques. If
2107 you are concerned about the danger of a patent and would like advice,
2108 write to @email{licensing@@gnu.org}, and we will try to help you get
2109 advice from a lawyer.
2111 Sometimes the GNU project takes a strong stand against a particular
2112 patented technology in order to encourage society to reject it.
2114 For example, the MP3 audio format is covered by a software patent in
2115 the USA and some other countries. A patent holder has threatened
2116 lawsuits against the developers of free programs (these are not GNU
2117 programs) to produce and play MP3, and some GNU/Linux distributors are
2118 afraid to include them. Development of the programs continues, but we
2119 campaign for the rejection of MP3 format in favor of Ogg Vorbis format.
2121 A GNU package should not recommend use of any non-free program, nor
2122 should it require a non-free program (such as a non-free compiler or
2123 IDE) to build. Thus, a GNU package cannot be written in a programming
2124 language that does not have a free software implementation. Now that
2125 GNU/Linux systems are widely available, all GNU packages should
2126 provide full functionality on a 100% free GNU/Linux system, and should
2127 not require any non-free software to build or function.
2128 The GNU Coding Standards say a lot more about this issue.
2130 A GNU package should not refer the user to any non-free documentation
2131 for free software. The need for free documentation to come with free
2132 software is now a major focus of the GNU project; to show that we are
2133 serious about the need for free documentation, we must not contradict
2134 our position by recommending use of documentation that isn't free.
2136 Finally, new issues concerning the ethics of software freedom come up
2137 frequently. We ask that GNU maintainers, at least on matters that
2138 pertain specifically to their package, stand with the rest of the GNU
2139 project when such issues come up.
2143 @chapter Terminology Issues
2146 This chapter explains a couple of issues of terminology which are
2147 important for correcting two widespread and important misunderstandings
2151 * Free Software and Open Source::
2155 @node Free Software and Open Source
2156 @section Free Software and Open Source
2157 @cindex free software movement
2159 @cindex movement, free software
2160 @cindex development method, open source
2162 The terms ``free software'' and ``open source'', while describing
2163 almost the same category of software, stand for views based on
2164 fundamentally different values. The free software movement is
2165 idealistic, and raises issues of freedom, ethics, principle and what
2166 makes for a good society. The term open source, initiated in 1998, is
2167 associated with a philosophy which studiously avoids such questions.
2168 For a detailed explanation, see
2169 @url{http://www.gnu.org/philosophy/open-source-misses-the-point.html}.
2171 The GNU Project is aligned with the free software movement. This
2172 doesn't mean that all GNU contributors and maintainers have to agree;
2173 your views on these issues are up to you, and you're entitled to express
2174 them when speaking for yourself.
2176 However, due to the much greater publicity that the term ``open source''
2177 receives, the GNU Project needs to overcome a widespread
2178 mistaken impression that GNU is @emph{and always was} an ``open
2179 source'' activity. For this reason, please use the term ``free
2180 software'', not ``open source'', in GNU software releases, GNU
2181 documentation, and announcements and articles that you publish in your
2182 role as the maintainer of a GNU package. A reference to the URL given
2183 above, to explain the difference, is a useful thing to include as
2188 @section GNU and Linux
2192 The GNU Project was formed to develop a free Unix-like operating system,
2193 GNU. The existence of this system is our major accomplishment.
2194 However, the widely used version of the GNU system, in which Linux is
2195 used as the kernel, is often called simply ``Linux''. As a result, most
2196 users don't know about the GNU Project's major accomplishment---or more
2197 precisely, they know about it, but don't realize it is the GNU Project's
2198 accomplishment and reason for existence. Even people who believe they
2199 know the real history often believe that the goal of GNU was to develop
2200 ``tools'' or ``utilities''.
2202 To correct this confusion, we have made a years-long effort to
2203 distinguish between Linux, the kernel that Linus Torvalds wrote, and
2204 GNU/Linux, the operating system that is the combination of GNU and
2205 Linux. The resulting increased awareness of what the GNU Project has
2206 already done helps every activity of the GNU Project recruit more
2207 support and contributors.
2209 Please make this distinction consistently in GNU software releases, GNU
2210 documentation, and announcements and articles that you publish in your
2211 role as the maintainer of a GNU package. If you want to explain the
2212 terminology and its reasons, you can refer to the URL
2213 @url{http://www.gnu.org/gnu/linux-and-gnu.html}.
2215 To make it clear that Linux is a kernel, not an operating system,
2216 please take care to avoid using the term ``Linux system'' in those
2217 materials. If you want to have occasion to make a statement about
2218 systems in which the kernel is Linux, write ``systems in which the
2219 kernel is Linux'' or ``systems with Linux as the kernel.'' That
2220 explicitly contrasts the system and the kernel, and will help readers
2221 understand the difference between the two. Please avoid simplified
2222 forms such as ``Linux-based systems'' because those fail to highlight
2223 the difference between the kernel and the system, and could encourage
2224 readers to overlook the distinction.
2226 To contrast the GNU system properly with respect to GNU/Linux, you can
2227 call it ``GNU/Hurd'' or ``the GNU/Hurd system''. However, when that
2228 contrast is not specifically the focus, please call it just ``GNU'' or
2231 When referring to the collection of servers that is the higher level
2232 of the GNU kernel, please call it ``the Hurd'' or ``the GNU Hurd''.
2233 Note that this uses a space, not a slash.
2236 @node Interviews and Speeches
2237 @chapter Interviews and Speeches
2239 Interviews and speeches about your package are an important channel
2240 for informing the public about the GNU system and the ideas of the
2241 free software movement. Please avoid saying ``open source'' and avoid
2242 calling the GNU system ``Linux'', just as you would in the package
2243 itself (@pxref{Terminology}). Likewise, avoid promoting nonfree
2244 programs (@pxref{References,,, standards, GNU Coding
2245 Standards}) as you would in the package itself.
2247 Many GNU users have erroneous ideas about GNU. Outside of our
2248 community, most people think it is Linux. Please use your opportunity
2249 to set them straight. Start the presentation with the answers to
2250 these basic questions:
2254 What GNU is (an operating system developed to be Unix-like and totally
2255 free software). It is good to mention @url{http://www.gnu.org}.
2258 What free software is (the users control it, so it doesn't control
2259 them). It is good to state the four freedoms and/or refer to
2260 @url{http://www.gnu.org/philosophy/free-sw.html}.
2263 What GNU/Linux is (Linux filled the last gap in GNU). It is useful to
2264 refer to @url{http://www.gnu.org/gnu/linux-and-gnu.html}.
2267 What the GNU Project is (the project to develop GNU).
2270 How your package fits in (it's part of GNU, and the work is part of
2274 If you feel a social pressure not to say these things, you may be
2275 coming in contact with some who would prefer that these things not be
2276 said. That's precisely when we need your support most.
2278 Please don't include advertisements or plugs for any company, product
2279 or service. Even if the product would meet the standards for the FSF
2280 to endorse it, an ad for it is out of place in a presentation about a
2281 GNU package. Likewise, please don't include company slogans. Mention
2282 a company only when called for by the subject matter.
2284 A few GNU packages are actually business activities of a particular
2285 company. In that case, it is ok to say so at the start. Otherwise,
2286 please show that this is a project of the GNU Project, and avoid
2287 suggesting it is any company's project.
2289 If you are paid by a company to work on the GNU package, it is
2290 appropriate to thank the company in a discreet way, but please don't
2293 Before you do a speech or interview, please contact the GNU Project
2294 leadership. We can give you advice on how to deal with various
2297 When your interviews and speech recordings or transcript are posted,
2298 please tell us about them. Then we can publicize them.
2300 Please post them in formats that are friendly to free software: not in
2301 Doc or Docx format, not with Flash, not with QuickTime, not with MP3,
2302 MPEG2 or MPEG4. Plain text, HTML and PDF are good.
2306 @cindex CVS repository
2308 @cindex source repository
2309 @cindex version control system
2311 @cindex release site
2314 We recommend using @code{savannah.gnu.org} for the source code
2315 repository for your package, but that's not required. @xref{Old
2316 Versions}, for more information about Savannah.
2318 We strongly urge you to use @code{ftp.gnu.org} as the standard
2319 distribution site for releases. Doing so makes it easier for
2320 developers and users to find the latest GNU releases. However, it is
2321 ok to use another server if you wish, provided it allows access from
2322 the general public without limitation (for instance, without excluding
2325 If you use a company's machine to hold the repository for your
2326 program, or as its release distribution site, please put this
2327 statement in a prominent place on the site, so as to prevent people
2328 from getting the wrong idea about the relationship between the package
2332 The programs <list of them> hosted here are free software packages
2333 of the GNU Project, not products of <company name>. We call them
2334 "free software" because you are free to copy and redistribute them,
2335 following the rules stated in the license of each package. For more
2336 information, see http://www.gnu.org/philosophy/free-sw.html.
2338 If you are looking for service or support for GNU software, see
2339 http://www.gnu.org/gethelp/ for suggestions of where to ask.
2341 If you would like to contribute to the development of one of these
2342 packages, contact the package maintainer or the bug-reporting address
2343 of the package (which should be listed in the package itself), or look
2344 on www.gnu.org for more information on how to contribute.
2350 @cindex Donations, for packages
2351 @cindex Money, donated to packages
2353 As a maintainer, you might want to accept donations for your work,
2354 especially if you pay for any of your own hosting/development
2355 infrastructure. Following is some text you can adapt to your own
2356 situation, and use on your package's web site, @file{README}, or
2357 in wherever way you find it useful:
2360 We appreciate contributions of any size -- donations enable us to spend
2361 more time working on the project, and help cover our infrastructure
2364 If you'd like to make a small donation, please visit @var{url1} and do
2365 it through @var{payment-service}. Since our project isn't a
2366 tax-exempt organization, we can't offer you a tax deduction, but for
2367 all donations over @var{amount1}, we'd be happy to recognize your
2368 contribution on @var{url2}.
2370 We are also happy to consider making particular improvements or
2371 changes, or giving specific technical assistance, in return for a
2372 substantial donation over @var{amount2}. If you would like to discuss
2373 this possibility, write to us at @var{address}.
2375 Another possibility is to pay a software maintenance fee. Again,
2376 write to us about this at @var{address} to discuss how much you want
2377 to pay and how much maintenance we can offer in return. If you pay
2378 more than @var{amount1}, we can give you a document for your records.
2380 Thanks for your support!
2383 We don't recommend any specific payment service. However, GNU
2384 developers should not use a service that requires them to sign a
2385 proprietary software license, such as Google's payment service.
2387 Of course, it is also good to encourage people to join or contribute
2388 to the FSF (@url{http://www.fsf.org}), either instead of or as well as
2389 package-specific donations.
2392 @node Free Software Directory
2393 @chapter Free Software Directory
2394 @cindex Free Software Directory
2395 @cindex Directory, Free Software
2397 The Free Software Directory aims to be a complete list of free
2398 software packages, within certain criteria. Every GNU package should
2399 be listed there, so please see
2400 @url{http://www.gnu.org/help/directory.html#adding-entries} for
2401 information on how to write an entry for your package. Contact
2402 @email{bug-directory@@gnu.org} with any questions or suggestions for
2403 the Free Software Directory.
2406 @node Using the Proofreaders List
2407 @chapter Using the Proofreaders List
2408 @cindex proofreading
2410 If you want help finding errors in documentation,
2411 or help improving the quality of writing,
2412 or if you are not a native speaker of English
2413 and want help producing good English documentation,
2414 you can use the GNU proofreaders mailing list:
2415 @email{proofreaders@@gnu.org}.
2417 But be careful when you use the list,
2418 because there are over 200 people on it.
2419 If you simply ask everyone on the list to read your work,
2420 there will probably be tremendous duplication of effort
2421 by the proofreaders,
2422 and you will probably get the same errors reported 100 times.
2423 This must be avoided.
2425 Also, the people on the list do not want to get
2426 a large amount of mail from it.
2427 So do not ever ask people on the list to send mail to the list!
2429 Here are a few methods that seem reasonable to use:
2433 For something small, mail it to the list,
2434 and ask people to pick a random number from 1 to 20,
2435 and read it if the number comes out as 10.
2436 This way, assuming 50% response, some 5 people will read the piece.
2439 For a larger work, divide your work into around 20 equal-sized parts,
2440 tell people where to get it,
2441 and ask each person to pick randomly which part to read.
2443 Be sure to specify the random choice procedure;
2444 otherwise people will probably use a mental procedure
2445 that is not really random,
2446 such as ``pick a part near the middle'',
2447 and you will not get even coverage.
2449 You can either divide up the work physically, into 20 separate files,
2450 or describe a virtual division, such as by sections
2451 (if your work has approximately 20 sections).
2452 If you do the latter, be sure to be precise about it---for example,
2453 do you want the material before the first section heading
2454 to count as a section, or not?
2457 For a job needing special skills, send an explanation of it,
2458 and ask people to send you mail if they volunteer for the job.
2459 When you get enough volunteers, send another message to the list saying
2460 ``I have enough volunteers, no more please.''
2464 @node GNU Free Documentation License
2465 @appendix GNU Free Documentation License
2467 @cindex FDL, GNU Free Documentation License
2478 eval: (add-hook 'write-file-hooks 'time-stamp)
2479 time-stamp-start: "@set lastupdate "
2480 time-stamp-start: "@set lastupdate "
2482 time-stamp-format: "%:b %:d, %:y"
2483 compile-command: "make -C work.m"