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 23, 2007
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 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::
76 @chapter About This Document
78 This file contains guidelines and advice for someone who is the
79 maintainer of a GNU program on behalf of the GNU Project. Everyone is
80 entitled to change and redistribute GNU software; you need not pay
81 attention to this file to get permission. But if you want to maintain a
82 version for widespread distribution, we suggest you follow these
83 guidelines; if you would like to be a GNU maintainer, then it is
84 essential to follow these guidelines.
86 Please send corrections or suggestions for this document to
87 @email{maintainers@@gnu.org}. If you make a suggestion, please include
88 a suggested new wording for it, to help us consider the suggestion
89 efficiently. We prefer a context diff to the @file{maintain.texi} file,
90 but if you don't have that file, you can make a context diff for some
91 other version of this document, or propose it in any way that makes it
94 This document uses the gender-neutral third-person pronouns ``person'',
95 ``per'', ``pers'' and ``perself'' which were promoted, and perhaps
96 invented, by Marge Piercy in @cite{Woman on the Edge of Time}. They are
97 used just like ``she'', ``her'', ``hers'' and ``herself'', except that
98 they apply equally to males and females. For example, ``Person placed
99 per new program under the GNU GPL, to let the public benefit from per
100 work, and to enable per to feel person has done the right thing.''
102 The directory @file{/gd/gnuorg} is found on the GNU file server,
103 currently @code{fencepost.gnu.org}; if you are the maintainer of a GNU
104 package, you should have an account there. Contact
105 @email{accounts@@gnu.org} if you don't have one. (You can also ask
106 for accounts for people who help you a large amount in working on the
109 This release of the GNU Maintenance Instructions was last updated
113 @chapter Stepping Down
115 With good fortune, you will continue maintaining your package for many
116 decades. But sometimes for various reasons maintainers decide to step
119 If you're the official maintainer of a GNU package and you decide to
120 step down, please inform the GNU Project (@email{maintainers@@gnu.org}).
121 We need to know that the package no longer has a maintainer, so we can
122 look for and appoint a new maintainer.
124 If you have an idea for who should take over, please tell
125 @email{maintainers@@gnu.org} your suggestion. The appointment of a new
126 maintainer needs the GNU Project's confirmation, but your judgment that
127 a person is capable of doing the job will carry a lot of weight.
129 As your final act as maintainer, it would be helpful to set up the
130 package under @code{savannah.gnu.org} (@pxref{Old Versions}). This will
131 make it much easier for the new maintainer to pick up where you left off
132 and will ensure that the CVS tree is not misplaced if it takes us a
133 while to find a new maintainer.
135 @node Recruiting Developers
136 @chapter Recruiting Developers
138 Unless your package is a fairly small, you probably won't do all the
139 work on it yourself. Most maintainers recruit other developers to help.
141 Sometimes people will offer to help. Some of them will be capable,
142 while others will not. It's up to you to determine who provides useful
143 help, and encourage those people to participate more.
145 Some of the people who offer to help will support the GNU Project, while
146 others may be interested for other reasons. Some will support the goals
147 of the Free Software Movement, but some may not. They are all welcome
148 to help with the work---we don't ask people's views or motivations
149 before they contribute to GNU packages.
151 As a consequence, you cannot expect all contributors to support the GNU
152 Project, or to have a concern for its policies and standards. So part
153 of your job as maintainer is to exercise your authority on these points
154 when they arise. No matter how much of the work other people do, you
155 are in charge of what goes in the release. When a crucial point arises,
156 you should calmly state your decision and stick to it.
158 Sometimes a package has several co-maintainers who share the role of
159 maintainer. Unlike developers who help, co-maintainers have actually
160 been appointed jointly as the maintainers of the package, and they carry
161 out the maintainer's functions together. If you would like to propose
162 some of your developers as co-maintainers, please contact
163 @email{maintainers@@gnu.org}.
166 @chapter Legal Matters
167 @cindex legal matters
169 This chapter describes procedures you should follow for legal reasons
170 as you maintain the program, to avoid legal difficulties.
174 * Legally Significant::
175 * Recording Contributors::
176 * Copying from Other Packages::
177 * Copyright Notices::
179 * External Libraries::
182 @node Copyright Papers
183 @section Copyright Papers
184 @cindex copyright papers
186 If you maintain an FSF-copyrighted package
187 certain legal procedures are required when incorporating legally significant
188 changes written by other people. This ensures that the FSF has the
189 legal right to distribute the package, and the standing to defend its
190 GPL-covered status in court if necessary.
192 @strong{Before} incorporating significant changes, make sure that the
193 person who wrote the changes has signed copyright papers and that the
194 Free Software Foundation has received and signed them. We may also need
195 a disclaimer from the person's employer.
197 @cindex data base of GNU copyright assignments
198 To check whether papers have been received, look in
199 @file{/gd/gnuorg/copyright.list}. If you can't look there directly,
200 @email{fsf-records@@gnu.org} can check for you. Our clerk can also
201 check for papers that are waiting to be entered and inform you when
202 expected papers arrive.
204 @cindex @file{/gd/gnuorg} directory
205 @c This paragraph intentionally duplicates information given
206 @c near the beginning of the file--to make sure people don't miss it.
207 The directory @file{/gd/gnuorg} is found on the GNU machines,
208 currently @code{fencepost.gnu.org}; if you are the maintainer of a GNU
209 package, you should have an account on them. Contact
210 @email{accounts@@gnu.org} if you don't have one. (You can also ask
211 for accounts for people who help you a large amount in working on the
214 In order for the contributor to know person should sign papers, you need
215 to ask for the necessary papers. If you don't know per well, and you
216 don't know that person is used to our ways of handling copyright papers,
217 then it might be a good idea to raise the subject with a message like
221 Would you be willing to assign the copyright to the Free Software
222 Foundation, so that we could install it in @var{program}?
229 Would you be willing to sign a copyright disclaimer to put this change
230 in the public domain, so that we can install it in @var{program}?
233 If the contributor wants more information, you can send per
234 @file{/gd/gnuorg/conditions.text}, which explains per options (assign
235 vs.@: disclaim) and their consequences.
237 Once the conversation is under way and the contributor is ready for
238 more details, you should send one of the templates that are found in
239 the directory @file{/gd/gnuorg/Copyright/}; they are also available
240 from the @file{doc/Copyright/} directory of the @code{gnulib} project
241 at @url{http://savannah.gnu.org/projects/gnulib}. This section
242 explains which templates you should use in which circumstances.
243 @strong{Please don't use any of the templates except for those listed
244 here, and please don't change the wording.}
246 Once the conversation is under way, you can send the contributor the
247 precise wording and instructions by email. Before you do this, make
248 sure to get the current version of the template you will use! We change
249 these templates occasionally---don't keep using an old version.
251 For large changes, ask the contributor for an assignment. Send per a
252 copy of the file @file{request-assign.changes}. (Like all the
253 @samp{request-} files, it is in @file{/gd/gnuorg/Copyright} and in
256 For medium to small changes, request a disclaimer by sending per the
257 file @file{request-disclaim.changes}.
259 If the contributor is likely to keep making changes, person might want
260 to sign an assignment for all per future changes to the program. So it
261 is useful to offer per that alternative. If person wants to do it that
262 way, send per the @file{request-assign.future}.
264 When you send a @file{request-} file, you don't need to fill in anything
265 before sending it. Just send the file verbatim to the contributor. The
266 file gives per instructions for how to ask the FSF to mail per the
267 papers to sign. The @file{request-} file also raises the issue of
268 getting a copyright disclaimer from the contributor's employer.
270 When the contributor emails the form to the FSF, the FSF sends per
271 papers to sign. If person signs them right away, the whole process
272 takes about two weeks--mostly waiting for letters to go back and
275 For less common cases, we have template files you should send to the
276 contributor. Be sure to fill in the name of the person and the name
277 of the program in these templates, where it says @samp{NAME OF PERSON}
278 and @samp{NAME OF PROGRAM}, before sending; otherwise person might
279 sign without noticing them, and the papers would be useless. Note
280 that in some templates there is more than one place to put the name of
281 the program or the name of the person; be sure to change all of them.
282 All the templates raise the issue of an employer's disclaimer as well.
284 @cindex legal papers for changes in manuals
285 You do not need to ask for separate papers for a manual that is
286 distributed only in the software package it describes. But if we
287 sometimes distribute the manual separately (for instance, if we publish
288 it as a book), then we need separate legal papers for changes in the
289 manual. For smaller changes, use
290 @file{disclaim.changes.manual}; for larger ones, use
291 @file{assign.changes.manual}. To cover both past and future
292 changes to a manual, you can use @file{assign.future.manual}.
293 For a translation of a manual, use @file{assign.translation.manual}.
295 If a contributor is reluctant to sign an assignment for a large change,
296 and is willing to sign a disclaimer instead, that is acceptable, so you
297 should offer this alternative if it helps you reach agreement. We
298 prefer an assignment for a larger change, so that we can enforce the GNU
299 GPL for the new text, but a disclaimer is enough to let us use the text.
301 If you maintain a collection of programs, occasionally someone will
302 contribute an entire separate program or manual that should be added to
303 the collection. Then you can use the files
304 @file{request-assign.program}, @file{disclaim.program},
305 @file{assign.manual}, and @file{disclaim.manual}. We very much prefer
306 an assignment for a new separate program or manual, unless it is quite
307 small, but a disclaimer is acceptable if the contributor insists on
308 handling the matter that way.
310 If a contributor wants the FSF to publish only a pseudonym, that is
311 ok. The contributor should say this, and state the desired pseudonym,
312 when answering the @file{request-} form. The actual legal papers will
313 use the real name, but the FSF will publish only the pseudonym. When
314 using one of the other forms, fill in the real name but ask the
315 contributor to discuss the use of a pseudonym with
316 @email{assign@@gnu.org} before sending back the signed form.
318 @strong{Although there are other templates besides the ones listed here,
319 they are for special circumstances; please do not use them without
320 getting advice from @email{assign@@gnu.org}.}
322 If you are not sure what to do, then please ask @email{assign@@gnu.org} for
323 advice; if the contributor asks you questions about the meaning and
324 consequences of the legal papers, and you don't know the answers, you
325 can forward them to @email{assign@@gnu.org} and we will answer.
327 @strong{Please do not try changing the wording of a template yourself.
328 If you think a change is needed, please talk with @email{assign@@gnu.org},
329 and we will work with a lawyer to decide what to do.}
331 @node Legally Significant
332 @section Legally Significant Changes
334 If a person contributes more than around 15 lines of code and/or text
335 that is legally significant for copyright purposes, which means we
336 need copyright papers for it as described above.
338 A change of just a few lines (less than 15 or so) is not legally
339 significant for copyright. A regular series of repeated changes, such
340 as renaming a symbol, is not legally significant even if the symbol
341 has to be renamed in many places. Keep in mind, however, that a
342 series of minor changes by the same person can add up to a significant
343 contribution. What counts is the total contribution of the person; it
344 is irrelevant which parts of it were contributed when.
346 Copyright does not cover ideas. If someone contributes ideas but no
347 text, these ideas may be morally significant as contributions, and
348 worth giving credit for, but they are not significant for copyright
349 purposes. Likewise, bug reports do not count for copyright purposes.
351 When giving credit to people whose contributions are not legally
352 significant for copyright purposes, be careful to make that fact
353 clear. The credit should clearly say they did not contribute
354 significant code or text.
356 When people's contributions are not legally significant because they
357 did not write code, do this by stating clearly what their contribution
358 was. For instance, you could write this:
363 * Richard Mlynarik <mly@@adoc.xerox.com> (1997)
364 * Masatake Yamato <masata-y@@is.aist-nara.ac.jp> (1999)
369 @code{Ideas by:} makes it clear that Mlynarik and Yamato here
370 contributed only ideas, not code. Without the @code{Ideas by:} note,
371 several years from now we would find it hard to be sure whether they
372 had contributed code, and we might have to track them down and ask
375 When you record a small patch in a change log file, first search for
376 previous changes by the same person, and see if his past
377 contributions, plus the new one, add up to something legally
378 significant. If so, you should get copyright papers for all his
379 changes before you install the new change.
381 If that is not so, you can install the small patch. Write @samp{(tiny
382 change)} after the patch author's name, like this:
385 2002-11-04 Robert Fenk <Robert.Fenk@@gmx.de> (tiny change)
388 @node Recording Contributors
389 @section Recording Contributors
390 @cindex recording contributors
392 @strong{Keep correct records of which portions were written by whom.}
393 This is very important. These records should say which files
394 parts of files, were written by each person, and which files or
395 portions were revised by each person. This should include
396 installation scripts as well as manuals and documentation
399 These records don't need to be as detailed as a change log. They
400 don't need to distinguish work done at different times, only different
401 people. They don't need describe changes in more detail than which
402 files or parts of a file were changed. And they don't need to say
403 anything about the function or purpose of a file or change--the
404 Register of Copyrights doesn't care what the text does, just who wrote
405 or contributed to which parts.
407 The list should also mention if certain files distributed in the same
408 package are really a separate program.
410 Only the contributions that are legally significant for copyright
411 purposes (@pxref{Legally Significant}) need to be listed. Small
412 contributions, bug reports, ideas, etc., can be omitted.
414 For example, this would describe an early version of GAS:
417 Dean Elsner first version of all files except gdb-lines.c and m68k.c.
418 Jay Fenlason entire files gdb-lines.c and m68k.c, most of app.c,
419 plus extensive changes in messages.c, input-file.c, write.c
420 and revisions elsewhere.
422 Note: GAS is distributed with the files obstack.c and obstack.h, but
423 they are considered a separate package, not part of GAS proper.
426 @cindex @file{AUTHORS} file
427 Please keep these records in a file named @file{AUTHORS} in the source
428 directory for the program itself.
430 You can use the change log as the basis for these records, if you
431 wish. Just make sure to record the correct author for each change
432 (the person who wrote the change, @emph{not} the person who installed
433 it), and add @samp{(tiny change)} for those changes that are too
434 trivial to matter for copyright purposes. Later on you can update the
435 @file{AUTHORS} file from the change log. This can even be done
436 automatically, if you are careful about the formatting of the change
439 @node Copying from Other Packages
440 @section Copying from Other Packages
442 When you copy legally significant code from another free software
443 package with a GPL-compatible license, you should look in the
444 package's records to find out the authors of the part you are copying,
445 and list them as the contributors of the code that you copied. If all
446 you did was copy it, not write it, then for copyright purposes you are
447 @emph{not} one of the contributors of @emph{this} code.
449 Especially when code has been released into the public domain, authors
450 sometimes fail to write a license statement in each file. In this
451 case, please first be sure that all the authors of the code have
452 disclaimed copyright interest. Then, when copying the new files into
453 your project, add a brief note at the beginning of the files recording
454 the authors, the public domain status, and anything else relevant.
456 On the other hand, when merging some public domain code into an
457 existing file covered by the GPL (or LGPL or other free software
458 license), there is no reason to indicate the pieces which are public
459 domain. The notice saying that the whole file is under the GPL (or
460 other license) is legally sufficient.
462 Using code that is released under a GPL-compatible free license,
463 rather than being in the public domain, may require preserving
464 copyright notices or other steps. Of course, you should do what is
467 If you are maintaining an FSF-copyrighted package, please verify we
468 have papers for the code you are copying, @emph{before} copying it.
469 If you are copying from another FSF-copyrighted package, then we
470 presumably have papers for that package's own code, but you must check
471 whether the code you are copying is part of an external library; if
472 that is the case, we don't have papers for it, so you should not copy
473 it. It can't hurt in any case to double-check with the developer of
476 When you are copying code for which we do not already have papers, you
477 need to get papers for it. It may be difficult to get the papers if
478 the code was not written as a contribution to your package, but that
479 doesn't mean it is ok to do without them. If you cannot get papers
480 for the code, you can only use it as an external library
481 (@pxref{External Libraries}).
484 @node Copyright Notices
485 @section Copyright Notices
486 @cindex copyright notices in program files
488 You should maintain a proper copyright notice and a license
489 notice in each nontrivial file in the package. (Any file more than ten
490 lines long is nontrivial for this purpose.) This includes header files
491 and interface definitions for
492 building or running the program, documentation files, and any supporting
493 files. If a file has been explicitly placed in the public domain, then
494 instead of a copyright notice, it should have a notice saying explicitly
495 that it is in the public domain.
497 Even image files and sound files should contain copyright notices and
498 license notices, if they can. Some formats do not have room for textual
499 annotations; for these files, state the copyright and copying
500 permissions in a README file in the same directory.
502 Change log files should have a copyright notice and license notice at
503 the end, since new material is added at the beginning but the end
506 When a file is automatically generated from some other file in the
507 distribution, it is useful for the automatic procedure to copy the
508 copyright notice and permission notice of the file it is generated
509 from, if possible. Alternatively, put a notice at the beginning saying
510 which file it is generated from.
512 A copyright notice looks like this:
515 Copyright (C) @var{year1}, @var{year2}, @var{year3} @var{copyright-holder}
518 The @var{copyright-holder} may be the Free Software Foundation, Inc., or
519 someone else; you should know who is the copyright holder for your
522 Replace the @samp{(C)} with a C-in-a-circle symbol if it is available.
523 For example, use @samp{@@copyright@{@}} in a Texinfo file. However,
524 stick with parenthesized @samp{C} unless you know that C-in-a-circle
525 will work. For example, a program's standard @option{--version}
526 message should use parenthesized @samp{C} by default, though message
527 translations may use C-in-a-circle in locales where that symbol is
530 To update the list of year numbers, add each year in which you have
531 made nontrivial changes to the package. (Here we assume you're using
532 a publicly accessible revision control server, so that every revision
533 installed is also immediately and automatically published.) When you
534 add the new year, it is not required to keep track which files have
535 seen significant changes in the new year and which have not. It is
536 recommended and simpler to add the new year to all files in the
537 package, and be done with it for the rest of the year.
539 For files which are regularly copied from another project (such as
540 @samp{gnulib}), the copyright notice should left as it is in the
543 Don't delete old year numbers, though; they can indicate when older
544 versions might theoretically go into the public domain. If you copy a
545 file into the package from some other program, keep the copyright
546 years that come with the file.
548 Do not abbreviate the year list using a range; for instance, do not
549 write @samp{1996--1998}; instead, write @samp{1996, 1997, 1998}.
551 The copyright statement may be split across multiple lines, both in
552 source files and in any generated output. This often happens for
553 files with a long history, having many different years of
556 For an FSF-copyrighted package, if you have followed the procedures to
557 obtain legal papers, each file should have just one copyright holder:
558 the Free Software Foundation, Inc. You should edit the file's
559 copyright notice to list that name and only that name.
561 But if contributors are not all assigning their copyrights to a single
562 copyright holder, it can easily happen that one file has several
563 copyright holders. Each contributor of nontrivial text is a copyright
566 In that case, you should always include a copyright notice in the name
567 of main copyright holder of the file. You can also include copyright
568 notices for other copyright holders as well, and this is a good idea
569 for those who have contributed a large amount and for those who
570 specifically ask for notices in their names. (Sometimes the license
571 on code that you copy in may require preserving certain copyright
572 notices.) But you don't have to include a notice for everyone who
573 contributed to the file (which would be rather inconvenient).
575 Sometimes a program has an overall copyright notice that refers to the
576 whole program. It might be in the @file{README} file, or it might be
577 displayed when the program starts up. This copyright notice should
578 mention the year of completion of the most recent major version; it
579 can mention years of completion of previous major versions, but that
583 @node License Notices
584 @section License Notices
585 @cindex license notices in program files
587 Every nontrivial file needs a license notice as well as the copyright
588 notice. (Without a license notice giving permission to copy and change
590 would make the file non-free.)
592 The package itself should contain a full copy of GPL (conventionally in
593 a file named @file{COPYING}) and the GNU Free Documentation License
594 (included within your documentation). If the package contains any files
595 distributed under the Lesser GPL, it should contain a full copy of that
596 as well (conventionally in a file named @file{COPYING.LIB}).
598 You can get the official versions of these files from three places.
599 You can use whichever is the most convenient for you.
603 @uref{http://www.gnu.org/licenses/}.
606 The directory @file{/gd/gnuorg} on the host
607 @code{fencepost.gnu.org}. (You can ask @email{accounts@@gnu.org}
608 for an account there if you don't have one).
611 The @code{gnulib} project on @code{savannah.gnu.org}, which you
612 can access via anonymous CVS. See
613 @uref{http://savannah.gnu.org/projects/gnulib}.
617 The official Texinfo sources for the licenses are also available in
618 those same places, so you can include them in your documentation. A
619 GFDL-covered manual must include the GFDL in this way. @xref{GNU Sample
620 Texts,,,texinfo,Texinfo}, for a full example in a Texinfo manual.
622 Typically the license notice for program files (including build scripts,
623 configure files and makefiles) should cite the GPL, like this:
626 This file is part of GNU @var{program}
628 GNU @var{program} is free software; you can redistribute it and/or modify
629 it under the terms of the GNU General Public License as published by
630 the Free Software Foundation; either version 2, or (at your option)
633 GNU @var{program} is distributed in the hope that it will be useful,
634 but WITHOUT ANY WARRANTY; without even the implied warranty of
635 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
636 GNU General Public License for more details.
638 You should have received a copy of the GNU General Public License
639 along with @var{program}; see the file COPYING. If not, write to
640 the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
641 Boston, MA 02110-1301 USA.
644 But in a small program which is just a few files, you can use
648 This program is free software; you can redistribute it and/or modify
649 it under the terms of the GNU General Public License as published by
650 the Free Software Foundation; either version 2 of the License, or
651 (at your option) any later version.
653 This program is distributed in the hope that it will be useful,
654 but WITHOUT ANY WARRANTY; without even the implied warranty of
655 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
656 GNU General Public License for more details.
658 You should have received a copy of the GNU General Public License along
659 with this program; if not, write to the Free Software Foundation, Inc.,
660 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
663 Documentation files should have license notices also. Manuals should
664 use the GNU Free Documentation License. Here is an example of the
665 license notice to use after the copyright notice. Please adjust the
666 list of invariant sections as appropriate for your manual. (If there
667 are none, then say ``with no invariant sections''.) @xref{GNU Sample
668 Texts,,,texinfo,Texinfo}, for a full example in a Texinfo manual.
671 Permission is granted to copy, distribute and/or modify this document
672 under the terms of the GNU Free Documentation License, Version 1.2 or
673 any later version published by the Free Software Foundation; with the
674 Invariant Sections being "GNU General Public License", with the
675 Front-Cover Texts being ``A GNU Manual,'' and with the Back-Cover Texts
676 as in (a) below. A copy of the license is included in the section
677 entitled "GNU Free Documentation License".
679 (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
680 this GNU Manual. Buying copies from GNU Press supports the FSF in
681 developing GNU and promoting software freedom.''
685 If the FSF does not publish this manual on paper, then omit the last
686 sentence in (a) that talks about copies from GNU Press. If the FSF is
687 not the copyright holder, then replace @samp{FSF} with the appropriate
690 See @url{http://www.gnu.org/licenses/fdl-howto.html} for more advice
691 about how to use the GNU FDL.
693 If the manual is over 400 pages, or if the FSF thinks it might be a good
694 choice for publishing on paper, then please include our standard
695 invariant section which explains the importance of free documentation.
696 Write to @email{assign@@gnu.org} to get a copy of this section.
698 Note that when you distribute several manuals together in one software
699 package, their on-line forms can share a single copy of the GFDL (see
700 section 6). However, the printed (@samp{.dvi}) forms should each
701 contain a copy of the GFDL, unless they are set up to be printed
702 and published only together. Therefore, it is usually simplest to
703 include the GFDL in each manual.
705 Small supporting files, short manuals (under 300 lines long) and rough
706 documentation (README files, INSTALL files, etc) can use a simple
707 all-permissive license like this one:
710 Copying and distribution of this file, with or without modification,
711 are permitted in any medium without royalty provided the copyright
712 notice and this notice are preserved.
715 If your package distributes Autoconf macros that are intended to be
716 used (hence distributed) by third-party packages under possibly
717 incompatible licenses, you may also use the above all-permissive
718 license for these macros.
720 If you would like help with license issues or with using the GFDL,
721 please contact @email{licensing@@gnu.org}.
723 @node External Libraries
724 @section External Libraries
726 When maintaining an FSF-copyrighted GNU package, you may occasionally
727 want to use a general-purpose free software module which offers a
728 useful functionality, as a ``library'' facility (though the module is
729 not always packaged technically as a library).
731 In a case like this, it would be unreasonable to ask the author of that
732 module to assign the copyright to the FSF. After all, person did not
733 write it specifically as a contribution to your package, so it would be
734 impertinent to ask per, out of the blue, ``Please give the FSF your
737 So the thing to do in this case is to make your program use the module,
738 but not consider it a part of your program. There are two reasonable
739 methods of doing this:
743 Assume the module is already installed on the system, and use it when
744 linking your program. This is only reasonable if the module really has
745 the form of a library.
748 Include the module in your package, putting the source in a separate
749 subdirectory whose @file{README} file says, ``This is not part of the
750 GNU FOO program, but is used with GNU FOO.'' Then set up your makefiles
751 to build this module and link it into the executable.
753 For this method, it is not necessary to treat the module as a library
754 and make a @samp{.a} file from it. You can link with the @samp{.o}
755 files directly in the usual manner.
758 Both of these methods create an irregularity, and our lawyers have told
759 us to minimize the amount of such irregularity. So consider using these
760 methods only for general-purpose modules that were written for other
761 programs and released separately for general use. For anything that was
762 written as a contribution to your package, please get papers signed.
765 @chapter Cleaning Up Changes
766 @cindex contributions, accepting
767 @cindex quality of changes suggested by others
769 Don't feel obligated to include every change that someone asks you to
770 include. You must judge which changes are improvements---partly based
771 on what you think the users will like, and partly based on your own
772 judgment of what is better. If you think a change is not good, you
775 If someone sends you changes which are useful, but written in an ugly
776 way or hard to understand and maintain in the future, don't hesitate to
777 ask per to clean up their changes before you merge them. Since the
778 amount of work we can do is limited, the more we convince others to help
779 us work efficiently, the faster GNU will advance.
781 If the contributor will not or can not make the changes clean enough,
782 then it is legitimate to say ``I can't install this in its present form;
783 I can only do so if you clean it up.'' Invite per to distribute per
784 changes another way, or to find other people to make them clean enough
785 for you to install and maintain.
787 The only reason to do these cleanups yourself is if (1) it is easy, less
788 work than telling the author what to clean up, or (2) the change is an
789 important one, important enough to be worth the work of cleaning it up.
791 The GNU Coding Standards are a good thing to send people when you ask
792 them to clean up changes (@pxref{Top, , Contents, standards, GNU Coding
793 Standards}). The Emacs Lisp manual contains an appendix that gives
794 coding standards for Emacs Lisp programs; it is good to urge authors to
795 read it (@pxref{Tips, , Tips and Standards, elisp, The GNU Emacs Lisp
799 @chapter Platforms to Support
801 Most GNU packages run on a wide range of platforms. These platforms are
802 not equally important.
804 The most important platforms for a GNU package to support are GNU and
805 GNU/Linux. Developing the GNU operating system is the whole point of
806 the GNU Project; a GNU package exists to make the whole GNU system more
807 powerful. So please keep that goal in mind and let it shape your work.
808 For instance, every new feature you add should work on GNU, and
809 GNU/Linux if possible too. If a new feature only runs on GNU and
810 GNU/Linux, it could still be acceptable. However, a feature that runs
811 only on other systems and not on GNU or GNU/Linux makes no sense in a
814 You will naturally want to keep the program running on all the platforms
815 it supports. But you personally will not have access to most of these
816 platforms--so how should you do it?
818 Don't worry about trying to get access to all of these platforms. Even
819 if you did have access to all the platforms, it would be inefficient for
820 you to test the program on each platform yourself. Instead, you should
821 test the program on a few platforms, including GNU or GNU/Linux, and let
822 the users test it on the other platforms. You can do this through a
823 pretest phase before the real release; when there is no reason to expect
824 problems, in a package that is mostly portable, you can just make a
825 release and let the users tell you if anything unportable was
828 It is important to test the program personally on GNU or GNU/Linux,
829 because these are the most important platforms for a GNU package. If
830 you don't have access to one of these platforms, please ask
831 @email{maintainers@@gnu.org} to help you out.
833 Supporting other platforms is optional---we do it when that seems like
834 a good idea, but we don't consider it obligatory. If the users don't
835 take care of a certain platform, you may have to desupport it unless
836 and until users come forward to help. Conversely, if a user offers
837 changes to support an additional platform, you will probably want to
838 install them, but you don't have to. If you feel the changes are
839 complex and ugly, if you think that they will increase the burden of
840 future maintenance, you can and should reject them. This includes
841 both free or mainly-free platforms such as OpenBSD, FreeBSD, and
842 NetBSD, and non-free platforms such as Windows.
846 @chapter Dealing With Mail
849 @cindex email, for receiving bug reports
850 @cindex mailing list for bug reports
851 Once a program is in use, you will get bug reports for it. Most GNU
852 programs have their own special lists for sending bug reports. The
853 advertised bug-reporting email address should always be
854 @samp{bug-@var{program}@@gnu.org}, to help show users that the program
855 is a GNU package, but it is ok to set up that list to forward to another
856 site for further forwarding. The package distribution should state the
857 name of the bug-reporting list in a prominent place, and ask users to
858 help us by reporting bugs there.
860 We also have a catch-all list, @email{bug-gnu-utils@@gnu.org}, which is
861 used for all GNU programs that don't have their own specific lists. But
862 nowadays we want to give each program its own bug-reporting list and
863 move away from using @email{bug-gnu-utils}.
865 If you are the maintainer of a GNU package, you should have an account
866 on the GNU servers; contact @email{accounts@@gnu.org} if you don't have
867 one. (You can also ask for accounts for people who help you a large
868 amount in working on the package.) With this account, you can edit
869 @file{/com/mailer/aliases} to create a new unmanaged list or add
870 yourself to an existing unmanaged list. A comment near the beginning of
871 that file explains how to create a Mailman-managed mailing list.
873 But if you don't want to learn how to do those things, you can
874 alternatively ask @email{alias-file@@gnu.org} to add you to the
875 bug-reporting list for your program. To set up a new list, contact
876 @email{new-mailing-list@@gnu.org}. You can subscribe to a list managed
877 by Mailman by sending mail to the corresponding @samp{-request} address.
879 You should moderate postings from non-subscribed addresses on your
880 mailing lists, to prevent propagation of unwanted messages (``spam'')
881 to subscribers and to the list archives. For lists controlled by
882 Mailman, you can do this by setting @code{Privacy Options - Sender
883 Filter - generic_nonmember_action} to @code{Hold}, and then
884 periodically (daily is best) reviewing the held messages, accepting
885 the real ones and discarding the junk.
887 @cindex responding to bug reports
888 When you receive bug reports, keep in mind that bug reports are crucial
889 for your work. If you don't know about problems, you cannot fix them.
890 So always thank each person who sends a bug report.
892 You don't have an obligation to give more response than that, though.
893 The main purpose of bug reports is to help you contribute to the
894 community by improving the next version of the program. Many of the
895 people who report bugs don't realize this---they think that the point is
896 for you to help them individually. Some will ask you to focus on that
897 @emph{instead of} on making the program better. If you comply with
898 their wishes, you will have been distracted from the job of maintaining
901 For example, people sometimes report a bug in a vague (and therefore
902 useless) way, and when you ask for more information, they say, ``I just
903 wanted to see if you already knew the solution'' (in which case the bug
904 report would do nothing to help improve the program). When this
905 happens, you should explain to them the real purpose of bug reports. (A
906 canned explanation will make this more efficient.)
908 When people ask you to put your time into helping them use the program,
909 it may seem ``helpful'' to do what they ask. But it is much @emph{less}
910 helpful than improving the program, which is the maintainer's real job.
912 By all means help individual users when you feel like it, if you feel
913 you have the time available. But be careful to limit the amount of time
914 you spend doing this---don't let it eat away the time you need to
915 maintain the program! Know how to say no; when you are pressed for
916 time, just ``thanks for the bug report---I will fix it'' is enough
919 Some GNU packages, such as Emacs and GCC, come with advice about how to
920 make bug reports useful. If you want to copy and adapt that, it could
921 be a very useful thing to do.
924 @chapter Recording Old Versions
925 @cindex version control
927 It is very important to keep backup files of all source files of GNU.
928 You can do this using RCS, CVS or PRCS if you like. The easiest way to
929 use RCS or CVS is via the Version Control library in Emacs;
930 @ref{VC Concepts,, Concepts of Version Control, emacs, The GNU Emacs
933 The history of previous revisions and log entries is very important for
934 future maintainers of the package, so even if you do not make it
935 publicly accessible, be careful not to put anything in the repository or
936 change log that you would not want to hand over to another maintainer
939 The GNU Project provides a CVS server that GNU software packages can
940 use: @code{subversions.gnu.org}. (The name refers to the multiple
941 versions and their subversions that are stored in a CVS repository.)
942 You don't have to use this repository, but if you plan to allow public
943 read-only access to your development sources, it is convenient for
944 people to be able to find various GNU packages in a central place. The
945 CVS Server is managed by @email{cvs-hackers@@gnu.org}.
947 The GNU project also provides additional developer resources on
948 @code{subversions.gnu.org} through its @code{savannah.gnu.org}
949 interface. All GNU maintainers are encouraged to take advantage of
950 these facilities, as @code{savannah} can serve to foster a sense of
951 community among all GNU developers and help in keeping up with project
955 @chapter Distributions
957 It is important to follow the GNU conventions when making GNU software
961 * Distribution tar Files::
962 * Distribution Patches::
963 * Distribution on ftp.gnu.org::
965 * Automated FTP Uploads::
969 @node Distribution tar Files
970 @section Distribution tar Files
971 @cindex distribution, tar files
973 The tar file for version @var{m}.@var{n} of program @code{foo} should be
974 named @file{foo-@var{m}.@var{n}.tar}. It should unpack into a
975 subdirectory named @file{foo-@var{m}.@var{n}}. Tar files should not
976 unpack into files in the current directory, because this is inconvenient
977 if the user happens to unpack into a directory with other files in it.
979 Here is how the @file{Makefile} for Bison creates the tar file.
980 This method is good for other programs.
984 echo bison-`sed -e '/version_string/!d' \
985 -e 's/[^0-9.]*\([0-9.]*\).*/\1/' -e q version.c` > .fname
988 dst=`cat .fname`; for f in $(DISTFILES); do \
989 ln $(srcdir)/$$f $$dst/$$f || @{ echo copying $$f; \
990 cp -p $(srcdir)/$$f $$dst/$$f ; @} \
992 tar --gzip -chf `cat .fname`.tar.gz `cat .fname`
993 -rm -rf `cat .fname` .fname
996 Source files that are symbolic links to other file systems cannot be
997 installed in the temporary directory using @code{ln}, so use @code{cp}
1001 Using Automake is a good way to take care of writing the @code{dist}
1004 @node Distribution Patches
1005 @section Distribution Patches
1006 @cindex patches, against previous releases
1008 If the program is large, it is useful to make a set of diffs for each
1009 release, against the previous important release.
1011 At the front of the set of diffs, put a short explanation of which
1012 version this is for and which previous version it is relative to.
1013 Also explain what else people need to do to update the sources
1014 properly (for example, delete or rename certain files before
1015 installing the diffs).
1017 The purpose of having diffs is that they are small. To keep them
1018 small, exclude files that the user can easily update. For example,
1019 exclude info files, DVI files, tags tables, output files of Bison or
1020 Flex. In Emacs diffs, we exclude compiled Lisp files, leaving it up
1021 to the installer to recompile the patched sources.
1023 When you make the diffs, each version should be in a directory suitably
1024 named---for example, @file{gcc-2.3.2} and @file{gcc-2.3.3}. This way,
1025 it will be very clear from the diffs themselves which version is which.
1029 @cindex time stamp in diffs
1030 If you use GNU @code{diff} to make the patch, use the options
1031 @samp{-rc2P}. That will put any new files into the output as ``entirely
1032 different.'' Also, the patch's context diff headers should have dates
1033 and times in Universal Time using traditional Unix format, so that patch
1034 recipients can use GNU @code{patch}'s @samp{-Z} option. For example,
1035 you could use the following Bourne shell command to create the patch:
1038 LC_ALL=C TZ=UTC0 diff -rc2P gcc-2.3.2 gcc-2.3.3 | \
1039 gzip -9 >gcc-2.3.2-2.3.3.patch.gz
1042 If the distribution has subdirectories in it, then the diffs probably
1043 include some files in the subdirectories. To help users install such
1044 patches reliably, give them precise directions for how to run patch.
1045 For example, say this:
1048 To apply these patches, cd to the main directory of the program
1049 and then use `patch -p1'. `-p1' avoids guesswork in choosing
1050 which subdirectory to find each file in.
1053 It's wise to test your patch by applying it to a copy of the old
1054 version, and checking that the result exactly matches the new version.
1056 @node Distribution on ftp.gnu.org
1057 @section Distribution on @code{ftp.gnu.org}
1058 @cindex GNU ftp site
1059 @cindex @code{ftp.gnu.org}, the GNU ftp site
1061 GNU packages are distributed through directory @file{/gnu} on
1062 @code{ftp.gnu.org}. Each package should have a subdirectory
1063 named after the package, and all the distribution files for the package
1064 should go in that subdirectory.
1066 @c If you have an interest in seeing the monthly download logs from the FTP
1067 @c site at @code{ftp.gnu.org} for your program, that is something that
1068 @c @email{ftp-upload@@gnu.org} can set up for you. Please contact them if
1069 @c you are interested.
1071 @xref{Automated FTP Uploads}, for procedural details of putting new
1072 versions on @code{ftp.gnu.org}.
1075 @section Test Releases
1076 @cindex test releases
1077 @cindex beta releases
1078 @cindex pretest releases
1080 @cindex @code{alpha.gnu.org}, ftp site for test releases
1081 When you release a greatly changed new major version of a program, you
1082 might want to do so as a pretest. This means that you make a tar file,
1083 but send it only to a group of volunteers that you have recruited. (Use
1084 a suitable GNU mailing list/newsgroup to recruit them.)
1086 We normally use the FTP server @code{alpha.gnu.org} for pretests and
1087 prerelease versions. @xref{Automated FTP Uploads}, for procedural details
1088 of putting new versions on @code{alpha.gnu.org}.
1090 Once a program gets to be widely used and people expect it to work
1091 solidly, it is a good idea to do pretest releases before each ``real''
1094 There are two ways of handling version numbers for pretest versions.
1095 One method is to treat them as versions preceding the release you are going
1098 In this method, if you are about to release version 4.6 but you want
1099 to do a pretest first, call it 4.5.90. If you need a second pretest,
1100 call it 4.5.91, and so on. If you are really unlucky and ten pretests
1101 are not enough, after 4.5.99 you could advance to 4.5.990 and so on.
1102 (You could also use 4.5.100, but 990 has the advantage of sorting in
1105 The other method is to attach a date to the release number that is
1106 coming. For a pretest for version 4.6, made on Dec 10, 2002, this
1107 would be 4.6.20021210. A second pretest made the same day could be
1110 For development snapshots that are not formal pretests, using just
1111 the date without the version numbers is ok too.
1113 One thing that you should never do is to release a pretest with the same
1114 version number as the planned real release. Many people will look only
1115 at the version number (in the tar file name, in the directory name that
1116 it unpacks into, or wherever they can find it) to determine whether a
1117 tar file is the latest version. People might look at the test release
1118 in this way and mistake it for the real release. Therefore, always
1119 change the number when you release changed code.
1122 @node Automated FTP Uploads
1123 @section Automated FTP Uploads
1125 @cindex ftp uploads, automated
1126 In order to upload new releases to @code{ftp.gnu.org} or
1127 @code{alpha.gnu.org}, you first need to register the necessary
1128 information. Then, you can perform uploads yourself, with no
1129 intervention needed by the system administrators.
1132 * Automated Upload Registration::
1133 * Automated Upload Procedure::
1134 * FTP Upload Directive File - v1.1::
1135 * FTP Upload Directive File - v1.0::
1139 @node Automated Upload Registration
1140 @subsection Automated Upload Registration
1142 @cindex registration
1143 @cindex uploads, registration for
1145 To register your information to perform automated uploads, send a
1146 message, preferably GPG-signed, to @email{ftp-upload@@gnu.org} with
1151 Name of package(s) that you are the maintainer for, and your
1152 preferred email address.
1155 An ASCII armored copy of your GnuPG key, as an attachment.
1156 (@samp{gpg --export -a YOUR_KEY_ID >mykey.asc} should give you this.)
1159 A list of names and preferred email addresses of other individuals you
1160 authorize to make releases for which packages, if any (in the case that you
1161 don't make all releases yourself).
1164 ASCII armored copies of GnuPG keys for any individuals listed in (3).
1167 The administrators will acknowledge your message when they have added
1168 the proper GPG keys as authorized to upload files for the
1169 corresponding packages.
1172 @node Automated Upload Procedure
1173 @subsection Automated Upload Procedure
1177 Once you have registered your information as described in the
1178 previous section, you will be able to do unattended ftp uploads using
1179 the following procedure.
1181 For each upload destined for @code{ftp.gnu.org} or
1182 @code{alpha.gnu.org}, three files (a @dfn{triplet}) need to be
1183 uploaded via ftp to the host @code{ftp-upload.gnu.org}.
1187 The file to be distributed (for example, @file{foo.tar.gz}).
1190 Detached GPG binary signature for (1), made using @samp{gpg -b}
1191 (for example, @file{foo.tar.gz.sig}).
1194 A clearsigned @dfn{directive file}, made using @samp{gpg --clearsign}
1195 (for example, @file{foo.tar.gz.directive.asc}).
1198 The names of the files are important. The signature file must have the
1199 same name as the file to be distributed, with an additional
1200 @file{.sig} extension. The directive file must have the same name as
1201 the file to be distributed, with an additional @file{.directive.asc}
1202 extension. If you do not follow this naming convention, the upload
1203 @emph{will not be processed}.
1205 Since v1.1 of the upload script, it is also possible to upload a
1206 @dfn{directive file} on its own to perform certain operations on
1207 uploaded files. @xref{FTP Upload Directive File - v1.1}, for more
1210 Upload the file(s) via anonymous ftp to @code{ftp-upload.gnu.org}. If
1211 the upload is destined for @code{ftp.gnu.org}, place the file(s) in
1212 the @file{/incoming/ftp} directory. If the upload is destined for
1213 @code{alpha.gnu.org}, place the file(s) in the @file{/incoming/alpha}
1216 Uploads are processed every five minutes. Uploads that are in progress while
1217 the upload processing script is running are handled properly, so do not worry
1218 about the timing of your upload.
1220 Your designated upload email addresses (@pxref{Automated Upload Registration})
1221 are sent a message if there are any problems processing an upload for your
1222 package. You also receive a message when your upload has been successfully
1225 If you have difficulties processing an upload, email
1226 @email{ftp-upload@@gnu.org}.
1229 @node FTP Upload Directive File - v1.1
1230 @subsection FTP Upload Directive File - v1.1
1232 The directive file name must end in @file{directive.asc}.
1234 When part of a triplet, the directive file must always contain the
1235 directives @code{version}, @code{directory} and @code{filename}, as
1236 described. In addition, a 'comment' directive is allowed.
1238 The @code{version} directive must always have the value @samp{1.1}.
1240 The @code{directory} directive specifies the final destination
1241 directory where the uploaded file and its @file{.sig} companion are to
1244 The @code{filename} directive must contain the name of the file to be
1245 distributed (item@tie{}(1) above).
1247 For example, as part of an uploaded triplet, a
1248 @file{foo.tar.gz.directive.asc} file might contain these lines (before
1249 being gpg clearsigned):
1254 filename: foo.tar.gz
1255 comment: hello world!
1258 This directory line indicates that @file{foo.tar.gz} and
1259 @file{foo.tar.gz.sig} are part of package @code{bar}. If you uploaded
1260 this triplet to @file{/incoming/ftp} and the system positively
1261 authenticates the signatures, the files @file{foo.tar.gz} and
1262 @file{foo.tar.gz.sig} will be placed in the directory
1263 @file{gnu/bar/v1} of the @code{ftp.gnu.org} site.
1265 The directive file can be used to create currently non-existent
1266 directory trees, as long as they are under the package directory for
1267 your package (in the example above, that is @code{bar}).
1269 If you upload a file that already exists in the FTP directory, the
1270 original will simply be archived and replaced with the new upload.
1272 @subheading Standalone directives
1274 When uploaded by itself, the directive file must contain one or more
1275 of the directives @code{symlink}, @code{rmsymlink} or @code{archive},
1276 in addition to the obligatory @code{directory} and @code{version}
1277 directives. A @code{filename} directive is not allowed, and a
1278 @code{comment} directive is optional.
1280 If you use more than one directive, the directives are executed in the
1281 sequence they are specified in.
1283 Here are a few examples. The first removes a symlink:
1288 rmsymlink: foo-latest.tgz
1289 comment: remove a symlink
1293 Archive an old file, taking it offline:
1298 archive: foo-1.1.tar.gz
1299 comment: archive an old file - it will not be available through FTP anymore
1303 Create a new symlink:
1308 symlink: foo-1.2.tar.gz foo-latest.tgz
1309 comment: create a new symlink
1313 Do everything at once:
1318 rmsymlink: foo-latest.tgz
1319 symlink: foo-1.2.tar.gz foo-latest.tgz
1320 archive: foo-1.1.tar.gz
1321 comment: now do everything at once
1325 @node FTP Upload Directive File - v1.0
1326 @subsection FTP Upload Directive File - v1.0
1328 @dfn{As of June 2006, the upload script is running in compatibility
1329 mode, allowing uploads with either version@tie{}1.1 or
1330 version@tie{}1.0 of the directive file syntax. Support for v1.0
1331 uploads will be phased out by the end of 2006, so please upgrade
1334 The directive file should contain one line, excluding the clearsigned
1335 data GPG that inserts, which specifies the final destination directory
1336 where items (1) and (2) are to be placed.
1338 For example, the @file{foo.tar.gz.directive.asc} file might contain the
1345 This directory line indicates that @file{foo.tar.gz} and
1346 @file{foo.tar.gz.sig} are part of package @code{bar}. If you were to
1347 upload the triplet to @file{/incoming/ftp}, and the system can
1348 positively authenticate the signatures, then the files
1349 @file{foo.tar.gz} and @file{foo.tar.gz.sig} will be placed in the
1350 directory @file{gnu/bar/v1} of the @code{ftp.gnu.org} site.
1352 The directive file can be used to create currently non-existent
1353 directory trees, as long as they are under the package directory for
1354 your package (in the example above, that is @code{bar}).
1358 @section Announcing Releases
1360 When you have a new release, please make an announcement. You can
1361 maintain your own mailing list for announcements if you like, or you can
1362 use the moderated general GNU announcements list,
1363 @email{info-gnu@@gnu.org}.
1365 If you use your own list, you can decide as you see fit what events are
1366 worth announcing. If you use @email{info-gnu@@gnu.org}, please do not
1367 announce pretest releases, only real releases. But real releases do
1368 include releases made just to fix bugs.
1374 Please write pages about your package for installation on
1375 @code{www.gnu.org}. The pages should follow our usual standards for web
1376 pages (see @url{http://www.gnu.org/server}); we chose them in order to
1377 support a wide variety of browsers, to focus on information rather than
1378 flashy eye candy, and to keep the site simple and uniform.
1380 The simplest way to maintain the web pages for your project is to
1381 register the project on @code{savannah.gnu.org}. Then you can edit
1382 the pages using CVS. You can keep the source files there too, but if
1383 you want to use @code{savannah.gnu.org} only for the web pages, simply
1384 register a ``web-only'' project.
1386 If you don't want to use that method, please talk with
1387 @email{webmasters@@gnu.org} about other possible methods. For
1388 instance, you can mail them pages to install, if necessary. But that
1389 is more work for them, so please use CVS if you can.
1391 Some GNU packages have just simple web pages, but the more information
1392 you provide, the better. So please write as much as you usefully can,
1393 and put all of it on @code{www.gnu.org}. However, pages that access
1394 databases (including mail logs and bug tracking) are an exception; set
1395 them up on whatever site is convenient for you, and make the pages on
1396 @code{www.gnu.org} link to that site.
1398 Historically, web pages for GNU packages did not include GIF images,
1399 because of patent problems (@pxref{Ethical and Philosophical
1400 Consideration}). Although the GIF patents expired in 2006, using GIF
1401 images is still not recommended, as the PNG and JPEG formats are
1402 generally superior. See @url{http://www.gnu.org/philosophy/gif.html}.
1404 The web pages for the package should include its manuals, in HTML,
1405 DVI, Info, PostScript, PDF, plain ASCII, and Texinfo format (source).
1406 (All of these can be generated automatically from the Texinfo source
1407 using Makeinfo and other programs.) When there is only one manual,
1408 put it in a subdirectory called @file{manual}; the file
1409 @file{manual/index.html} should have a link to the manual in each of
1412 If the package has more than one manual, put each one in a
1413 subdirectory of @file{manual}, set up @file{index.html} in each
1414 subdirectory to link to that manual in all its forms, and make
1415 @file{manual/index.html} link to each manual through its subdirectory.
1417 See the section below for details on a script to make the job of
1418 creating all these different formats and index pages easier.
1420 We would like to include links to all these manuals in the page
1421 @url{http://www.gnu.org/manual}. Just send mail to
1422 @code{webmasters@@gnu.org} telling them the name of your package and
1423 asking them to edit @url{http://www.gnu.org/manual}, and they will do
1424 so based on the contents of your @file{manual} directory.
1427 * Invoking gendocs.sh::
1428 * CVS Keywords in Web Pages::
1431 @node Invoking gendocs.sh
1432 @section Invoking @command{gendocs.sh}
1434 @cindex generating documentation output
1436 The script @command{gendocs.sh} eases the task of generating the
1437 Texinfo documentation output for your web pages
1438 section above. It has a companion template file, used as the basis
1439 for the HTML index pages. Both are available from the Texinfo CVS
1442 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh}
1443 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template}
1446 Invoke the script like this, in the directory containing the Texinfo
1449 gendocs.sh @var{yourmanual} "GNU @var{yourmanual} manual"
1452 @noindent where @var{yourmanual} is the short name for your package.
1453 The script processes the file @file{@var{yourmanual}.texinfo} (or
1454 @file{.texi} or @file{.txi}). For example:
1458 # download gendocs.sh and gendocs_template
1459 gendocs.sh emacs "GNU Emacs manual"
1462 @command{gendocs.sh} creates a subdirectory @file{manual/} containing
1463 the manual generated in all the standard output formats: Info, HTML,
1464 DVI, and so on, as well as the Texinfo source. You then need to move
1465 all those files, retaining the subdirectories, into the web pages for
1468 You can specify the option @option{-o @var{outdir}} to override the
1469 name @file{manual}. Any previous contents of @var{outdir} will be deleted.
1471 The second argument, with the description, is included as part of the
1472 HTML @code{<title>} of the overall @file{manual/index.html} file. It
1473 should include the name of the package being documented, as shown.
1474 @file{manual/index.html} is created by substitution from the file
1475 @file{gendocs_template}. (Feel free to modify the generic template
1476 for your own purposes.)
1478 If you have several manuals, you'll need to run this script several
1479 times with different arguments, specifying a different output
1480 directory with @option{-o} each time, and moving all the output to
1481 your web page. Then write (by hand) an overall index.html with links
1482 to them all. For example:
1485 gendocs.sh -o texinfo texinfo "GNU Texinfo manual"
1486 gendocs.sh -o info info "GNU Info manual"
1487 gendocs.sh -o info-stnd info-stnd "GNU info-stnd manual"
1490 You can set the environment variables @env{MAKEINFO}, @env{TEXI2DVI},
1491 and @env{DVIPS} to control the programs that get executed, and
1492 @env{GENDOCS_TEMPLATE_DIR} to control where the
1493 @file{gendocs_template} file is found.
1495 Please email bug reports, enhancement requests, or other
1496 correspondence to @email{bug-texinfo@@gnu.org}.
1499 @node CVS Keywords in Web Pages
1500 @section CVS Keywords in Web Pages
1501 @cindex cvs keywords in web pages
1502 @cindex rcs keywords in web pages
1503 @cindex $ keywords in web pages
1504 @cindex web pages, and cvs keywords
1506 Since @code{www.gnu.org} works through CVS, CVS keywords in your
1507 manual, such as @code{@w{$}Log$}, need special treatment (even if you
1508 don't happen to maintain your manual in CVS).
1510 If these keywords end up in the generated output as literal strings,
1511 they will be expanded. The most robust way to handle this is to turn
1512 off keyword expansion for such generated files. For existing files,
1516 cvs admin -ko @var{file1} @var{file2} ...
1523 cvs add -ko @var{file1} @var{file2} ...
1526 @xref{Keyword substitution,,,cvs,Version Management with CVS}.
1528 In Texinfo source, the recommended way to literally specify a
1529 ``dollar'' keyword is:
1535 The @code{@@w} prevents keyword expansion in the Texinfo source
1536 itself. Also, @code{makeinfo} notices the @code{@@w} and generates
1537 output avoiding the literal keyword string.
1540 @node Ethical and Philosophical Consideration
1541 @chapter Ethical and Philosophical Consideration
1545 The GNU project takes a strong stand for software freedom. Many times,
1546 this means you'll need to avoid certain technologies when such
1547 technologies conflict with our ethics of software freedom.
1549 Software patents threaten the advancement of free software and freedom
1550 to program. For our safety (which includes yours), we try to avoid
1551 using algorithms and techniques that we know are patented in the US or
1552 elsewhere, unless the patent looks so absurd that we doubt it will be
1553 enforced, or we have a suitable patent license allowing release of free
1556 Beyond that, sometimes the GNU project takes a strong stand against a
1557 particular patented technology in order to encourage everyone to
1558 reject it. For example, until the GIF patents expired in 2006, we
1559 specified that GNU packages and web pages should not include GIF image
1560 files, and that equal or better support for other image formats such
1561 as PNG and JPEG was crucial. (These other formats remain superior, so
1562 there is still no particular reason to use GIF's.)
1564 Software patents are not the only matter for ethical concern. A GNU
1565 package should not recommend use of any non-free program, nor should it
1566 require a non-free program (such as a non-free compiler or IDE) to
1567 build. Thus, a GNU package cannot be written in a programming language
1568 that does not have a free software implementation. Now that GNU/Linux
1569 systems are widely available, all GNU packages should function
1570 completely with the GNU/Linux system and not require any non-free
1571 software to build or function.
1573 A GNU package should not refer the user to any non-free documentation
1574 for free software. The need for free documentation to come with free
1575 software is now a major focus of the GNU project; to show that we are
1576 serious about the need for free documentation, we must not contradict
1577 our position by recommending use of documentation that isn't free.
1579 Finally, new issues concerning the ethics of software freedom come up
1580 frequently. We ask that GNU maintainers, at least on matters that
1581 pertain specifically to their package, stand with the rest of the GNU
1582 project when such issues come up.
1585 @chapter Terminology Issues
1588 This chapter explains a couple of issues of terminology which are
1589 important for correcting two widespread and important misunderstandings
1593 * Free Software and Open Source::
1597 @node Free Software and Open Source
1598 @section Free Software and Open Source
1599 @cindex free software
1601 @cindex movements, Free Software and Open Source
1603 The terms ``free software'' and ``open source'' are the slogans of two
1604 different movements which differ in their basic philosophy. The Free
1605 Software Movement is idealistic, and raises issues of freedom, ethics,
1606 principle and what makes for a good society. The Open Source Movement,
1607 founded in 1998, studiously avoids such questions. For more explanation,
1608 see @url{http://www.gnu.org/philosophy/free-software-for-freedom.html}.
1610 The GNU Project is aligned with the Free Software Movement. This
1611 doesn't mean that all GNU contributors and maintainers have to agree;
1612 your views on these issues are up to you, and you're entitled to express
1613 them when speaking for yourself.
1615 However, due to the much greater publicity that the Open Source
1616 Movement receives, the GNU Project needs to overcome a widespread
1617 mistaken impression that GNU is @emph{and always was} an activity of
1618 the Open Source Movement. For this reason, please use the term ``free
1619 software,'' not ``open source,'' in GNU software releases, GNU
1620 documentation, and announcements and articles that you publish in your
1621 role as the maintainer of a GNU package. A reference to the URL given
1622 above, to explain the difference, is a useful thing to include as
1626 @section GNU and Linux
1630 The GNU Project was formed to develop a free Unix-like operating system,
1631 GNU. The existence of this system is our major accomplishment.
1632 However, the widely used version of the GNU system, in which Linux is
1633 used as the kernel, is often called simply ``Linux''. As a result, most
1634 users don't know about the GNU Project's major accomplishment---or more
1635 precisely, they know about it, but don't realize it is the GNU Project's
1636 accomplishment and reason for existence. Even people who believe they
1637 know the real history often believe that the goal of GNU was to develop
1638 ``tools'' or ``utilities.''
1640 To correct this confusion, we have made a years-long effort to
1641 distinguish between Linux, the kernel that Linus Torvalds wrote, and
1642 GNU/Linux, the operating system that is the combination of GNU and
1643 Linux. The resulting increased awareness of what the GNU Project has
1644 already done helps every activity of the GNU Project recruit more
1645 support and contributors.
1647 Please make this distinction consistently in GNU software releases, GNU
1648 documentation, and announcements and articles that you publish in your
1649 role as the maintainer of a GNU package. If you want to explain the
1650 terminology and its reasons, you can refer to the URL
1651 @url{http://www.gnu.org/gnu/linux-and-gnu.html}.
1653 Do contrast the GNU system properly speaking to GNU/Linux, you can
1654 call it ``GNU/Hurd'' or ``the GNU/Hurd system.'' However, when that
1655 contrast is not specifically the focus, please call it just ``GNU'' or
1658 When referring to the collection of servers that is the higher level
1659 of the GNU kernel, please call it ``the Hurd'' or ``the GNU Hurd.''
1660 Note that this uses a space, not a slash.
1664 @cindex CVS repository
1669 We would like to recommend using @code{subversions.gnu.org} as the CVS
1670 repository for your package, and using @code{ftp.gnu.org} as the
1671 standard FTP site. It is ok to use other machines if you wish. If you
1672 use a company's machine to hold the repository for your program, or as
1673 its ftp site, please put this statement in a prominent place on the
1674 site, so as to prevent people from getting the wrong idea about the
1675 relationship between the package and the company:
1678 The programs <list of them> hosted here are free software packages
1679 of the GNU Project, not products of <company name>. We call them
1680 "free software" because you are free to copy and redistribute them,
1681 following the rules stated in the license of each package. For more
1682 information, see http://www.gnu.org/philosophy/free-sw.html.
1684 If you are looking for service or support for GNU software, see
1685 http://www.gnu.org/help/gethelp.html for suggestions of where to ask.
1687 If you would like to contribute to the development of one of these
1688 packages, contact the package maintainer or the bug-reporting address
1689 of the package (which should be listed in the package itself), or look
1690 on www.gnu.org for more information on how to contribute.
1693 @node Free Software Directory
1694 @chapter Free Software Directory
1695 @cindex Free Software Directory
1697 The Free Software Directory aims to be a complete list of free software
1698 packages, within certain criteria. Every GNU package should be listed
1699 there, so please contact @email{bug-directory@@gnu.org} to ask for
1700 information on how to write an entry for your package.
1702 @node Using the Proofreaders List
1703 @chapter Using the Proofreaders List
1704 @cindex proofreading
1706 If you want help finding errors in documentation,
1707 or help improving the quality of writing,
1708 or if you are not a native speaker of English
1709 and want help producing good English documentation,
1710 you can use the GNU proofreaders mailing list:
1711 @email{proofreaders@@gnu.org}.
1713 But be careful when you use the list,
1714 because there are over 200 people on it.
1715 If you simply ask everyone on the list to read your work,
1716 there will probably be tremendous duplication of effort
1717 by the proofreaders,
1718 and you will probably get the same errors reported 100 times.
1719 This must be avoided.
1721 Also, the people on the list do not want to get
1722 a large amount of mail from it.
1723 So do not ever ask people on the list to send mail to the list!
1725 Here are a few methods that seem reasonable to use:
1729 For something small, mail it to the list,
1730 and ask people to pick a random number from 1 to 20,
1731 and read it if the number comes out as 10.
1732 This way, assuming 50% response, some 5 people will read the piece.
1735 For a larger work, divide your work into around 20 equal-sized parts,
1736 tell people where to get it,
1737 and ask each person to pick randomly which part to read.
1739 Be sure to specify the random choice procedure;
1740 otherwise people will probably use a mental procedure
1741 that is not really random,
1742 such as "pick a part near the middle",
1743 and you will not get even coverage.
1745 You can either divide up the work physically, into 20 separate files,
1746 or describe a virtual division, such as by sections
1747 (if your work has approximately 20 sections).
1748 If you do the latter, be sure to be precise about it---for example,
1749 do you want the material before the first section heading
1750 to count as a section, or not?
1753 For a job needing special skills, send an explanation of it,
1754 and ask people to send you mail if they volunteer for the job.
1755 When you get enough volunteers, send another message to the list saying
1756 "I have enough volunteers, no more please."
1766 eval: (add-hook 'write-file-hooks 'time-stamp)
1767 time-stamp-start: "@set lastupdate "
1768 time-stamp-start: "@set lastupdate "
1770 time-stamp-format: "%:b %:d, %:y"
1771 compile-command: "make just-maintain"