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 January 5, 2008
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).
25 Information for maintainers of GNU software, last updated @value{lastupdate}.
27 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
28 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software
32 Permission is granted to make and distribute verbatim copies
33 of this entire document without royalty provided the
34 copyright notice and this permission notice are preserved.
39 @title Information For Maintainers of GNU Software
40 @author Richard Stallman
41 @author last updated @value{lastupdate}
43 @vskip 0pt plus 1filll
59 * Recruiting Developers::
67 * Ethical and Philosophical Consideration::
70 * Free Software Directory::
71 * Using the Proofreaders List::
77 @chapter About This Document
79 This file contains guidelines and advice for someone who is the
80 maintainer of a GNU program on behalf of the GNU Project. Everyone is
81 entitled to change and redistribute GNU software; you need not pay
82 attention to this file to get permission. But if you want to maintain a
83 version for widespread distribution, we suggest you follow these
84 guidelines; if you would like to be a GNU maintainer, then it is
85 essential to follow these guidelines.
87 Please send corrections or suggestions for this document to
88 @email{maintainers@@gnu.org}. If you make a suggestion, please include
89 a suggested new wording for it, to help us consider the suggestion
90 efficiently. We prefer a context diff to the @file{maintain.texi} file,
91 but if you don't have that file, you can make a context diff for some
92 other version of this document, or propose it in any way that makes it
95 This document uses the gender-neutral third-person pronouns ``person'',
96 ``per'', ``pers'' and ``perself'' which were promoted, and perhaps
97 invented, by Marge Piercy in @cite{Woman on the Edge of Time}. They are
98 used just like ``she'', ``her'', ``hers'' and ``herself'', except that
99 they apply equally to males and females. For example, ``Person placed
100 per new program under the GNU GPL, to let the public benefit from per
101 work, and to enable per to feel person has done the right thing.''
103 The directory @file{/gd/gnuorg} is found on the GNU file server,
104 currently @code{fencepost.gnu.org}; if you are the maintainer of a GNU
105 package, you should have an account there. Contact
106 @email{accounts@@gnu.org} if you don't have one. (You can also ask
107 for accounts for people who help you a large amount in working on the
110 This release of the GNU Maintenance Instructions was last updated
115 @chapter Stepping Down
117 With good fortune, you will continue maintaining your package for many
118 decades. But sometimes for various reasons maintainers decide to step
121 If you're the official maintainer of a GNU package and you decide to
122 step down, please inform the GNU Project (@email{maintainers@@gnu.org}).
123 We need to know that the package no longer has a maintainer, so we can
124 look for and appoint a new maintainer.
126 If you have an idea for who should take over, please tell
127 @email{maintainers@@gnu.org} your suggestion. The appointment of a new
128 maintainer needs the GNU Project's confirmation, but your judgment that
129 a person is capable of doing the job will carry a lot of weight.
131 As your final act as maintainer, it would be helpful to set up the
132 package under @code{savannah.gnu.org} (@pxref{Old Versions}). This will
133 make it much easier for the new maintainer to pick up where you left off
134 and will ensure that the source tree is not misplaced if it takes us a
135 while to find a new maintainer.
138 @node Recruiting Developers
139 @chapter Recruiting Developers
141 Unless your package is a fairly small, you probably won't do all the
142 work on it yourself. Most maintainers recruit other developers to help.
144 Sometimes people will offer to help. Some of them will be capable,
145 while others will not. It's up to you to determine who provides useful
146 help, and encourage those people to participate more.
148 Some of the people who offer to help will support the GNU Project, while
149 others may be interested for other reasons. Some will support the goals
150 of the Free Software Movement, but some may not. They are all welcome
151 to help with the work---we don't ask people's views or motivations
152 before they contribute to GNU packages.
154 As a consequence, you cannot expect all contributors to support the GNU
155 Project, or to have a concern for its policies and standards. So part
156 of your job as maintainer is to exercise your authority on these points
157 when they arise. No matter how much of the work other people do, you
158 are in charge of what goes in the release. When a crucial point arises,
159 you should calmly state your decision and stick to it.
161 Sometimes a package has several co-maintainers who share the role of
162 maintainer. Unlike developers who help, co-maintainers have actually
163 been appointed jointly as the maintainers of the package, and they carry
164 out the maintainer's functions together. If you would like to propose
165 some of your developers as co-maintainers, please contact
166 @email{maintainers@@gnu.org}.
170 @chapter Legal Matters
171 @cindex legal matters
173 This chapter describes procedures you should follow for legal reasons
174 as you maintain the program, to avoid legal difficulties.
178 * Legally Significant::
179 * Recording Contributors::
180 * Copying from Other Packages::
181 * Copyright Notices::
183 * External Libraries::
186 @node Copyright Papers
187 @section Copyright Papers
188 @cindex copyright papers
190 If you maintain an FSF-copyrighted package
191 certain legal procedures are required when incorporating legally significant
192 changes written by other people. This ensures that the FSF has the
193 legal right to distribute the package, and the standing to defend its
194 GPL-covered status in court if necessary.
196 @strong{Before} incorporating significant changes, make sure that the
197 person who wrote the changes has signed copyright papers and that the
198 Free Software Foundation has received and signed them. We may also need
199 a disclaimer from the person's employer.
201 @cindex data base of GNU copyright assignments
202 To check whether papers have been received, look in
203 @file{/gd/gnuorg/copyright.list}. If you can't look there directly,
204 @email{fsf-records@@gnu.org} can check for you. Our clerk can also
205 check for papers that are waiting to be entered and inform you when
206 expected papers arrive.
208 @cindex @file{/gd/gnuorg} directory
209 @c This paragraph intentionally duplicates information given
210 @c near the beginning of the file--to make sure people don't miss it.
211 The directory @file{/gd/gnuorg} is found on the GNU machines,
212 currently @code{fencepost.gnu.org}; if you are the maintainer of a GNU
213 package, you should have an account on them. Contact
214 @email{accounts@@gnu.org} if you don't have one. (You can also ask
215 for accounts for people who help you a large amount in working on the
218 In order for the contributor to know person should sign papers, you need
219 to ask for the necessary papers. If you don't know per well, and you
220 don't know that person is used to our ways of handling copyright papers,
221 then it might be a good idea to raise the subject with a message like
225 Would you be willing to assign the copyright to the Free Software
226 Foundation, so that we could install it in @var{program}?
233 Would you be willing to sign a copyright disclaimer to put this change
234 in the public domain, so that we can install it in @var{program}?
237 If the contributor wants more information, you can send per
238 @file{/gd/gnuorg/conditions.text}, which explains per options (assign
239 vs.@: disclaim) and their consequences.
241 Once the conversation is under way and the contributor is ready for
242 more details, you should send one of the templates that are found in
243 the directory @file{/gd/gnuorg/Copyright/}; they are also available
244 from the @file{doc/Copyright/} directory of the @code{gnulib} project
245 at @url{http://savannah.gnu.org/projects/gnulib}. This section
246 explains which templates you should use in which circumstances.
247 @strong{Please don't use any of the templates except for those listed
248 here, and please don't change the wording.}
250 Once the conversation is under way, you can send the contributor the
251 precise wording and instructions by email. Before you do this, make
252 sure to get the current version of the template you will use! We change
253 these templates occasionally---don't keep using an old version.
255 For large changes, ask the contributor for an assignment. Send per a
256 copy of the file @file{request-assign.changes}. (Like all the
257 @samp{request-} files, it is in @file{/gd/gnuorg/Copyright} and in
260 For medium to small changes, request a disclaimer by sending per the
261 file @file{request-disclaim.changes}.
263 If the contributor is likely to keep making changes, person might want
264 to sign an assignment for all per future changes to the program. So it
265 is useful to offer per that alternative. If person wants to do it that
266 way, send per the @file{request-assign.future}.
268 When you send a @file{request-} file, you don't need to fill in anything
269 before sending it. Just send the file verbatim to the contributor. The
270 file gives per instructions for how to ask the FSF to mail per the
271 papers to sign. The @file{request-} file also raises the issue of
272 getting a copyright disclaimer from the contributor's employer.
274 When the contributor emails the form to the FSF, the FSF sends per
275 papers to sign. If person signs them right away, the whole process
276 takes about two weeks--mostly waiting for letters to go back and
279 For less common cases, we have template files you should send to the
280 contributor. Be sure to fill in the name of the person and the name
281 of the program in these templates, where it says @samp{NAME OF PERSON}
282 and @samp{NAME OF PROGRAM}, before sending; otherwise person might
283 sign without noticing them, and the papers would be useless. Note
284 that in some templates there is more than one place to put the name of
285 the program or the name of the person; be sure to change all of them.
286 All the templates raise the issue of an employer's disclaimer as well.
288 @cindex legal papers for changes in manuals
289 You do not need to ask for separate papers for a manual that is
290 distributed only in the software package it describes. But if we
291 sometimes distribute the manual separately (for instance, if we publish
292 it as a book), then we need separate legal papers for changes in the
293 manual. For smaller changes, use
294 @file{disclaim.changes.manual}; for larger ones, use
295 @file{assign.changes.manual}. To cover both past and future
296 changes to a manual, you can use @file{assign.future.manual}.
297 For a translation of a manual, use @file{assign.translation.manual}.
299 If a contributor is reluctant to sign an assignment for a large change,
300 and is willing to sign a disclaimer instead, that is acceptable, so you
301 should offer this alternative if it helps you reach agreement. We
302 prefer an assignment for a larger change, so that we can enforce the GNU
303 GPL for the new text, but a disclaimer is enough to let us use the text.
305 If you maintain a collection of programs, occasionally someone will
306 contribute an entire separate program or manual that should be added to
307 the collection. Then you can use the files
308 @file{request-assign.program}, @file{disclaim.program},
309 @file{assign.manual}, and @file{disclaim.manual}. We very much prefer
310 an assignment for a new separate program or manual, unless it is quite
311 small, but a disclaimer is acceptable if the contributor insists on
312 handling the matter that way.
314 If a contributor wants the FSF to publish only a pseudonym, that is
315 ok. The contributor should say this, and state the desired pseudonym,
316 when answering the @file{request-} form. The actual legal papers will
317 use the real name, but the FSF will publish only the pseudonym. When
318 using one of the other forms, fill in the real name but ask the
319 contributor to discuss the use of a pseudonym with
320 @email{assign@@gnu.org} before sending back the signed form.
322 @strong{Although there are other templates besides the ones listed here,
323 they are for special circumstances; please do not use them without
324 getting advice from @email{assign@@gnu.org}.}
326 If you are not sure what to do, then please ask @email{assign@@gnu.org} for
327 advice; if the contributor asks you questions about the meaning and
328 consequences of the legal papers, and you don't know the answers, you
329 can forward them to @email{assign@@gnu.org} and we will answer.
331 @strong{Please do not try changing the wording of a template yourself.
332 If you think a change is needed, please talk with @email{assign@@gnu.org},
333 and we will work with a lawyer to decide what to do.}
335 @node Legally Significant
336 @section Legally Significant Changes
338 If a person contributes more than around 15 lines of code and/or text
339 that is legally significant for copyright purposes, which means we
340 need copyright papers for it as described above.
342 A change of just a few lines (less than 15 or so) is not legally
343 significant for copyright. A regular series of repeated changes, such
344 as renaming a symbol, is not legally significant even if the symbol
345 has to be renamed in many places. Keep in mind, however, that a
346 series of minor changes by the same person can add up to a significant
347 contribution. What counts is the total contribution of the person; it
348 is irrelevant which parts of it were contributed when.
350 Copyright does not cover ideas. If someone contributes ideas but no
351 text, these ideas may be morally significant as contributions, and
352 worth giving credit for, but they are not significant for copyright
353 purposes. Likewise, bug reports do not count for copyright purposes.
355 When giving credit to people whose contributions are not legally
356 significant for copyright purposes, be careful to make that fact
357 clear. The credit should clearly say they did not contribute
358 significant code or text.
360 When people's contributions are not legally significant because they
361 did not write code, do this by stating clearly what their contribution
362 was. For instance, you could write this:
367 * Richard Mlynarik <mly@@adoc.xerox.com> (1997)
368 * Masatake Yamato <masata-y@@is.aist-nara.ac.jp> (1999)
373 @code{Ideas by:} makes it clear that Mlynarik and Yamato here
374 contributed only ideas, not code. Without the @code{Ideas by:} note,
375 several years from now we would find it hard to be sure whether they
376 had contributed code, and we might have to track them down and ask
379 When you record a small patch in a change log file, first search for
380 previous changes by the same person, and see if per past
381 contributions, plus the new one, add up to something legally
382 significant. If so, you should get copyright papers for all per
383 changes before you install the new change.
385 If that is not so, you can install the small patch. Write @samp{(tiny
386 change)} after the patch author's name, like this:
389 2002-11-04 Robert Fenk <Robert.Fenk@@gmx.de> (tiny change)
392 @node Recording Contributors
393 @section Recording Contributors
394 @cindex recording contributors
396 @strong{Keep correct records of which portions were written by whom.}
397 This is very important. These records should say which files
398 parts of files, were written by each person, and which files or
399 portions were revised by each person. This should include
400 installation scripts as well as manuals and documentation
403 These records don't need to be as detailed as a change log. They
404 don't need to distinguish work done at different times, only different
405 people. They don't need describe changes in more detail than which
406 files or parts of a file were changed. And they don't need to say
407 anything about the function or purpose of a file or change--the
408 Register of Copyrights doesn't care what the text does, just who wrote
409 or contributed to which parts.
411 The list should also mention if certain files distributed in the same
412 package are really a separate program.
414 Only the contributions that are legally significant for copyright
415 purposes (@pxref{Legally Significant}) need to be listed. Small
416 contributions, bug reports, ideas, etc., can be omitted.
418 For example, this would describe an early version of GAS:
421 Dean Elsner first version of all files except gdb-lines.c and m68k.c.
422 Jay Fenlason entire files gdb-lines.c and m68k.c, most of app.c,
423 plus extensive changes in messages.c, input-file.c, write.c
424 and revisions elsewhere.
426 Note: GAS is distributed with the files obstack.c and obstack.h, but
427 they are considered a separate package, not part of GAS proper.
430 @cindex @file{AUTHORS} file
431 Please keep these records in a file named @file{AUTHORS} in the source
432 directory for the program itself.
434 You can use the change log as the basis for these records, if you
435 wish. Just make sure to record the correct author for each change
436 (the person who wrote the change, @emph{not} the person who installed
437 it), and add @samp{(tiny change)} for those changes that are too
438 trivial to matter for copyright purposes. Later on you can update the
439 @file{AUTHORS} file from the change log. This can even be done
440 automatically, if you are careful about the formatting of the change
443 @node Copying from Other Packages
444 @section Copying from Other Packages
446 When you copy legally significant code from another free software
447 package with a GPL-compatible license, you should look in the
448 package's records to find out the authors of the part you are copying,
449 and list them as the contributors of the code that you copied. If all
450 you did was copy it, not write it, then for copyright purposes you are
451 @emph{not} one of the contributors of @emph{this} code.
453 Especially when code has been released into the public domain, authors
454 sometimes fail to write a license statement in each file. In this
455 case, please first be sure that all the authors of the code have
456 disclaimed copyright interest. Then, when copying the new files into
457 your project, add a brief note at the beginning of the files recording
458 the authors, the public domain status, and anything else relevant.
460 On the other hand, when merging some public domain code into an
461 existing file covered by the GPL (or LGPL or other free software
462 license), there is no reason to indicate the pieces which are public
463 domain. The notice saying that the whole file is under the GPL (or
464 other license) is legally sufficient.
466 Using code that is released under a GPL-compatible free license,
467 rather than being in the public domain, may require preserving
468 copyright notices or other steps. Of course, you should do what is
471 If you are maintaining an FSF-copyrighted package, please verify we
472 have papers for the code you are copying, @emph{before} copying it.
473 If you are copying from another FSF-copyrighted package, then we
474 presumably have papers for that package's own code, but you must check
475 whether the code you are copying is part of an external library; if
476 that is the case, we don't have papers for it, so you should not copy
477 it. It can't hurt in any case to double-check with the developer of
480 When you are copying code for which we do not already have papers, you
481 need to get papers for it. It may be difficult to get the papers if
482 the code was not written as a contribution to your package, but that
483 doesn't mean it is ok to do without them. If you cannot get papers
484 for the code, you can only use it as an external library
485 (@pxref{External Libraries}).
488 @node Copyright Notices
489 @section Copyright Notices
490 @cindex copyright notices in program files
492 You should maintain a proper copyright notice and a license
493 notice in each nontrivial file in the package. (Any file more than ten
494 lines long is nontrivial for this purpose.) This includes header files
495 and interface definitions for
496 building or running the program, documentation files, and any supporting
497 files. If a file has been explicitly placed in the public domain, then
498 instead of a copyright notice, it should have a notice saying explicitly
499 that it is in the public domain.
501 Even image files and sound files should contain copyright notices and
502 license notices, if they can. Some formats do not have room for textual
503 annotations; for these files, state the copyright and copying
504 permissions in a README file in the same directory.
506 Change log files should have a copyright notice and license notice at
507 the end, since new material is added at the beginning but the end
510 When a file is automatically generated from some other file in the
511 distribution, it is useful for the automatic procedure to copy the
512 copyright notice and permission notice of the file it is generated
513 from, if possible. Alternatively, put a notice at the beginning saying
514 which file it is generated from.
516 A copyright notice looks like this:
519 Copyright (C) @var{year1}, @var{year2}, @var{year3} @var{copyright-holder}
522 The @var{copyright-holder} may be the Free Software Foundation, Inc., or
523 someone else; you should know who is the copyright holder for your
526 Replace the @samp{(C)} with a C-in-a-circle symbol if it is available.
527 For example, use @samp{@@copyright@{@}} in a Texinfo file. However,
528 stick with parenthesized @samp{C} unless you know that C-in-a-circle
529 will work. For example, a program's standard @option{--version}
530 message should use parenthesized @samp{C} by default, though message
531 translations may use C-in-a-circle in locales where that symbol is
534 To update the list of year numbers, add each year in which you have
535 made nontrivial changes to the package. (Here we assume you're using
536 a publicly accessible revision control server, so that every revision
537 installed is also immediately and automatically published.) When you
538 add the new year, it is not required to keep track which files have
539 seen significant changes in the new year and which have not. It is
540 recommended and simpler to add the new year to all files in the
541 package, and be done with it for the rest of the year.
543 For files which are regularly copied from another project (such as
544 @samp{gnulib}), the copyright notice should left as it is in the
547 Don't delete old year numbers, though; they can indicate when older
548 versions might theoretically go into the public domain. If you copy a
549 file into the package from some other program, keep the copyright
550 years that come with the file.
552 Do not abbreviate the year list using a range; for instance, do not
553 write @samp{1996--1998}; instead, write @samp{1996, 1997, 1998}.
555 The copyright statement may be split across multiple lines, both in
556 source files and in any generated output. This often happens for
557 files with a long history, having many different years of
560 For an FSF-copyrighted package, if you have followed the procedures to
561 obtain legal papers, each file should have just one copyright holder:
562 the Free Software Foundation, Inc. You should edit the file's
563 copyright notice to list that name and only that name.
565 But if contributors are not all assigning their copyrights to a single
566 copyright holder, it can easily happen that one file has several
567 copyright holders. Each contributor of nontrivial text is a copyright
570 In that case, you should always include a copyright notice in the name
571 of main copyright holder of the file. You can also include copyright
572 notices for other copyright holders as well, and this is a good idea
573 for those who have contributed a large amount and for those who
574 specifically ask for notices in their names. (Sometimes the license
575 on code that you copy in may require preserving certain copyright
576 notices.) But you don't have to include a notice for everyone who
577 contributed to the file (which would be rather inconvenient).
579 Sometimes a program has an overall copyright notice that refers to the
580 whole program. It might be in the @file{README} file, or it might be
581 displayed when the program starts up. This copyright notice should
582 mention the year of completion of the most recent major version; it
583 can mention years of completion of previous major versions, but that
587 @node License Notices
588 @section License Notices
589 @cindex license notices in program files
591 Every nontrivial file needs a license notice as well as the copyright
592 notice. (Without a license notice giving permission to copy and
593 change the file, the file is non-free.)
595 The package itself should contain a full copy of GPL (conventionally
596 in a file named @file{COPYING}) and the GNU Free Documentation License
597 (included within your documentation). If the package contains any
598 files distributed under the Lesser GPL, it should contain a full copy
599 of that as well (conventionally in a file named
600 @file{COPYING.LESSER}).
602 If you have questions about license issues for your GNU package,
603 please write @email{licensing@@gnu.org}.
606 * Source: Canonical License Sources.
607 * Code: License Notices for Code.
608 * Documentation: License Notices for Documentation.
609 * Other: License Notices for Other Files.
613 @node Canonical License Sources
614 @subsection Canonical License Sources
616 You can get the official versions of these files from several places.
617 You can use whichever is the most convenient for you.
621 @uref{http://www.gnu.org/licenses/}.
624 The @code{gnulib} project on @code{savannah.gnu.org}, which you
625 can access via anonymous Git or CVS. See
626 @uref{http://savannah.gnu.org/projects/gnulib}.
630 The official Texinfo sources for the licenses are also available in
631 those same places, so you can include them in your documentation. A
632 GFDL-covered manual should include the GFDL in this way. @xref{GNU
633 Sample Texts,,,texinfo,Texinfo}, for a full example in a Texinfo
637 @node License Notices for Code
638 @subsection License Notices for Code
640 Typically the license notice for program files (including build scripts,
641 configure files and makefiles) should cite the GPL, like this:
644 This file is part of GNU @var{program}.
646 GNU @var{program} is free software: you can redistribute it and/or
647 modify it under the terms of the GNU General Public License as
648 published by the Free Software Foundation, either version 3 of the
649 License, or (at your option) any later version.
651 GNU @var{program} is distributed in the hope that it will be useful,
652 but WITHOUT ANY WARRANTY; without even the implied warranty of
653 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
654 GNU General Public License for more details.
656 You should have received a copy of the GNU General Public License
657 along with this program. If not, see @url{http://www.gnu.org/licenses/}.
660 But in a small program which is just a few files, you can use
664 This program is free software: you can redistribute it and/or modify
665 it under the terms of the GNU General Public License as published by
666 the Free Software Foundation; either version 3 of the License, or
667 (at your option) any later version.
669 This program is distributed in the hope that it will be useful,
670 but WITHOUT ANY WARRANTY; without even the implied warranty of
671 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
672 GNU General Public License for more details.
674 You should have received a copy of the GNU General Public License
675 along with this program. If not, see @url{http://www.gnu.org/licenses/}.
679 @node License Notices for Documentation
680 @subsection License Notices for Documentation
682 Documentation files should have license notices also. Manuals should
683 use the GNU Free Documentation License. Following is an example of the
684 license notice to use after the copyright line(s) using all the
685 features of the GFDL.
688 Permission is granted to copy, distribute and/or modify this document
689 under the terms of the GNU Free Documentation License, Version 1.2 or
690 any later version published by the Free Software Foundation; with the
691 Invariant Sections being ``GNU General Public License'', with the
692 Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts
693 as in (a) below. A copy of the license is included in the section
694 entitled ``GNU Free Documentation License''.
696 (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
697 this GNU Manual. Buying copies from GNU Press supports the FSF in
698 developing GNU and promoting software freedom.''
701 If the FSF does not publish this manual on paper, then omit the last
702 sentence in (a) that talks about copies from GNU Press. If the FSF is
703 not the copyright holder, then replace @samp{FSF} with the appropriate
706 Please adjust the list of invariant sections as appropriate for your
707 manual. If there are none, then say ``with no Invariant Sections''.
708 If your manual is not published by the FSF, and under 400 pages, you
709 can omit both cover texts and the inclusion of the GPL.
711 @xref{GNU Sample Texts,,,texinfo,Texinfo}, for a full example in a
712 Texinfo manual, and see
713 @url{http://www.gnu.org/licenses/fdl-howto.html} for more advice about
714 how to use the GNU FDL.
716 If the manual is over 400 pages, or if the FSF thinks it might be a good
717 choice for publishing on paper, then please include our standard
718 invariant section which explains the importance of free documentation.
719 Write to @email{assign@@gnu.org} to get a copy of this section.
721 When you distribute several manuals together in one software package,
722 their on-line forms can share a single copy of the GFDL (see
723 section@tie{}6). However, the printed (@samp{.dvi}, @samp{.pdf},
724 @dots{}) forms should each contain a copy of the GFDL, unless they are
725 set up to be printed and published only together. Therefore, it is
726 usually simplest to include the GFDL in each manual.
729 @node License Notices for Other Files
730 @subsection License Notices for Other Files
732 Small supporting files, short manuals (under 300 lines long) and rough
733 documentation (README files, INSTALL files, etc) can use a simple
734 all-permissive license like this one:
737 Copying and distribution of this file, with or without modification,
738 are permitted in any medium without royalty provided the copyright
739 notice and this notice are preserved.
742 If your package distributes Autoconf macros that are intended to be
743 used (hence distributed) by third-party packages under possibly
744 incompatible licenses, you may also use the above all-permissive
745 license for these macros.
748 @node External Libraries
749 @section External Libraries
751 When maintaining an FSF-copyrighted GNU package, you may occasionally
752 want to use a general-purpose free software module which offers a
753 useful functionality, as a ``library'' facility (though the module is
754 not always packaged technically as a library).
756 In a case like this, it would be unreasonable to ask the author of that
757 module to assign the copyright to the FSF. After all, person did not
758 write it specifically as a contribution to your package, so it would be
759 impertinent to ask per, out of the blue, ``Please give the FSF your
762 So the thing to do in this case is to make your program use the module,
763 but not consider it a part of your program. There are two reasonable
764 methods of doing this:
768 Assume the module is already installed on the system, and use it when
769 linking your program. This is only reasonable if the module really has
770 the form of a library.
773 Include the module in your package, putting the source in a separate
774 subdirectory whose @file{README} file says, ``This is not part of the
775 GNU FOO program, but is used with GNU FOO.'' Then set up your makefiles
776 to build this module and link it into the executable.
778 For this method, it is not necessary to treat the module as a library
779 and make a @samp{.a} file from it. You can link with the @samp{.o}
780 files directly in the usual manner.
783 Both of these methods create an irregularity, and our lawyers have told
784 us to minimize the amount of such irregularity. So consider using these
785 methods only for general-purpose modules that were written for other
786 programs and released separately for general use. For anything that was
787 written as a contribution to your package, please get papers signed.
791 @chapter Cleaning Up Changes
792 @cindex contributions, accepting
793 @cindex quality of changes suggested by others
795 Don't feel obligated to include every change that someone asks you to
796 include. You must judge which changes are improvements---partly based
797 on what you think the users will like, and partly based on your own
798 judgment of what is better. If you think a change is not good, you
801 If someone sends you changes which are useful, but written in an ugly
802 way or hard to understand and maintain in the future, don't hesitate to
803 ask per to clean up their changes before you merge them. Since the
804 amount of work we can do is limited, the more we convince others to help
805 us work efficiently, the faster GNU will advance.
807 If the contributor will not or can not make the changes clean enough,
808 then it is legitimate to say ``I can't install this in its present form;
809 I can only do so if you clean it up.'' Invite per to distribute per
810 changes another way, or to find other people to make them clean enough
811 for you to install and maintain.
813 The only reason to do these cleanups yourself is if (1) it is easy, less
814 work than telling the author what to clean up, or (2) the change is an
815 important one, important enough to be worth the work of cleaning it up.
817 The GNU Coding Standards are a good thing to send people when you ask
818 them to clean up changes (@pxref{Top, , Contents, standards, GNU Coding
819 Standards}). The Emacs Lisp manual contains an appendix that gives
820 coding standards for Emacs Lisp programs; it is good to urge authors to
821 read it (@pxref{Tips, , Tips and Standards, elisp, The GNU Emacs Lisp
826 @chapter Platforms to Support
828 Most GNU packages run on a wide range of platforms. These platforms are
829 not equally important.
831 The most important platforms for a GNU package to support are GNU and
832 GNU/Linux. Developing the GNU operating system is the whole point of
833 the GNU Project; a GNU package exists to make the whole GNU system more
834 powerful. So please keep that goal in mind and let it shape your work.
835 For instance, every new feature you add should work on GNU, and
836 GNU/Linux if possible too. If a new feature only runs on GNU and
837 GNU/Linux, it could still be acceptable. However, a feature that runs
838 only on other systems and not on GNU or GNU/Linux makes no sense in a
841 You will naturally want to keep the program running on all the platforms
842 it supports. But you personally will not have access to most of these
843 platforms--so how should you do it?
845 Don't worry about trying to get access to all of these platforms. Even
846 if you did have access to all the platforms, it would be inefficient for
847 you to test the program on each platform yourself. Instead, you should
848 test the program on a few platforms, including GNU or GNU/Linux, and let
849 the users test it on the other platforms. You can do this through a
850 pretest phase before the real release; when there is no reason to expect
851 problems, in a package that is mostly portable, you can just make a
852 release and let the users tell you if anything unportable was
855 It is important to test the program personally on GNU or GNU/Linux,
856 because these are the most important platforms for a GNU package. If
857 you don't have access to one of these platforms, please ask
858 @email{maintainers@@gnu.org} to help you out.
860 Supporting other platforms is optional---we do it when that seems like
861 a good idea, but we don't consider it obligatory. If the users don't
862 take care of a certain platform, you may have to desupport it unless
863 and until users come forward to help. Conversely, if a user offers
864 changes to support an additional platform, you will probably want to
865 install them, but you don't have to. If you feel the changes are
866 complex and ugly, if you think that they will increase the burden of
867 future maintenance, you can and should reject them. This includes
868 both free or mainly-free platforms such as OpenBSD, FreeBSD, and
869 NetBSD, and non-free platforms such as Windows.
873 @chapter Dealing With Mail
876 @cindex email, for receiving bug reports
877 @cindex mailing list for bug reports
878 Once a program is in use, you will get bug reports for it. Most GNU
879 programs have their own special lists for sending bug reports. The
880 advertised bug-reporting email address should always be
881 @samp{bug-@var{program}@@gnu.org}, to help show users that the program
882 is a GNU package, but it is ok to set up that list to forward to another
883 site for further forwarding. The package distribution should state the
884 name of the bug-reporting list in a prominent place, and ask users to
885 help us by reporting bugs there.
887 We also have a catch-all list, @email{bug-gnu-utils@@gnu.org}, which is
888 used for all GNU programs that don't have their own specific lists. But
889 nowadays we want to give each program its own bug-reporting list and
890 move away from using @email{bug-gnu-utils}.
892 If you are the maintainer of a GNU package, you should have an account
893 on the GNU servers; contact @email{accounts@@gnu.org} if you don't have
894 one. (You can also ask for accounts for people who help you a large
895 amount in working on the package.) With this account, you can edit
896 @file{/com/mailer/aliases} to create a new unmanaged list or add
897 yourself to an existing unmanaged list. A comment near the beginning of
898 that file explains how to create a Mailman-managed mailing list.
900 But if you don't want to learn how to do those things, you can
901 alternatively ask @email{alias-file@@gnu.org} to add you to the
902 bug-reporting list for your program. To set up a new list, contact
903 @email{new-mailing-list@@gnu.org}. You can subscribe to a list managed
904 by Mailman by sending mail to the corresponding @samp{-request} address.
906 You should moderate postings from non-subscribed addresses on your
907 mailing lists, to prevent propagation of unwanted messages (``spam'')
908 to subscribers and to the list archives. For lists controlled by
909 Mailman, you can do this by setting @code{Privacy Options - Sender
910 Filter - generic_nonmember_action} to @code{Hold}, and then
911 periodically (daily is best) reviewing the held messages, accepting
912 the real ones and discarding the junk.
914 @cindex responding to bug reports
915 When you receive bug reports, keep in mind that bug reports are crucial
916 for your work. If you don't know about problems, you cannot fix them.
917 So always thank each person who sends a bug report.
919 You don't have an obligation to give more response than that, though.
920 The main purpose of bug reports is to help you contribute to the
921 community by improving the next version of the program. Many of the
922 people who report bugs don't realize this---they think that the point is
923 for you to help them individually. Some will ask you to focus on that
924 @emph{instead of} on making the program better. If you comply with
925 their wishes, you will have been distracted from the job of maintaining
928 For example, people sometimes report a bug in a vague (and therefore
929 useless) way, and when you ask for more information, they say, ``I just
930 wanted to see if you already knew the solution'' (in which case the bug
931 report would do nothing to help improve the program). When this
932 happens, you should explain to them the real purpose of bug reports. (A
933 canned explanation will make this more efficient.)
935 When people ask you to put your time into helping them use the program,
936 it may seem ``helpful'' to do what they ask. But it is much @emph{less}
937 helpful than improving the program, which is the maintainer's real job.
939 By all means help individual users when you feel like it, if you feel
940 you have the time available. But be careful to limit the amount of time
941 you spend doing this---don't let it eat away the time you need to
942 maintain the program! Know how to say no; when you are pressed for
943 time, just ``thanks for the bug report---I will fix it'' is enough
946 Some GNU packages, such as Emacs and GCC, come with advice about how to
947 make bug reports useful. If you want to copy and adapt that, it could
948 be a very useful thing to do.
952 @chapter Recording Old Versions
953 @cindex version control
955 It is very important to keep backup files of all source files of GNU.
956 You can do this using a source control system (such as RCS, CVS, Git,
957 @dots{}) if you like. The easiest way to use RCS or CVS is via the
958 Version Control library in Emacs (@pxref{VC Concepts,, Concepts of
959 Version Control, emacs, The GNU Emacs Manual}).
961 The history of previous revisions and log entries is very important for
962 future maintainers of the package, so even if you do not make it
963 publicly accessible, be careful not to put anything in the repository or
964 change log that you would not want to hand over to another maintainer
967 The GNU Project provides a server that GNU software packages can use
968 for source control and other package needs: @code{savannah.gnu.org}.
969 You don't have to use this repository, but if you plan to allow public
970 read-only access to your development sources, it is convenient for
971 people to be able to find various GNU packages in a central place.
972 Savannah is managed by @email{savannah-hackers@@gnu.org}.
974 All GNU maintainers are encouraged to take advantage of Savannah, as
975 sharing such a central point can serve to foster a sense of community
976 among GNU developers and help in keeping up with project management.
980 @chapter Distributions
982 It is important to follow the GNU conventions when making GNU software
986 * Distribution tar Files::
987 * Distribution Patches::
988 * Distribution on ftp.gnu.org::
990 * Automated FTP Uploads::
994 @node Distribution tar Files
995 @section Distribution tar Files
996 @cindex distribution, tar files
998 The tar file for version @var{m}.@var{n} of program @code{foo} should be
999 named @file{foo-@var{m}.@var{n}.tar}. It should unpack into a
1000 subdirectory named @file{foo-@var{m}.@var{n}}. Tar files should not
1001 unpack into files in the current directory, because this is inconvenient
1002 if the user happens to unpack into a directory with other files in it.
1004 Here is how the @file{Makefile} for Bison creates the tar file.
1005 This method is good for other programs.
1009 echo bison-`sed -e '/version_string/!d' \
1010 -e 's/[^0-9.]*\([0-9.]*\).*/\1/' -e q version.c` > .fname
1011 -rm -rf `cat .fname`
1013 dst=`cat .fname`; for f in $(DISTFILES); do \
1014 ln $(srcdir)/$$f $$dst/$$f || @{ echo copying $$f; \
1015 cp -p $(srcdir)/$$f $$dst/$$f ; @} \
1017 tar --gzip -chf `cat .fname`.tar.gz `cat .fname`
1018 -rm -rf `cat .fname` .fname
1021 Source files that are symbolic links to other file systems cannot be
1022 installed in the temporary directory using @code{ln}, so use @code{cp}
1026 Using Automake is a good way to take care of writing the @code{dist}
1029 @node Distribution Patches
1030 @section Distribution Patches
1031 @cindex patches, against previous releases
1033 If the program is large, it is useful to make a set of diffs for each
1034 release, against the previous important release.
1036 At the front of the set of diffs, put a short explanation of which
1037 version this is for and which previous version it is relative to.
1038 Also explain what else people need to do to update the sources
1039 properly (for example, delete or rename certain files before
1040 installing the diffs).
1042 The purpose of having diffs is that they are small. To keep them
1043 small, exclude files that the user can easily update. For example,
1044 exclude info files, DVI files, tags tables, output files of Bison or
1045 Flex. In Emacs diffs, we exclude compiled Lisp files, leaving it up
1046 to the installer to recompile the patched sources.
1048 When you make the diffs, each version should be in a directory suitably
1049 named---for example, @file{gcc-2.3.2} and @file{gcc-2.3.3}. This way,
1050 it will be very clear from the diffs themselves which version is which.
1054 @cindex time stamp in diffs
1055 If you use GNU @code{diff} to make the patch, use the options
1056 @samp{-rc2P}. That will put any new files into the output as ``entirely
1057 different.'' Also, the patch's context diff headers should have dates
1058 and times in Universal Time using traditional Unix format, so that patch
1059 recipients can use GNU @code{patch}'s @samp{-Z} option. For example,
1060 you could use the following Bourne shell command to create the patch:
1063 LC_ALL=C TZ=UTC0 diff -rc2P gcc-2.3.2 gcc-2.3.3 | \
1064 gzip -9 >gcc-2.3.2-2.3.3.patch.gz
1067 If the distribution has subdirectories in it, then the diffs probably
1068 include some files in the subdirectories. To help users install such
1069 patches reliably, give them precise directions for how to run patch.
1070 For example, say this:
1073 To apply these patches, cd to the main directory of the program
1074 and then use `patch -p1'. `-p1' avoids guesswork in choosing
1075 which subdirectory to find each file in.
1078 It's wise to test your patch by applying it to a copy of the old
1079 version, and checking that the result exactly matches the new version.
1081 @node Distribution on ftp.gnu.org
1082 @section Distribution on @code{ftp.gnu.org}
1083 @cindex GNU ftp site
1084 @cindex @code{ftp.gnu.org}, the GNU ftp site
1086 GNU packages are distributed through directory @file{/gnu} on
1087 @code{ftp.gnu.org}. Each package should have a subdirectory
1088 named after the package, and all the distribution files for the package
1089 should go in that subdirectory.
1091 @c If you have an interest in seeing the monthly download logs from the FTP
1092 @c site at @code{ftp.gnu.org} for your program, that is something that
1093 @c @email{ftp-upload@@gnu.org} can set up for you. Please contact them if
1094 @c you are interested.
1096 @xref{Automated FTP Uploads}, for procedural details of putting new
1097 versions on @code{ftp.gnu.org}.
1100 @section Test Releases
1101 @cindex test releases
1102 @cindex beta releases
1103 @cindex pretest releases
1105 @cindex @code{alpha.gnu.org}, ftp site for test releases
1106 When you release a greatly changed new major version of a program, you
1107 might want to do so as a pretest. This means that you make a tar file,
1108 but send it only to a group of volunteers that you have recruited. (Use
1109 a suitable GNU mailing list/newsgroup to recruit them.)
1111 We normally use the FTP server @code{alpha.gnu.org} for pretests and
1112 prerelease versions. @xref{Automated FTP Uploads}, for procedural details
1113 of putting new versions on @code{alpha.gnu.org}.
1115 Once a program gets to be widely used and people expect it to work
1116 solidly, it is a good idea to do pretest releases before each ``real''
1119 There are two ways of handling version numbers for pretest versions.
1120 One method is to treat them as versions preceding the release you are going
1123 In this method, if you are about to release version 4.6 but you want
1124 to do a pretest first, call it 4.5.90. If you need a second pretest,
1125 call it 4.5.91, and so on. If you are really unlucky and ten pretests
1126 are not enough, after 4.5.99 you could advance to 4.5.990 and so on.
1127 (You could also use 4.5.100, but 990 has the advantage of sorting in
1130 The other method is to attach a date to the release number that is
1131 coming. For a pretest for version 4.6, made on Dec 10, 2002, this
1132 would be 4.6.20021210. A second pretest made the same day could be
1135 For development snapshots that are not formal pretests, using just
1136 the date without the version numbers is ok too.
1138 One thing that you should never do is to release a pretest with the same
1139 version number as the planned real release. Many people will look only
1140 at the version number (in the tar file name, in the directory name that
1141 it unpacks into, or wherever they can find it) to determine whether a
1142 tar file is the latest version. People might look at the test release
1143 in this way and mistake it for the real release. Therefore, always
1144 change the number when you release changed code.
1147 @node Automated FTP Uploads
1148 @section Automated FTP Uploads
1150 @cindex ftp uploads, automated
1151 In order to upload new releases to @code{ftp.gnu.org} or
1152 @code{alpha.gnu.org}, you first need to register the necessary
1153 information. Then, you can perform uploads yourself, with no
1154 intervention needed by the system administrators.
1156 The general idea is that releases should be crytographically signed
1157 before they are made publicly available.
1160 * Automated Upload Registration::
1161 * Automated Upload Procedure::
1162 * FTP Upload Directive File - v1.1::
1163 * FTP Upload Directive File - v1.0::
1167 @node Automated Upload Registration
1168 @subsection Automated Upload Registration
1170 @cindex registration
1171 @cindex uploads, registration for
1173 Here is how to register your information so you can perform uploads
1174 for your GNU package:
1179 Create an account for yourself at @url{http://savannah.gnu.org}, if
1180 you don't already have one. By the way, this is also needed to
1181 maintain the web pages for your project also (@pxref{Web Pages}).
1184 In the @samp{My Account Conf} page on @code{savannah}, upload the GPG
1185 key you will use to sign your packages. You can create a key with the
1186 command @code{gpg --gen-key}. (For full information about GPG, see
1187 @url{http://www.gnu.org/software/gpg}).
1190 Send a message, preferably GPG-signed, to @email{ftp-upload@@gnu.org}
1195 Name of package(s) that you are the maintainer for, and your
1196 preferred email address.
1199 An ASCII armored copy of your GnuPG key, as an attachment. (@samp{gpg
1200 --export -a @var{your_key_id} >mykey.asc} should give you this.)
1203 A list of names and preferred email addresses of other individuals you
1204 authorize to make releases for which packages, if any (in the case that you
1205 don't make all releases yourself).
1208 ASCII armored copies of GnuPG keys for any individuals listed in (3).
1212 The administrators will acknowledge your message when they have added
1213 the proper GPG keys as authorized to upload files for the
1214 corresponding packages.
1217 @node Automated Upload Procedure
1218 @subsection Automated Upload Procedure
1222 Once you have registered your information as described in the
1223 previous section, you will be able to do unattended ftp uploads using
1224 the following procedure.
1226 For each upload destined for @code{ftp.gnu.org} or
1227 @code{alpha.gnu.org}, three files (a @dfn{triplet}) need to be
1228 uploaded via ftp to the host @code{ftp-upload.gnu.org}.
1232 The file to be distributed (for example, @file{foo.tar.gz}).
1235 Detached GPG binary signature for (1), made using @samp{gpg -b}
1236 (for example, @file{foo.tar.gz.sig}).
1239 A clearsigned @dfn{directive file}, made using @samp{gpg --clearsign}
1240 (for example, @file{foo.tar.gz.directive.asc}).
1243 The names of the files are important. The signature file must have the
1244 same name as the file to be distributed, with an additional
1245 @file{.sig} extension. The directive file must have the same name as
1246 the file to be distributed, with an additional @file{.directive.asc}
1247 extension. If you do not follow this naming convention, the upload
1248 @emph{will not be processed}.
1250 Since v1.1 of the upload script, it is also possible to upload a
1251 @dfn{directive file} on its own to perform certain operations on
1252 uploaded files. @xref{FTP Upload Directive File - v1.1}, for more
1255 Upload the file(s) via anonymous ftp to @code{ftp-upload.gnu.org}. If
1256 the upload is destined for @code{ftp.gnu.org}, place the file(s) in
1257 the @file{/incoming/ftp} directory. If the upload is destined for
1258 @code{alpha.gnu.org}, place the file(s) in the @file{/incoming/alpha}
1261 Uploads are processed every five minutes. Uploads that are in
1262 progress while the upload processing script is running are handled
1263 properly, so do not worry about the timing of your upload. Uploaded
1264 files that belong to an incomplete triplet are deleted automatically
1267 Your designated upload email addresses (@pxref{Automated Upload Registration})
1268 are sent a message if there are any problems processing an upload for your
1269 package. You also receive a message when your upload has been successfully
1272 If you have difficulties processing an upload, email
1273 @email{ftp-upload@@gnu.org}.
1276 @node FTP Upload Directive File - v1.1
1277 @subsection FTP Upload Directive File - v1.1
1279 The directive file name must end in @file{directive.asc}.
1281 When part of a triplet, the directive file must always contain the
1282 directives @code{version}, @code{directory} and @code{filename}, as
1283 described. In addition, a 'comment' directive is allowed.
1285 The @code{version} directive must always have the value @samp{1.1}.
1287 The @code{directory} directive specifies the final destination
1288 directory where the uploaded file and its @file{.sig} companion are to
1291 The @code{filename} directive must contain the name of the file to be
1292 distributed (item@tie{}(1) above).
1294 For example, as part of an uploaded triplet, a
1295 @file{foo.tar.gz.directive.asc} file might contain these lines (before
1296 being gpg clearsigned):
1301 filename: foo.tar.gz
1302 comment: hello world!
1305 This directory line indicates that @file{foo.tar.gz} and
1306 @file{foo.tar.gz.sig} are part of package @code{bar}. If you uploaded
1307 this triplet to @file{/incoming/ftp} and the system positively
1308 authenticates the signatures, the files @file{foo.tar.gz} and
1309 @file{foo.tar.gz.sig} will be placed in the directory
1310 @file{gnu/bar/v1} of the @code{ftp.gnu.org} site.
1312 The directive file can be used to create currently non-existent
1313 directory trees, as long as they are under the package directory for
1314 your package (in the example above, that is @code{bar}).
1316 If you upload a file that already exists in the FTP directory, the
1317 original will simply be archived and replaced with the new upload.
1319 @subheading Standalone directives
1321 When uploaded by itself, the directive file must contain one or more
1322 of the directives @code{symlink}, @code{rmsymlink} or @code{archive},
1323 in addition to the obligatory @code{directory} and @code{version}
1324 directives. A @code{filename} directive is not allowed, and a
1325 @code{comment} directive is optional.
1327 If you use more than one directive, the directives are executed in the
1328 sequence they are specified in.
1330 Here are a few examples. The first removes a symlink:
1335 rmsymlink: foo-latest.tgz
1336 comment: remove a symlink
1340 Archive an old file, taking it offline:
1345 archive: foo-1.1.tar.gz
1346 comment: archive an old file; it will not be available through FTP anymore
1350 Archive an old directory (with all contents), taking it offline:
1356 comment: archive an old directory; it will not be available through FTP anymore
1360 Create a new symlink:
1365 symlink: foo-1.2.tar.gz foo-latest.tgz
1366 comment: create a new symlink
1370 Do everything at once:
1375 rmsymlink: foo-latest.tgz
1376 symlink: foo-1.2.tar.gz foo-latest.tgz
1377 archive: foo-1.1.tar.gz
1378 comment: now do everything at once
1382 @node FTP Upload Directive File - v1.0
1383 @subsection FTP Upload Directive File - v1.0
1385 @dfn{As of June 2006, the upload script is running in compatibility
1386 mode, allowing uploads with either version@tie{}1.1 or
1387 version@tie{}1.0 of the directive file syntax. Support for v1.0
1388 uploads will be phased out by the end of 2006, so please upgrade
1391 The directive file should contain one line, excluding the clearsigned
1392 data GPG that inserts, which specifies the final destination directory
1393 where items (1) and (2) are to be placed.
1395 For example, the @file{foo.tar.gz.directive.asc} file might contain the
1402 This directory line indicates that @file{foo.tar.gz} and
1403 @file{foo.tar.gz.sig} are part of package @code{bar}. If you were to
1404 upload the triplet to @file{/incoming/ftp}, and the system can
1405 positively authenticate the signatures, then the files
1406 @file{foo.tar.gz} and @file{foo.tar.gz.sig} will be placed in the
1407 directory @file{gnu/bar/v1} of the @code{ftp.gnu.org} site.
1409 The directive file can be used to create currently non-existent
1410 directory trees, as long as they are under the package directory for
1411 your package (in the example above, that is @code{bar}).
1415 @section Announcing Releases
1417 When you have a new release, please make an announcement. You can
1418 maintain your own mailing list for announcements if you like, or you can
1419 use the moderated general GNU announcements list,
1420 @email{info-gnu@@gnu.org}.
1422 If you use your own list, you can decide as you see fit what events are
1423 worth announcing. If you use @email{info-gnu@@gnu.org}, please do not
1424 announce pretest releases, only real releases. But real releases do
1425 include releases made just to fix bugs.
1432 Please write web pages about your package for installation on
1433 @code{www.gnu.org}. They should follow our usual standards for web
1434 pages (see @url{http://www.gnu.org/server}); we chose them in order to
1435 support a wide variety of browsers, to focus on information rather
1436 than flashy eye candy, and to keep the site simple and uniform.
1438 The simplest way to maintain the web pages for your project is to
1439 register the project on @code{savannah.gnu.org}. Then you can edit
1440 the pages using CVS. You can keep the source files there too, but if
1441 you want to use @code{savannah.gnu.org} only for the web pages, simply
1442 register a ``web-only'' project.
1444 If you don't want to use that method, please talk with
1445 @email{webmasters@@gnu.org} about other possible methods. For
1446 instance, you can mail them pages to install, if necessary. But that
1447 is more work for them, so please use CVS if you can.
1449 Some GNU packages have just simple web pages, but the more information
1450 you provide, the better. So please write as much as you usefully can,
1451 and put all of it on @code{www.gnu.org}. However, pages that access
1452 databases (including mail logs and bug tracking) are an exception; set
1453 them up on whatever site is convenient for you, and make the pages on
1454 @code{www.gnu.org} link to that site.
1456 Historically, web pages for GNU packages did not include GIF images,
1457 because of patent problems (@pxref{Ethical and Philosophical
1458 Consideration}). Although the GIF patents expired in 2006, using GIF
1459 images is still not recommended, as the PNG and JPEG formats are
1460 generally superior. See @url{http://www.gnu.org/philosophy/gif.html}.
1462 If you use a site other than @code{www.gnu.org}, please make sure that
1463 the site runs on free software alone. (It is ok if the site uses
1464 unreleased custom software, since that is free in a trivial sense:
1465 there's only one user and it has the four freedoms.) If the web site
1466 for a GNU package runs on non-free software, the public will see this,
1467 and it will have the effect of granting legitimacy to the non-free
1470 If you use multiple sites, they should all follow that criterion.
1471 Please don't link to a site that is about your package, which the
1472 public might perceive as connected with it and reflecting the position
1473 of its developers, unless it follows that criterion.
1475 The web pages for the package should include its manuals, in HTML,
1476 DVI, Info, PostScript, PDF, plain ASCII, and Texinfo format (source).
1477 (All of these can be generated automatically from the Texinfo source
1478 using Makeinfo and other programs.) When there is only one manual,
1479 put it in a subdirectory called @file{manual}; the file
1480 @file{manual/index.html} should have a link to the manual in each of
1483 If the package has more than one manual, put each one in a
1484 subdirectory of @file{manual}, set up @file{index.html} in each
1485 subdirectory to link to that manual in all its forms, and make
1486 @file{manual/index.html} link to each manual through its subdirectory.
1488 See the section below for details on a script to make the job of
1489 creating all these different formats and index pages easier.
1491 We would like to include links to all these manuals in the page
1492 @url{http://www.gnu.org/manual}. Just send mail to
1493 @code{webmasters@@gnu.org} telling them the name of your package and
1494 asking them to edit @url{http://www.gnu.org/manual}, and they will do
1495 so based on the contents of your @file{manual} directory.
1498 * Invoking gendocs.sh::
1499 * CVS Keywords in Web Pages::
1503 @node Invoking gendocs.sh
1504 @section Invoking @command{gendocs.sh}
1506 @cindex generating documentation output
1508 The script @command{gendocs.sh} eases the task of generating the
1509 Texinfo documentation output for your web pages
1510 section above. It has a companion template file, used as the basis
1511 for the HTML index pages. Both are available from the Texinfo CVS
1514 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh}
1515 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template}
1518 There is also a ``minimalistic'' template version, available from:
1521 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template_min}
1524 Invoke the script like this, in the directory containing the Texinfo
1527 gendocs.sh @var{yourmanual} "GNU @var{yourmanual} manual"
1530 @noindent where @var{yourmanual} is the short name for your package.
1531 The script processes the file @file{@var{yourmanual}.texinfo} (or
1532 @file{.texi} or @file{.txi}). For example:
1536 # download gendocs.sh and gendocs_template
1537 gendocs.sh emacs "GNU Emacs manual"
1540 @command{gendocs.sh} creates a subdirectory @file{manual/} containing
1541 the manual generated in all the standard output formats: Info, HTML,
1542 DVI, and so on, as well as the Texinfo source. You then need to move
1543 all those files, retaining the subdirectories, into the web pages for
1546 You can specify the option @option{-o @var{outdir}} to override the
1547 name @file{manual}. Any previous contents of @var{outdir} will be deleted.
1549 The second argument, with the description, is included as part of the
1550 HTML @code{<title>} of the overall @file{manual/index.html} file. It
1551 should include the name of the package being documented, as shown.
1552 @file{manual/index.html} is created by substitution from the file
1553 @file{gendocs_template}. (Feel free to modify the generic template
1554 for your own purposes.)
1556 If you have several manuals, you'll need to run this script several
1557 times with different arguments, specifying a different output
1558 directory with @option{-o} each time, and moving all the output to
1559 your web page. Then write (by hand) an overall index.html with links
1560 to them all. For example:
1563 gendocs.sh -o texinfo texinfo "GNU Texinfo manual"
1564 gendocs.sh -o info info "GNU Info manual"
1565 gendocs.sh -o info-stnd info-stnd "GNU info-stnd manual"
1568 By default, the script uses @command{makeinfo} for generating
1569 @acronym{HTML} output. If you prefer to use @command{texi2html}, use
1570 the @option{--texi2html} command line option, e.g.:
1573 gendocs --texi2html -o texinfo texinfo "GNU Texinfo manual"
1576 The template files will automatically produce entries for additional
1577 HTML output generated by @command{texi2html} (i.e., split by sections
1580 You can set the environment variables @env{MAKEINFO}, @env{TEXI2DVI},
1581 @env{TEXI2HTML} and @env{DVIPS} to control the programs that get
1582 executed, and @env{GENDOCS_TEMPLATE_DIR} to control where the
1583 @file{gendocs_template} file is found.
1585 Please email bug reports, enhancement requests, or other
1586 correspondence to @email{bug-texinfo@@gnu.org}.
1589 @node CVS Keywords in Web Pages
1590 @section CVS Keywords in Web Pages
1591 @cindex cvs keywords in web pages
1592 @cindex rcs keywords in web pages
1593 @cindex $ keywords in web pages
1594 @cindex web pages, and cvs keywords
1596 Since @code{www.gnu.org} works through CVS, CVS keywords in your
1597 manual, such as @code{@w{$}Log$}, need special treatment (even if you
1598 don't happen to maintain your manual in CVS).
1600 If these keywords end up in the generated output as literal strings,
1601 they will be expanded. The most robust way to handle this is to turn
1602 off keyword expansion for such generated files. For existing files,
1606 cvs admin -ko @var{file1} @var{file2} ...
1613 cvs add -ko @var{file1} @var{file2} ...
1616 @xref{Keyword substitution,,,cvs,Version Management with CVS}.
1618 In Texinfo source, the recommended way to literally specify a
1619 ``dollar'' keyword is:
1625 The @code{@@w} prevents keyword expansion in the Texinfo source
1626 itself. Also, @code{makeinfo} notices the @code{@@w} and generates
1627 output avoiding the literal keyword string.
1630 @node Ethical and Philosophical Consideration
1631 @chapter Ethical and Philosophical Consideration
1635 The GNU project takes a strong stand for software freedom. Many
1636 times, this means you'll need to avoid certain technologies when their
1637 use would conflict with our long-term goals.
1639 Software patents threaten the advancement of free software and freedom
1640 to program. There are so many software patents in the US that any
1641 large program probably implements hundreds of patented techniques,
1642 unknown to the program's developers. It would be futile and
1643 self-defeating to try to find and avoid all these patents. But there
1644 are some patents which we know are likely to be used to threaten free
1645 software, so we make an effort to avoid the patented techniques. If
1646 you are concerned about the danger of a patent and would like advice,
1647 write to @email{maintainers@@gnu.org}, and we will try to help you get
1648 advice from a lawyer.
1650 Sometimes the GNU project takes a strong stand against a particular
1651 patented technology in order to encourage society to reject it.
1653 For example, the MP3 audio format is covered by a software patent in
1654 the USA and some other countries. A patent holder has threatened
1655 lawsuits against the developers of free programs (these are not GNU
1656 programs) to produce and play MP3, and some GNU/Linux distributors are
1657 afraid to include them. Development of the programs continues, but we
1658 campaign for the rejection of MP3 format in favor of Ogg Vorbis format.
1660 A GNU package should not recommend use of any non-free program, nor
1661 should it require a non-free program (such as a non-free compiler or
1662 IDE) to build. Thus, a GNU package cannot be written in a programming
1663 language that does not have a free software implementation. Now that
1664 GNU/Linux systems are widely available, all GNU packages should
1665 provide full functionality on a 100% free GNU/Linux system, and should
1666 not require any non-free software to build or function.
1667 The GNU Coding Standards say a lot more about this issue.
1669 A GNU package should not refer the user to any non-free documentation
1670 for free software. The need for free documentation to come with free
1671 software is now a major focus of the GNU project; to show that we are
1672 serious about the need for free documentation, we must not contradict
1673 our position by recommending use of documentation that isn't free.
1675 Finally, new issues concerning the ethics of software freedom come up
1676 frequently. We ask that GNU maintainers, at least on matters that
1677 pertain specifically to their package, stand with the rest of the GNU
1678 project when such issues come up.
1682 @chapter Terminology Issues
1685 This chapter explains a couple of issues of terminology which are
1686 important for correcting two widespread and important misunderstandings
1690 * Free Software and Open Source::
1694 @node Free Software and Open Source
1695 @section Free Software and Open Source
1696 @cindex free software
1698 @cindex movements, Free Software and Open Source
1700 The terms ``free software'' and ``open source'' are the slogans of two
1701 different movements which differ in their basic philosophy. The Free
1702 Software Movement is idealistic, and raises issues of freedom, ethics,
1703 principle and what makes for a good society. The Open Source Movement,
1704 founded in 1998, studiously avoids such questions. For more explanation,
1705 see @url{http://www.gnu.org/philosophy/free-software-for-freedom.html}.
1707 The GNU Project is aligned with the Free Software Movement. This
1708 doesn't mean that all GNU contributors and maintainers have to agree;
1709 your views on these issues are up to you, and you're entitled to express
1710 them when speaking for yourself.
1712 However, due to the much greater publicity that the Open Source
1713 Movement receives, the GNU Project needs to overcome a widespread
1714 mistaken impression that GNU is @emph{and always was} an activity of
1715 the Open Source Movement. For this reason, please use the term ``free
1716 software'', not ``open source'', in GNU software releases, GNU
1717 documentation, and announcements and articles that you publish in your
1718 role as the maintainer of a GNU package. A reference to the URL given
1719 above, to explain the difference, is a useful thing to include as
1723 @section GNU and Linux
1727 The GNU Project was formed to develop a free Unix-like operating system,
1728 GNU. The existence of this system is our major accomplishment.
1729 However, the widely used version of the GNU system, in which Linux is
1730 used as the kernel, is often called simply ``Linux''. As a result, most
1731 users don't know about the GNU Project's major accomplishment---or more
1732 precisely, they know about it, but don't realize it is the GNU Project's
1733 accomplishment and reason for existence. Even people who believe they
1734 know the real history often believe that the goal of GNU was to develop
1735 ``tools'' or ``utilities.''
1737 To correct this confusion, we have made a years-long effort to
1738 distinguish between Linux, the kernel that Linus Torvalds wrote, and
1739 GNU/Linux, the operating system that is the combination of GNU and
1740 Linux. The resulting increased awareness of what the GNU Project has
1741 already done helps every activity of the GNU Project recruit more
1742 support and contributors.
1744 Please make this distinction consistently in GNU software releases, GNU
1745 documentation, and announcements and articles that you publish in your
1746 role as the maintainer of a GNU package. If you want to explain the
1747 terminology and its reasons, you can refer to the URL
1748 @url{http://www.gnu.org/gnu/linux-and-gnu.html}.
1750 To contrast the GNU system properly with respect to GNU/Linux, you can
1751 call it ``GNU/Hurd'' or ``the GNU/Hurd system.'' However, when that
1752 contrast is not specifically the focus, please call it just ``GNU'' or
1755 When referring to the collection of servers that is the higher level
1756 of the GNU kernel, please call it ``the Hurd'' or ``the GNU Hurd.''
1757 Note that this uses a space, not a slash.
1762 @cindex CVS repository
1767 We would like to recommend using @code{subversions.gnu.org} as the CVS
1768 repository for your package, and using @code{ftp.gnu.org} as the
1769 standard FTP site. It is ok to use other machines if you wish. If you
1770 use a company's machine to hold the repository for your program, or as
1771 its ftp site, please put this statement in a prominent place on the
1772 site, so as to prevent people from getting the wrong idea about the
1773 relationship between the package and the company:
1776 The programs <list of them> hosted here are free software packages
1777 of the GNU Project, not products of <company name>. We call them
1778 "free software" because you are free to copy and redistribute them,
1779 following the rules stated in the license of each package. For more
1780 information, see http://www.gnu.org/philosophy/free-sw.html.
1782 If you are looking for service or support for GNU software, see
1783 http://www.gnu.org/help/gethelp.html for suggestions of where to ask.
1785 If you would like to contribute to the development of one of these
1786 packages, contact the package maintainer or the bug-reporting address
1787 of the package (which should be listed in the package itself), or look
1788 on www.gnu.org for more information on how to contribute.
1792 @node Free Software Directory
1793 @chapter Free Software Directory
1794 @cindex Free Software Directory
1795 @cindex Directory, Free Software
1797 The Free Software Directory aims to be a complete list of free software
1798 packages, within certain criteria. Every GNU package should be listed
1799 there, so please contact @email{bug-directory@@gnu.org} to ask for
1800 information on how to write an entry for your package.
1803 @node Using the Proofreaders List
1804 @chapter Using the Proofreaders List
1805 @cindex proofreading
1807 If you want help finding errors in documentation,
1808 or help improving the quality of writing,
1809 or if you are not a native speaker of English
1810 and want help producing good English documentation,
1811 you can use the GNU proofreaders mailing list:
1812 @email{proofreaders@@gnu.org}.
1814 But be careful when you use the list,
1815 because there are over 200 people on it.
1816 If you simply ask everyone on the list to read your work,
1817 there will probably be tremendous duplication of effort
1818 by the proofreaders,
1819 and you will probably get the same errors reported 100 times.
1820 This must be avoided.
1822 Also, the people on the list do not want to get
1823 a large amount of mail from it.
1824 So do not ever ask people on the list to send mail to the list!
1826 Here are a few methods that seem reasonable to use:
1830 For something small, mail it to the list,
1831 and ask people to pick a random number from 1 to 20,
1832 and read it if the number comes out as 10.
1833 This way, assuming 50% response, some 5 people will read the piece.
1836 For a larger work, divide your work into around 20 equal-sized parts,
1837 tell people where to get it,
1838 and ask each person to pick randomly which part to read.
1840 Be sure to specify the random choice procedure;
1841 otherwise people will probably use a mental procedure
1842 that is not really random,
1843 such as ``pick a part near the middle'',
1844 and you will not get even coverage.
1846 You can either divide up the work physically, into 20 separate files,
1847 or describe a virtual division, such as by sections
1848 (if your work has approximately 20 sections).
1849 If you do the latter, be sure to be precise about it---for example,
1850 do you want the material before the first section heading
1851 to count as a section, or not?
1854 For a job needing special skills, send an explanation of it,
1855 and ask people to send you mail if they volunteer for the job.
1856 When you get enough volunteers, send another message to the list saying
1857 ``I have enough volunteers, no more please.''
1868 eval: (add-hook 'write-file-hooks 'time-stamp)
1869 time-stamp-start: "@set lastupdate "
1870 time-stamp-start: "@set lastupdate "
1872 time-stamp-format: "%:b %:d, %:y"
1873 compile-command: "make just-maintain"