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 September 26, 2011
11 @dircategory GNU organization
13 * Maintaining: (maintain). Maintaining GNU software.
16 @setchapternewpage off
18 @c Put everything in one index (arbitrarily chosen to be the concept index).
23 Information for maintainers of GNU software, last updated @value{lastupdate}.
25 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
26 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
27 2010, 2011 Free Software Foundation, Inc.
30 Permission is granted to copy, distribute and/or modify this document
31 under the terms of the GNU Free Documentation License, Version 1.3 or
32 any later version published by the Free Software Foundation; with no
33 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
34 Texts. A copy of the license is included in the section entitled
35 ``GNU Free Documentation License''.
40 @title Information for Maintainers of GNU Software
41 @author Richard Stallman
42 @author last updated @value{lastupdate}
44 @vskip 0pt plus 1filll
60 * Getting a GNU Account::
62 * Recruiting Developers::
70 * Ethical and Philosophical Consideration::
74 * Free Software Directory::
75 * Using the Proofreaders List::
76 * GNU Free Documentation License::
82 @chapter About This Document
84 This file contains guidelines and advice for someone who is the
85 maintainer of a GNU program on behalf of the GNU Project. Everyone is
86 entitled to change and redistribute GNU software; you need not pay
87 attention to this file to get permission. But if you want to maintain
88 a version for widespread distribution, we suggest you follow these
89 guidelines. If you are or would like to be a GNU maintainer, then it
90 is essential to follow these guidelines.
92 In addition to this document, please read and follow the GNU Coding
93 Standards (@pxref{Top, , Contents, standards, GNU Coding Standards}).
95 @cindex @code{bug-standards@@gnu.org} email address
96 @cindex Savannah repository for @code{gnustandards}
97 @cindex @code{gnustandards} project repository
98 Please send corrections or suggestions for this document to
99 @email{bug-standards@@gnu.org}. If you make a suggestion, please
100 include suggested new wording if you can. We prefer a context diff to
101 the Texinfo source, but if that's difficult for you, you can make a
102 diff for some other version of this document, or propose it in any way
103 that makes it clear. The source repository for this document can be
104 found at @url{http://savannah.gnu.org/projects/gnustandards}.
106 @cindex @code{gnustandards-commit@@gnu.org} mailing list
107 If you want to receive diffs for every change to these GNU documents,
108 join the mailing list @code{gnustandards-commit@@gnu.org}, for
109 instance via the web interface at
110 @url{http://lists.gnu.org/mailman/listinfo/gnustandards-commit}.
111 Archives are also available there.
113 @cindex Piercy, Marge
114 This document uses the gender-neutral third-person pronouns ``person'',
115 ``per'', ``pers'' and ``perself'' which were promoted, and perhaps
116 invented, by Marge Piercy in @cite{Woman on the Edge of Time}. They are
117 used just like ``she'', ``her'', ``hers'' and ``herself'', except that
118 they apply equally to males and females. For example, ``Person placed
119 per new program under the GNU GPL, to let the public benefit from per
120 work, and to enable per to feel person has done the right thing.''
122 This release of the GNU Maintainer Information was last updated
127 @chapter Getting Help
128 @cindex help, getting
130 @cindex @code{mentors@@gnu.org} mailing list
131 If you have any general questions or encounter a situation where it
132 isn't clear how to get something done or who to ask, you (as a GNU
133 contributor) can always write to @email{mentors@@gnu.org}, which is a
134 list of a few experienced GNU folks who have volunteered to answer
135 questions. Any GNU-related question is fair game for the
138 @cindex advisory committee
139 The GNU Advisory Committee helps to coordinate activities in the GNU
140 project on behalf of RMS (Richard Stallman, the Chief GNUisance). If
141 you have any organizational questions or concerns you can contact the
142 committee at @email{gnu-advisory@@gnu.org}. See
143 @url{http://www.gnu.org/contact/gnu-advisory.html} for the current
144 committee members. Additional information is in
145 @file{/gd/gnuorg/advisory}.
147 @cindex down, when GNU machines are
148 @cindex outage, of GNU machines
149 @cindex @url{http://identi.ca/group/fsfstatus}
150 If you find that any GNU computer systems (@code{fencepost.gnu.org},
151 @code{ftp.gnu.org}, @code{www.gnu.org}, @code{savannah.gnu.org},
152 @dots{}) seem to be down, you can check the current status at
153 @url{http://identi.ca/group/fsfstatus}. Most likely the problem, if
154 it can be alleviated at the FSF end, is already being worked on.
156 @cindex sysadmin, FSF
157 @cindex FSF system administrators
158 @cindex GNU system administrators
159 The FSF system administrators are responsible for the network and GNU
160 hardware. You can email them at @email{sysadmin@@fsf.org}, but please
161 try not to burden them unnecessarily.
164 @node Getting a GNU Account
165 @chapter Getting a GNU Account
166 @cindex shell account, on fencepost
167 @cindex @code{fencepost.gnu.org} GNU machine
169 @c We want to repeat this text later, so define a macro.
171 The directory @file{/gd/gnuorg} mentioned throughout this document is
172 available on the general GNU server, currently
173 @code{fencepost.gnu.org}. If you are the maintainer of a GNU package,
174 you should have an account there. If you don't have one already,
175 @url{http://www.gnu.org/software/README.accounts.html}. You can also
176 ask for accounts for people who significantly help you in working on
184 @chapter Stepping Down
185 @cindex stepping down as maintainer
186 @cindex resigning as maintainer
188 With good fortune, you will continue maintaining your package for many
189 decades. But sometimes for various reasons maintainers decide to step
192 If you're the official maintainer of a GNU package and you decide to
193 step down, please inform the GNU Project (@email{maintainers@@gnu.org}).
194 We need to know that the package no longer has a maintainer, so we can
195 look for and appoint a new maintainer.
197 @cindex @email{maintainers@@gnu.org}
198 If you have an idea for who should take over, please tell
199 @email{maintainers@@gnu.org} your suggestion. The appointment of a new
200 maintainer needs the GNU Project's confirmation, but your judgment that
201 a person is capable of doing the job will carry a lot of weight.
203 As your final act as maintainer, it would be helpful to set up or
204 update the package under @code{savannah.gnu.org} (@pxref{Old
205 Versions}). This will make it much easier for the new maintainer to
206 pick up where you left off and will ensure that the source tree is not
207 misplaced if it takes us a while to find a new maintainer.
210 @node Recruiting Developers
211 @chapter Recruiting Developers
213 Unless your package is a fairly small, you probably won't do all the
214 work on it yourself. Most maintainers recruit other developers to help.
216 Sometimes people will offer to help. Some of them will be capable,
217 while others will not. It's up to you to determine who provides useful
218 help, and encourage those people to participate more.
220 Some of the people who offer to help will support the GNU Project, while
221 others may be interested for other reasons. Some will support the goals
222 of the Free Software Movement, but some may not. They are all welcome
223 to help with the work---we don't ask people's views or motivations
224 before they contribute to GNU packages.
226 As a consequence, you cannot expect all contributors to support the GNU
227 Project, or to have a concern for its policies and standards. So part
228 of your job as maintainer is to exercise your authority on these points
229 when they arise. No matter how much of the work other people do, you
230 are in charge of what goes in the release. When a crucial point arises,
231 you should calmly state your decision and stick to it.
233 Sometimes a package has several co-maintainers who share the role of
234 maintainer. Unlike developers who help, co-maintainers have actually
235 been appointed jointly as the maintainers of the package, and they carry
236 out the maintainer's functions together. If you would like to propose
237 some of your developers as co-maintainers, please contact
238 @email{maintainers@@gnu.org}.
240 We're happy to acknowledge all major contributors to GNU packages on
241 the @url{http://www.gnu.org/people/people.html} web page. Please send
242 an entry for yourself to @email{webmasters@@gnu.org}, and feel free to
243 suggest it to other significant developers on your package.
247 @chapter Legal Matters
248 @cindex legal matters
250 This chapter describes procedures you should follow for legal reasons
251 as you maintain the program, to avoid legal difficulties.
255 * Legally Significant::
256 * Recording Contributors::
257 * Copying from Other Packages::
258 * Copyright Notices::
260 * External Libraries::
263 @node Copyright Papers
264 @section Copyright Papers
265 @cindex copyright papers
267 If you maintain an FSF-copyrighted package
268 certain legal procedures are required when incorporating legally significant
269 changes written by other people. This ensures that the FSF has the
270 legal right to distribute the package, and the standing to defend its
271 GPL-covered status in court if necessary.
273 @strong{Before} incorporating significant changes, make sure that the
274 person who wrote the changes has signed copyright papers and that the
275 Free Software Foundation has received and signed them. We may also need
276 an employer's disclaimer from the person's employer.
278 @cindex data base of GNU copyright assignments
279 To check whether papers have been received, look in
280 @file{/gd/gnuorg/copyright.list}. If you can't look there directly,
281 @email{fsf-records@@gnu.org} can check for you. Our clerk can also
282 check for papers that are waiting to be entered and inform you when
283 expected papers arrive.
285 @cindex @file{/gd/gnuorg} directory
286 @c This paragraph intentionally duplicates information given
287 @c near the beginning of the file--to make sure people don't miss it.
290 In order for the contributor to know person should sign papers, you need
291 to ask per for the necessary papers. If you don't know per well, and you
292 don't know that person is used to our ways of handling copyright papers,
293 then it might be a good idea to raise the subject with a message like
297 Would you be willing to assign the copyright to the Free Software
298 Foundation, so that we could install it in @var{package}?
305 Would you be willing to sign a copyright disclaimer to put this change
306 in the public domain, so that we can install it in @var{package}?
309 If the contributor then wants more information, you can send per the file
310 @file{/gd/gnuorg/conditions.text}, which explains per options (assign
311 vs.@: disclaim) and their consequences.
313 Once the conversation is under way and the contributor is ready for
314 more details, you should send one of the templates that are found in
315 the directory @file{/gd/gnuorg/Copyright/}; they are also available
316 from the @file{doc/Copyright/} directory of the @code{gnulib} project
317 at @url{http://savannah.gnu.org/projects/gnulib}. This section
318 explains which templates you should use in which circumstances.
319 @strong{Please don't use any of the templates except for those listed
320 here, and please don't change the wording.}
322 Once the conversation is under way, you can send the contributor the
323 precise wording and instructions by email. Before you do this, make
324 sure to get the current version of the template you will use! We change
325 these templates occasionally---don't keep using an old version.
327 For large changes, ask the contributor for an assignment. Send per a
328 copy of the file @file{request-assign.changes}. (Like all the
329 @samp{request-} files, it is in @file{/gd/gnuorg/Copyright} and in
332 For medium to small changes, request a personal disclaimer by sending
333 per the file @file{request-disclaim.changes}.
335 If the contributor is likely to keep making changes, person might want
336 to sign an assignment for all per future changes to the program. So it
337 is useful to offer per that alternative. If person wants to do it that
338 way, send per the @file{request-assign.future}.
340 When you send a @file{request-} file, you don't need to fill in anything
341 before sending it. Just send the file verbatim to the contributor. The
342 file gives per instructions for how to ask the FSF to mail per the
343 papers to sign. The @file{request-} file also raises the issue of
344 getting an employer's disclaimer from the contributor's employer.
346 When the contributor emails the form to the FSF, the FSF sends per
347 papers to sign. If person signs them right away, the whole process
348 takes a couple of weeks---mostly waiting for letters to go back and
351 For less common cases, we have template files you should send to the
352 contributor. Be sure to fill in the name of the person and the name
353 of the program in these templates, where it says @samp{NAME OF PERSON}
354 and @samp{NAME OF PROGRAM}, before sending; otherwise person might
355 sign without noticing them, and the papers would be useless. Note
356 that in some templates there is more than one place to put the name of
357 the program or the name of the person; be sure to change all of them.
358 All the templates raise the issue of an employer's disclaimer as well.
360 @cindex legal papers for changes in manuals
361 You do not need to ask for separate papers for a manual that is
362 distributed only in the software package it describes. But if we
363 sometimes distribute the manual separately (for instance, if we publish
364 it as a book), then we need separate legal papers for changes in the
365 manual. For smaller changes, use
366 @file{disclaim.changes.manual}; for larger ones, use
367 @file{assign.changes.manual}. To cover both past and future
368 changes to a manual, you can use @file{assign.future.manual}.
369 For a translation of a manual, use @file{assign.translation.manual}.
371 For translations of program strings (as used by GNU Gettext, for
372 example; @pxref{Internationalization,,, standards, GNU Coding
373 Standards}), use @file{disclaim.translation}. If you make use of the
374 Translation Project (@url{http://translationproject.org}) facilities,
375 please check with the TP coordinators that they have sent the
376 contributor the papers; if they haven't, then you should send the
377 papers. In any case, you should wait for the confirmation from the
378 FSF that the signed papers have been received and accepted before
379 integrating the new contributor's material, as usual.
381 If a contributor is reluctant to sign an assignment for a large change,
382 and is willing to sign a disclaimer instead, that is acceptable, so you
383 should offer this alternative if it helps you reach agreement. We
384 prefer an assignment for a larger change, so that we can enforce the GNU
385 GPL for the new text, but a disclaimer is enough to let us use the text.
387 If you maintain a collection of programs, occasionally someone will
388 contribute an entire separate program or manual that should be added to
389 the collection. Then you can use the files
390 @file{request-assign.program}, @file{disclaim.program},
391 @file{assign.manual}, and @file{disclaim.manual}. We very much prefer
392 an assignment for a new separate program or manual, unless it is quite
393 small, but a disclaimer is acceptable if the contributor insists on
394 handling the matter that way.
396 If a contributor wants the FSF to publish only a pseudonym, that is
397 ok. The contributor should say this, and state the desired pseudonym,
398 when answering the @file{request-} form. The actual legal papers will
399 use the real name, but the FSF will publish only the pseudonym. When
400 using one of the other forms, fill in the real name but ask the
401 contributor to discuss the use of a pseudonym with
402 @email{assign@@gnu.org} before sending back the signed form.
404 @strong{Although there are other templates besides the ones listed here,
405 they are for special circumstances; please do not use them without
406 getting advice from @email{assign@@gnu.org}.}
408 If you are not sure what to do, then please ask @email{assign@@gnu.org} for
409 advice; if the contributor asks you questions about the meaning and
410 consequences of the legal papers, and you don't know the answers, you
411 can forward them to @email{assign@@gnu.org} and we will answer.
413 @strong{Please do not try changing the wording of a template yourself.
414 If you think a change is needed, please talk with @email{assign@@gnu.org},
415 and we will work with a lawyer to decide what to do.}
417 @node Legally Significant
418 @section Legally Significant Changes
420 If a person contributes more than around 15 lines of code and/or text
421 that is legally significant for copyright purposes, we
422 need copyright papers for that contribution, as described above.
424 A change of just a few lines (less than 15 or so) is not legally
425 significant for copyright. A regular series of repeated changes, such
426 as renaming a symbol, is not legally significant even if the symbol
427 has to be renamed in many places. Keep in mind, however, that a
428 series of minor changes by the same person can add up to a significant
429 contribution. What counts is the total contribution of the person; it
430 is irrelevant which parts of it were contributed when.
432 Copyright does not cover ideas. If someone contributes ideas but no
433 text, these ideas may be morally significant as contributions, and
434 worth giving credit for, but they are not significant for copyright
435 purposes. Likewise, bug reports do not count for copyright purposes.
437 When giving credit to people whose contributions are not legally
438 significant for copyright purposes, be careful to make that fact
439 clear. The credit should clearly say they did not contribute
440 significant code or text.
442 When people's contributions are not legally significant because they
443 did not write code, do this by stating clearly what their contribution
444 was. For instance, you could write this:
449 * Richard Mlynarik <mly@@adoc.xerox.com> (1997)
450 * Masatake Yamato <masata-y@@is.aist-nara.ac.jp> (1999)
455 @code{Ideas by:} makes it clear that Mlynarik and Yamato here
456 contributed only ideas, not code. Without the @code{Ideas by:} note,
457 several years from now we would find it hard to be sure whether they
458 had contributed code, and we might have to track them down and ask
461 When you record a small patch in a change log file, first search for
462 previous changes by the same person, and see if per past
463 contributions, plus the new one, add up to something legally
464 significant. If so, you should get copyright papers for all per
465 changes before you install the new change.
467 If that is not so, you can install the small patch. Write @samp{(tiny
468 change)} after the patch author's name, like this:
471 2002-11-04 Robert Fenk <Robert.Fenk@@gmx.de> (tiny change)
474 @node Recording Contributors
475 @section Recording Contributors
476 @cindex recording contributors
478 @strong{Keep correct records of which portions were written by whom.}
479 This is very important. These records should say which files or
480 parts of files were written by each person, and which files or
481 parts of files were revised by each person. This should include
482 installation scripts as well as manuals and documentation
485 These records don't need to be as detailed as a change log. They
486 don't need to distinguish work done at different times, only different
487 people. They don't need describe changes in more detail than which
488 files or parts of a file were changed. And they don't need to say
489 anything about the function or purpose of a file or change---the
490 Register of Copyrights doesn't care what the text does, just who wrote
491 or contributed to which parts.
493 The list should also mention if certain files distributed in the same
494 package are really a separate program.
496 Only the contributions that are legally significant for copyright
497 purposes (@pxref{Legally Significant}) need to be listed. Small
498 contributions, bug reports, ideas, etc., can be omitted.
500 For example, this would describe an early version of GAS:
503 Dean Elsner first version of all files except gdb-lines.c and m68k.c.
504 Jay Fenlason entire files gdb-lines.c and m68k.c, most of app.c,
505 plus extensive changes in messages.c, input-file.c, write.c
506 and revisions elsewhere.
508 Note: GAS is distributed with the files obstack.c and obstack.h, but
509 they are considered a separate package, not part of GAS proper.
512 @cindex @file{AUTHORS} file
513 Please keep these records in a file named @file{AUTHORS} in the source
514 directory for the program itself.
516 You can use the change log as the basis for these records, if you
517 wish. Just make sure to record the correct author for each change
518 (the person who wrote the change, @emph{not} the person who installed
519 it), and add @samp{(tiny change)} for those changes that are too
520 trivial to matter for copyright purposes. Later on you can update the
521 @file{AUTHORS} file from the change log. This can even be done
522 automatically, if you are careful about the formatting of the change
525 @node Copying from Other Packages
526 @section Copying from Other Packages
528 When you copy legally significant code from another free software
529 package with a GPL-compatible license, you should look in the
530 package's records to find out the authors of the part you are copying,
531 and list them as the contributors of the code that you copied. If all
532 you did was copy it, not write it, then for copyright purposes you are
533 @emph{not} one of the contributors of @emph{this} code.
535 Especially when code has been released into the public domain, authors
536 sometimes fail to write a license statement in each file. In this
537 case, please first be sure that all the authors of the code have
538 disclaimed copyright interest. Then, when copying the new files into
539 your project, add a brief note at the beginning of the files recording
540 the authors, the public domain status, and anything else relevant.
542 On the other hand, when merging some public domain code into an
543 existing file covered by the GPL (or LGPL or other free software
544 license), there is no reason to indicate the pieces which are public
545 domain. The notice saying that the whole file is under the GPL (or
546 other license) is legally sufficient.
548 Using code that is released under a GPL-compatible free license,
549 rather than being in the public domain, may require preserving
550 copyright notices or other steps. Of course, you should do what is
553 If you are maintaining an FSF-copyrighted package, please verify we
554 have papers for the code you are copying, @emph{before} copying it.
555 If you are copying from another FSF-copyrighted package, then we
556 presumably have papers for that package's own code, but you must check
557 whether the code you are copying is part of an external library; if
558 that is the case, we don't have papers for it, so you should not copy
559 it. It can't hurt in any case to double-check with the developer of
562 When you are copying code for which we do not already have papers, you
563 need to get papers for it. It may be difficult to get the papers if
564 the code was not written as a contribution to your package, but that
565 doesn't mean it is ok to do without them. If you cannot get papers
566 for the code, you can only use it as an external library
567 (@pxref{External Libraries}).
570 @node Copyright Notices
571 @section Copyright Notices
572 @cindex copyright notices in program files
574 You should maintain a proper copyright notice and a license
575 notice in each nontrivial file in the package. (Any file more than ten
576 lines long is nontrivial for this purpose.) This includes header files
577 and interface definitions for
578 building or running the program, documentation files, and any supporting
579 files. If a file has been explicitly placed in the public domain, then
580 instead of a copyright notice, it should have a notice saying explicitly
581 that it is in the public domain.
583 Even image files and sound files should contain copyright notices and
584 license notices, if their format permits. Some formats do not have
585 room for textual annotations; for these files, state the copyright and
586 copying permissions in a @file{README} file in the same directory.
588 Change log files should have a copyright notice and license notice at
589 the end, since new material is added at the beginning but the end
592 When a file is automatically generated from some other file in the
593 distribution, it is useful for the automatic procedure to copy the
594 copyright notice and permission notice of the file it is generated
595 from, if possible. Alternatively, put a notice at the beginning saying
596 which file it is generated from.
598 A copyright notice looks like this:
601 Copyright (C) @var{year1}, @var{year2}, @var{year3} @var{copyright-holder}
604 The word @samp{Copyright} must always be in English, by international
607 The @var{copyright-holder} may be the Free Software Foundation, Inc., or
608 someone else; you should know who is the copyright holder for your
611 Replace the @samp{(C)} with a C-in-a-circle symbol if it is available.
612 For example, use @samp{@@copyright@{@}} in a Texinfo file. However,
613 stick with parenthesized @samp{C} unless you know that C-in-a-circle
614 will work. For example, a program's standard @option{--version}
615 message should use parenthesized @samp{C} by default, though message
616 translations may use C-in-a-circle in locales where that symbol is
617 known to work. Alternatively, the @samp{(C)} or C-in-a-circle can be
618 omitted entirely; the word @samp{Copyright} suffices.
620 To update the list of year numbers, add each year in which you have
621 made nontrivial changes to the package. (Here we assume you're using
622 a publicly accessible revision control server, so that every revision
623 installed is also immediately and automatically published.) When you
624 add the new year, it is not required to keep track of which files have
625 seen significant changes in the new year and which have not. It is
626 recommended and simpler to add the new year to all files in the
627 package, and be done with it for the rest of the year.
629 Don't delete old year numbers, though; they are significant since they
630 indicate when older versions might theoretically go into the public
631 domain, if the movie companies don't continue buying laws to further
632 extend copyright. If you copy a file into the package from some other
633 program, keep the copyright years that come with the file.
635 You can use a range (@samp{2008-2010}) instead of listing individual
636 years (@samp{2008, 2009, 2010}) if and only if: 1)@tie{}every year in
637 the range, inclusive, really is a ``copyrightable'' year that would be
638 listed individually; @emph{and} 2)@tie{}you make an explicit statement
639 in a @file{README} file about this usage.
641 For files which are regularly copied from another project (such as
642 @samp{gnulib}), leave the copyright notice as it is in the original.
644 The copyright statement may be split across multiple lines, both in
645 source files and in any generated output. This often happens for
646 files with a long history, having many different years of
649 For an FSF-copyrighted package, if you have followed the procedures to
650 obtain legal papers, each file should have just one copyright holder:
651 the Free Software Foundation, Inc. You should edit the file's
652 copyright notice to list that name and only that name.
654 But if contributors are not all assigning their copyrights to a single
655 copyright holder, it can easily happen that one file has several
656 copyright holders. Each contributor of nontrivial text is a copyright
659 In that case, you should always include a copyright notice in the name
660 of main copyright holder of the file. You can also include copyright
661 notices for other copyright holders as well, and this is a good idea
662 for those who have contributed a large amount and for those who
663 specifically ask for notices in their names. (Sometimes the license
664 on code that you copy in may require preserving certain copyright
665 notices.) But you don't have to include a notice for everyone who
666 contributed to the file (which would be rather inconvenient).
668 Sometimes a program has an overall copyright notice that refers to the
669 whole program. It might be in the @file{README} file, or it might be
670 displayed when the program starts up. This copyright notice should
671 mention the year of completion of the most recent major version; it
672 can mention years of completion of previous major versions, but that
676 @node License Notices
677 @section License Notices
678 @cindex license notices in program files
680 Every nontrivial file needs a license notice as well as the copyright
681 notice. (Without a license notice giving permission to copy and
682 change the file, the file is non-free.)
684 The package itself should contain a full copy of GPL in plain text
685 (conventionally in a file named @file{COPYING}) and the GNU Free
686 Documentation License (included within your documentation, so there is
687 no need for a separate plain text version). If the package contains
688 any files distributed under the Lesser GPL, it should contain a full
689 copy of its plain text version also (conventionally in a file named
690 @file{COPYING.LESSER}).
692 If you have questions about licensing issues for your GNU package,
693 please write @email{licensing@@gnu.org}.
696 * Which: Licensing of GNU Packages.
697 * Canonical: Canonical License Sources.
698 * Code: License Notices for Code.
699 * Documentation: License Notices for Documentation.
700 * Other: License Notices for Other Files.
704 @node Licensing of GNU Packages
705 @subsection Licensing of GNU Packages
707 Normally, GNU packages should use the latest version of the GNU GPL,
708 with the ``or any later version'' formulation. @xref{License Notices
709 for Code}, for the exact wording of the license notice.
711 Occasionally, a GNU library may provide functionality which is already
712 widely available to proprietary programs through alternative
713 implementations; for example, the GNU C Library. In such cases, the
714 Lesser GPL should be used (again, for the notice wording,
715 @pxref{License Notices for Code}). If a GNU library provides unique
716 functionality, however, the GNU GPL should be used.
717 @url{http://www.gnu.org/licenses/why-not-lgpl.html} discusses this
720 Some of these libraries need to work with programs released under
721 GPLv2-only; that is, which allow the GNU GPL version 2 but not later
722 versions. In this case, the GNU package should be released under a
723 dual license: GNU GPL version 2 (or any later version) and the GNU
724 Lesser GPL version 3 (or any later version). Here is the notice for
728 This file is part of GNU @var{package}.
730 GNU @var{package} is free software: you can redistribute it and/or
731 modify it under the terms of either:
733 * the GNU Lesser General Public License as published by the Free
734 Software Foundation; either version 3 of the License, or (at your
735 option) any later version.
739 * the GNU General Public License as published by the Free
740 Software Foundation; either version 2 of the License, or (at your
741 option) any later version.
743 or both in parallel, as here.
745 GNU @var{package} is distributed in the hope that it will be useful,
746 but WITHOUT ANY WARRANTY; without even the implied warranty of
747 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
748 General Public License for more details.
750 You should have received copies of the GNU General Public License and
751 the GNU Lesser General Public License along with this program. If
752 not, see @url{http://www.gnu.org/licenses/}.
755 For small packages, you can use ``This program'' instead of ``GNU
759 @node Canonical License Sources
760 @subsection Canonical License Sources
762 You can get the official versions of these files from several places.
763 You can use whichever is the most convenient for you.
767 @uref{http://www.gnu.org/licenses/}.
770 The @code{gnulib} project on @code{savannah.gnu.org}, which you
771 can access via anonymous Git or CVS. See
772 @uref{http://savannah.gnu.org/projects/gnulib}.
776 The official Texinfo sources for the licenses are also available in
777 those same places, so you can include them in your documentation. A
778 GFDL-covered manual should include the GFDL in this way. @xref{GNU
779 Sample Texts,,, texinfo, Texinfo}, for a full example in a Texinfo
783 @node License Notices for Code
784 @subsection License Notices for Code
786 Typically the license notice for program files (including build scripts,
787 configure files and makefiles) should cite the GPL, like this:
790 This file is part of GNU @var{package}.
792 GNU @var{package} is free software: you can redistribute it and/or
793 modify it under the terms of the GNU General Public License as
794 published by the Free Software Foundation, either version 3 of the
795 License, or (at your option) any later version.
797 GNU @var{package} is distributed in the hope that it will be useful,
798 but WITHOUT ANY WARRANTY; without even the implied warranty of
799 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
800 GNU General Public License for more details.
802 You should have received a copy of the GNU General Public License
803 along with this program. If not, see @url{http://www.gnu.org/licenses/}.
806 But in a small program which is just a few files, you can use
810 This program is free software: you can redistribute it and/or modify
811 it under the terms of the GNU General Public License as published by
812 the Free Software Foundation; either version 3 of the License, or
813 (at your option) any later version.
815 This program is distributed in the hope that it will be useful,
816 but WITHOUT ANY WARRANTY; without even the implied warranty of
817 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
818 GNU General Public License for more details.
820 You should have received a copy of the GNU General Public License
821 along with this program. If not, see @url{http://www.gnu.org/licenses/}.
824 In either case, for those few packages which use the Lesser GPL
825 (@pxref{Licensing of GNU Packages}), insert the word ``Lesser'' before
826 ``General'' in @emph{all three} places.
827 @url{http://@/www.gnu.org/@/licenses/@/gpl-howto.html} discusses application
828 the GPL in more detail.
831 @node License Notices for Documentation
832 @subsection License Notices for Documentation
834 Documentation files should have license notices also. Manuals should
835 use the GNU Free Documentation License. Following is an example of the
836 license notice to use after the copyright line(s) using all the
837 features of the GFDL.
840 Permission is granted to copy, distribute and/or modify this document
841 under the terms of the GNU Free Documentation License, Version 1.3 or
842 any later version published by the Free Software Foundation; with the
843 Invariant Sections being ``GNU General Public License'', with the
844 Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts
845 as in (a) below. A copy of the license is included in the section
846 entitled ``GNU Free Documentation License''.
848 (a) The FSF's Back-Cover Text is: ``You have the freedom to
849 copy and modify this GNU manual. Buying copies from the FSF
850 supports it in developing GNU and promoting software freedom.''
853 If the FSF does not publish this manual on paper, then omit the last
854 sentence in (a) that talks about copies from GNU Press. If the FSF is
855 not the copyright holder, then replace @samp{FSF} with the appropriate
858 Please adjust the list of invariant sections as appropriate for your
859 manual. If there are none, then say ``with no Invariant Sections''.
860 If your manual is not published by the FSF, and under 400 pages, you
861 can omit both cover texts.
863 @xref{GNU Sample Texts,,, texinfo, Texinfo}, for a full example in a
864 Texinfo manual, and see
865 @url{http://www.gnu.org/licenses/fdl-howto.html} for more advice about
866 how to use the GNU FDL.
868 If the manual is over 400 pages, or if the FSF thinks it might be a
869 good choice for publishing on paper, then please include the GNU GPL,
870 as in the notice above. Please also include our standard invariant
871 section which explains the importance of free documentation. Write to
872 @email{assign@@gnu.org} to get a copy of this section.
874 When you distribute several manuals together in one software package,
875 their on-line forms can share a single copy of the GFDL (see
876 section@tie{}6). However, the printed (@samp{.dvi}, @samp{.pdf},
877 @dots{}) forms should each contain a copy of the GFDL, unless they are
878 set up to be printed and published only together. Therefore, it is
879 usually simplest to include the GFDL in each manual.
882 @node License Notices for Other Files
883 @subsection License Notices for Other Files
885 Small supporting files, short manuals (under 300 lines long) and rough
886 documentation (@file{README} files, @file{INSTALL} files, etc.)@: can
887 use a simple all-permissive license like this one:
890 Copying and distribution of this file, with or without modification,
891 are permitted in any medium without royalty provided the copyright
892 notice and this notice are preserved. This file is offered as-is,
893 without any warranty.
896 Older versions of this license did not have the second sentence with
897 the express warranty disclaimer. There is no urgent need to update
898 existing files, but new files should use the new text.
900 If your package distributes Autoconf macros that are intended to be
901 used (hence distributed) by third-party packages under possibly
902 incompatible licenses, you may also use the above all-permissive
903 license for these macros.
906 @node External Libraries
907 @section External Libraries
909 When maintaining an FSF-copyrighted GNU package, you may occasionally
910 want to use a general-purpose free software module which offers a
911 useful functionality, as a ``library'' facility (though the module is
912 not always packaged technically as a library).
914 In a case like this, it would be unreasonable to ask the author of that
915 module to assign the copyright to the FSF. After all, person did not
916 write it specifically as a contribution to your package, so it would be
917 impertinent to ask per, out of the blue, ``Please give the FSF your
920 So the thing to do in this case is to make your program use the module,
921 but not consider it a part of your program. There are two reasonable
922 methods of doing this:
926 Assume the module is already installed on the system, and use it when
927 linking your program. This is only reasonable if the module really has
928 the form of a library.
931 Include the module in your package, putting the source in a separate
932 subdirectory whose @file{README} file says, ``This is not part of the
933 GNU FOO program, but is used with GNU FOO.'' Then set up your makefiles
934 to build this module and link it into the executable.
936 For this method, it is not necessary to treat the module as a library
937 and make a @samp{.a} file from it. You can link with the @samp{.o}
938 files directly in the usual manner.
941 Both of these methods create an irregularity, and our lawyers have told
942 us to minimize the amount of such irregularity. So consider using these
943 methods only for general-purpose modules that were written for other
944 programs and released separately for general use. For anything that was
945 written as a contribution to your package, please get papers signed.
949 @chapter Cleaning Up Changes
950 @cindex contributions, accepting
951 @cindex quality of changes suggested by others
953 Don't feel obligated to include every change that someone asks you to
954 include. You must judge which changes are improvements---partly based
955 on what you think the users will like, and partly based on your own
956 judgment of what is better. If you think a change is not good, you
959 If someone sends you changes which are useful, but written in an ugly
960 way or hard to understand and maintain in the future, don't hesitate to
961 ask per to clean up their changes before you merge them. Since the
962 amount of work we can do is limited, the more we convince others to help
963 us work efficiently, the faster GNU will advance.
965 If the contributor will not or can not make the changes clean enough,
966 then it is legitimate to say ``I can't install this in its present form;
967 I can only do so if you clean it up.'' Invite per to distribute per
968 changes another way, or to find other people to make them clean enough
969 for you to install and maintain.
971 The only reason to do these cleanups yourself is if (1) it is easy, less
972 work than telling the author what to clean up, or (2) the change is an
973 important one, important enough to be worth the work of cleaning it up.
975 The GNU Coding Standards are a good thing to send people when you ask
976 them to clean up changes (@pxref{Top, , Contents, standards, GNU Coding
977 Standards}). The Emacs Lisp manual contains an appendix that gives
978 coding standards for Emacs Lisp programs; it is good to urge Lisp authors to
979 read it (@pxref{Tips, , Tips and Conventions, elisp, The GNU Emacs Lisp
984 @chapter Platforms to Support
986 Most GNU packages run on a wide range of platforms. These platforms are
987 not equally important.
989 The most important platforms for a GNU package to support are GNU and
990 GNU/Linux. Developing the GNU operating system is the whole point of
991 the GNU Project; a GNU package exists to make the whole GNU system more
992 powerful. So please keep that goal in mind and let it shape your work.
993 For instance, every new feature you add should work on GNU, and
994 GNU/Linux if possible too. If a new feature only runs on GNU and
995 GNU/Linux, it could still be acceptable. However, a feature that runs
996 only on other systems and not on GNU or GNU/Linux makes no sense in a
999 You will naturally want to keep the program running on all the platforms
1000 it supports. But you personally will not have access to most of these
1001 platforms---so how should you do it?
1003 Don't worry about trying to get access to all of these platforms. Even
1004 if you did have access to all the platforms, it would be inefficient for
1005 you to test the program on each platform yourself. Instead, you should
1006 test the program on a few platforms, including GNU or GNU/Linux, and let
1007 the users test it on the other platforms. You can do this through a
1008 pretest phase before the real release; when there is no reason to expect
1009 problems, in a package that is mostly portable, you can just make a
1010 release and let the users tell you if anything unportable was
1013 It is important to test the program personally on GNU or GNU/Linux,
1014 because these are the most important platforms for a GNU package. If
1015 you don't have access to one of these platforms, as a GNU maintainer
1016 you can get access to the general GNU login machine; see
1017 @url{http://www.gnu.org/software/README.accounts.html}.
1019 Supporting other platforms is optional---we do it when that seems like
1020 a good idea, but we don't consider it obligatory. If the users don't
1021 take care of a certain platform, you may have to desupport it unless
1022 and until users come forward to help. Conversely, if a user offers
1023 changes to support an additional platform, you will probably want to
1024 install them, but you don't have to. If you feel the changes are
1025 complex and ugly, if you think that they will increase the burden of
1026 future maintenance, you can and should reject them. This includes
1027 both free or mainly-free platforms such as OpenBSD, FreeBSD, and
1028 NetBSD, and non-free platforms such as Windows.
1032 @chapter Dealing With Mail
1035 This chapter describes setting up mailing lists for your package, and
1036 gives advice on how to handle bug reports and random requests once you
1040 * Standard Mailing Lists:: @samp{bug-pkg@@gnu.org} and other standard names.
1041 * Creating Mailing Lists:: The best way is to use Savannah.
1042 * Replying to Mail:: Advice on replying to incoming mail.
1046 @node Standard Mailing Lists
1047 @section Standard Mailing Lists
1049 @cindex standard mailing lists
1050 @cindex mailing lists, standard names of
1052 @cindex mailing list for bug reports
1053 Once a program is in use, you will get bug reports for it. Most GNU
1054 programs have their own special lists for sending bug reports. The
1055 advertised bug-reporting email address should always be
1056 @samp{bug-@var{package}@@gnu.org}, to help show users that the program
1057 is a GNU package, but it is ok to set up that list to forward to another
1058 site if you prefer. The package distribution should state the
1059 name of the bug-reporting list in a prominent place, and ask users to
1060 help us by reporting bugs there.
1062 @cindex @email{bug-gnu-utils@@gnu.org}
1063 We also have a catch-all list, @email{bug-gnu-utils@@gnu.org}, which is
1064 used for all GNU programs that don't have their own specific lists. But
1065 nowadays we want to give each program its own bug-reporting list and
1066 move away from using @email{bug-gnu-utils}.
1068 @xref{Replying to Mail}, for more about handling and tracking bug
1071 @cindex help for users, mailing list for
1072 Some GNU programs with many users have another mailing list,
1073 @samp{help-@var{package}.org}, for people to ask other users for help.
1074 If your program has many users, you should create such a list for it.
1075 For a fairly new program, which doesn't have a large user base yet, it
1076 is better not to bother with this.
1078 @cindex announcements, mailing list for
1079 If you wish, you can also have a mailing list
1080 @samp{info-@var{package}} for announcements (@pxref{Announcements}).
1081 Any other mailing lists you find useful can also be created.
1084 @node Creating Mailing Lists
1085 @section Creating Mailing Lists
1087 @cindex creating mailing lists
1088 @cindex mailing lists, creating
1090 Using the web interface on @code{savannah.gnu.org} is by far the
1091 easiest way to create normal mailing lists, managed through Mailman on
1092 the GNU mail server. Once you register your package on Savannah, you
1093 can create (and remove) lists yourself through the `Mailing Lists'
1094 menu, without needing to wait for intervention by anyone else.
1095 Furthermore, lists created through Savannah will have a reasonable
1096 default configuration for antispam purposes (see below).
1098 To create and maintain simple aliases and unmanaged lists, you can
1099 edit @file{/com/mailer/aliases} on the main GNU server. If you don't
1100 have an account there, please read
1101 @url{http://www.gnu.org/software/README.accounts.html} (@pxref{Getting
1104 But if you don't want to learn how to do those things, you can
1105 alternatively ask @email{alias-file@@gnu.org} to add you to the
1106 bug-reporting list for your program. To set up a new list, contact
1107 @email{new-mailing-list@@gnu.org}. You can subscribe to a list managed
1108 by Mailman by sending mail to the corresponding @samp{-request} address.
1110 @cindex spam prevention
1111 You should moderate postings from non-subscribed addresses on your
1112 mailing lists, to prevent propagation of unwanted messages (``spam'')
1113 to subscribers and to the list archives. For lists controlled by
1114 Mailman, you can do this by setting @code{Privacy Options - Sender
1115 Filter - generic_nonmember_action} to @code{Hold}, and then
1116 periodically (daily is best) reviewing the held messages, accepting
1117 the real ones and discarding the junk.
1119 Lists created through Savannah will have this setting, and a number of
1120 others, such that spam will be automatically deleted (after a short
1121 delay). The Savannah mailing list page describes all the details.
1122 You should still review the held messages in order to approve any that
1126 @node Replying to Mail
1127 @section Replying to Mail
1129 @cindex responding to bug reports
1130 @cindex bug reports, handling
1131 @cindex help requests, handling
1133 When you receive bug reports, keep in mind that bug reports are crucial
1134 for your work. If you don't know about problems, you cannot fix them.
1135 So always thank each person who sends a bug report.
1137 You don't have an obligation to give more response than that, though.
1138 The main purpose of bug reports is to help you contribute to the
1139 community by improving the next version of the program. Many of the
1140 people who report bugs don't realize this---they think that the point is
1141 for you to help them individually. Some will ask you to focus on that
1142 @emph{instead of} on making the program better. If you comply with
1143 their wishes, you will have been distracted from the job of maintaining
1146 For example, people sometimes report a bug in a vague (and therefore
1147 useless) way, and when you ask for more information, they say, ``I just
1148 wanted to see if you already knew the solution'' (in which case the bug
1149 report would do nothing to help improve the program). When this
1150 happens, you should explain to them the real purpose of bug reports. (A
1151 canned explanation will make this more efficient.)
1153 When people ask you to put your time into helping them use the program,
1154 it may seem ``helpful'' to do what they ask. But it is much @emph{less}
1155 helpful than improving the program, which is the maintainer's real job.
1157 By all means help individual users when you feel like it, if you feel
1158 you have the time available. But be careful to limit the amount of time
1159 you spend doing this---don't let it eat away the time you need to
1160 maintain the program! Know how to say no; when you are pressed for
1161 time, just ``thanks for the bug report---I will fix it'' is enough
1164 Some GNU packages, such as Emacs and GCC, come with advice about how
1165 to make bug reports useful. Copying and adapting that could be very
1166 useful for your package.
1168 @cindex @url{http://bugs.gnu.org}
1169 @cindex bug reports, email tracker for
1170 @cindex bug reports, web tracker for
1171 If you would like to use an email-based bug tracking system, see
1172 @url{http://bugs.gnu.org}; this can be connected with the regular
1173 bug-reporting address. Alternatively, if you would like to use a
1174 web-based bug tracking system, Savannah supports this (@pxref{Old
1175 Versions}), but please don't fail to accept bugs by regular email as
1176 well---we don't want to put up unnecessary barriers against users
1181 @chapter Recording Old Versions
1182 @cindex version control
1184 It is very important to keep backup files of all source files of GNU.
1185 You can do this using a source control system (such as Bazaar, RCS,
1186 CVS, Git, Subversion, @dots{}) if you like. An easy way to use
1187 many such systems is via the Version Control library in Emacs
1188 (@pxref{Introduction to VC,, Introduction to Version Control, emacs,
1189 The GNU Emacs Manual}).
1191 The history of previous revisions and log entries is very important for
1192 future maintainers of the package, so even if you do not make it
1193 publicly accessible, be careful not to put anything in the repository or
1194 change log that you would not want to hand over to another maintainer
1197 @cindex @code{savannah-hackers@@gnu.org}
1198 The GNU Project provides a server that GNU packages can use
1199 for source control and other package needs: @code{savannah.gnu.org}.
1200 Savannah is managed by @email{savannah-hackers@@gnu.org}. For more
1201 details on using and contributing to Savannah, see
1202 @url{http://savannah.gnu.org/maintenance}.
1204 It's not an absolute requirement, but all GNU maintainers are strongly
1205 encouraged to take advantage of Savannah, as sharing such a central
1206 point can serve to foster a sense of community among GNU developers as
1207 well as help in keeping up with project management. Please don't mark
1208 Savannah projects for GNU packages as private; that defeats a large
1209 part of the purpose of using Savannah in the first place.
1211 @cindex @code{savannah-announce@@gnu.org} mailing list
1212 If you do use Savannah, please subscribe to the
1213 @email{savannah-announce@@gnu.org} mailing list
1214 (@url{http://lists.gnu.org/mailman/listinfo/savannah-announce}). This
1215 is a very low-volume list to keep Savannah users informed of system
1216 upgrades, problems, and the like.
1220 @chapter Distributions
1222 It is important to follow the GNU conventions when making GNU software
1226 * Distribution tar Files::
1227 * Distribution Patches::
1228 * Distribution on ftp.gnu.org::
1230 * Automated FTP Uploads::
1234 @node Distribution tar Files
1235 @section Distribution tar Files
1236 @cindex distribution, tar files
1238 The tar file for version @var{m}.@var{n} of program @code{foo} should be
1239 named @file{foo-@var{m}.@var{n}.tar}. It should unpack into a
1240 subdirectory named @file{foo-@var{m}.@var{n}}. Tar files should not
1241 unpack into files in the current directory, because this is inconvenient
1242 if the user happens to unpack into a directory with other files in it.
1244 Here is how the @file{Makefile} for Bison creates the tar file.
1245 This method is good for other programs.
1249 echo bison-`sed -e '/version_string/!d' \
1250 -e 's/[^0-9.]*\([0-9.]*\).*/\1/' -e q version.c` > .fname
1251 -rm -rf `cat .fname`
1253 dst=`cat .fname`; for f in $(DISTFILES); do \
1254 ln $(srcdir)/$$f $$dst/$$f || @{ echo copying $$f; \
1255 cp -p $(srcdir)/$$f $$dst/$$f ; @} \
1257 tar --gzip -chf `cat .fname`.tar.gz `cat .fname`
1258 -rm -rf `cat .fname` .fname
1261 Source files that are symbolic links to other file systems cannot be
1262 installed in the temporary directory using @code{ln}, so use @code{cp}
1266 Using Automake is a good way to take care of writing the @code{dist}
1269 @node Distribution Patches
1270 @section Distribution Patches
1271 @cindex patches, against previous releases
1273 If the program is large, it is useful to make a set of diffs for each
1274 release, against the previous important release.
1276 At the front of the set of diffs, put a short explanation of which
1277 version this is for and which previous version it is relative to.
1278 Also explain what else people need to do to update the sources
1279 properly (for example, delete or rename certain files before
1280 installing the diffs).
1282 The purpose of having diffs is that they are small. To keep them
1283 small, exclude files that the user can easily update. For example,
1284 exclude info files, DVI files, tags tables, output files of Bison or
1285 Flex. In Emacs diffs, we exclude compiled Lisp files, leaving it up
1286 to the installer to recompile the patched sources.
1288 When you make the diffs, each version should be in a directory suitably
1289 named---for example, @file{gcc-2.3.2} and @file{gcc-2.3.3}. This way,
1290 it will be very clear from the diffs themselves which version is which.
1294 @cindex time stamp in diffs
1295 If you use GNU @code{diff} to make the patch, use the options
1296 @samp{-rc2P}. That will put any new files into the output as ``entirely
1297 different''. Also, the patch's context diff headers should have dates
1298 and times in Universal Time using traditional Unix format, so that patch
1299 recipients can use GNU @code{patch}'s @samp{-Z} option. For example,
1300 you could use the following Bourne shell command to create the patch:
1303 LC_ALL=C TZ=UTC0 diff -rc2P gcc-2.3.2 gcc-2.3.3 | \
1304 gzip -9 >gcc-2.3.2-2.3.3.patch.gz
1307 If the distribution has subdirectories in it, then the diffs probably
1308 include some files in the subdirectories. To help users install such
1309 patches reliably, give them precise directions for how to run patch.
1310 For example, say this:
1313 To apply these patches, cd to the main directory of the program
1314 and then use `patch -p1'. `-p1' avoids guesswork in choosing
1315 which subdirectory to find each file in.
1318 It's wise to test your patch by applying it to a copy of the old
1319 version, and checking that the result exactly matches the new version.
1321 @node Distribution on ftp.gnu.org
1322 @section Distribution on @code{ftp.gnu.org}
1323 @cindex GNU ftp site
1324 @cindex @code{ftp.gnu.org}, the GNU release site
1326 GNU packages are distributed through the directory @file{/gnu} on
1327 @code{ftp.gnu.org}, via both HTTP and FTP. Each package should have a
1328 subdirectory named after the package, and all the distribution files
1329 for the package should go in that subdirectory.
1331 @xref{Automated FTP Uploads}, for procedural details of putting new
1332 versions on @code{ftp.gnu.org}.
1335 @section Test Releases
1336 @cindex test releases
1337 @cindex beta releases
1338 @cindex pretest releases
1340 @cindex @code{alpha.gnu.org}, test release site
1341 When you release a greatly changed new major version of a program, you
1342 might want to do so as a pretest. This means that you make a tar file,
1343 but send it only to a group of volunteers that you have recruited. (Use
1344 a suitable GNU mailing list/newsgroup to recruit them.)
1346 We normally use the server @code{alpha.gnu.org} for pretests and
1347 prerelease versions. @xref{Automated FTP Uploads}, for procedural details
1348 of putting new versions on @code{alpha.gnu.org}.
1350 Once a program gets to be widely used and people expect it to work
1351 solidly, it is a good idea to do pretest releases before each ``real''
1354 There are two ways of handling version numbers for pretest versions.
1355 One method is to treat them as versions preceding the release you are going
1358 In this method, if you are about to release version 4.6 but you want
1359 to do a pretest first, call it 4.5.90. If you need a second pretest,
1360 call it 4.5.91, and so on. If you are really unlucky and ten pretests
1361 are not enough, after 4.5.99 you could advance to 4.5.990 and so on.
1362 (You could also use 4.5.100, but 990 has the advantage of sorting in
1365 The other method is to attach a date to the release number that is
1366 coming. For a pretest for version 4.6, made on Dec 10, 2002, this
1367 would be 4.6.20021210. A second pretest made the same day could be
1370 For development snapshots that are not formal pretests, using just
1371 the date without the version numbers is ok too.
1373 One thing that you should never do is to release a pretest with the same
1374 version number as the planned real release. Many people will look only
1375 at the version number (in the tar file name, in the directory name that
1376 it unpacks into, or wherever they can find it) to determine whether a
1377 tar file is the latest version. People might look at the test release
1378 in this way and mistake it for the real release. Therefore, always
1379 change the number when you release changed code.
1382 @node Automated FTP Uploads
1383 @section Automated FTP Uploads
1385 @cindex ftp uploads, automated
1386 In order to upload new releases to @code{ftp.gnu.org} or
1387 @code{alpha.gnu.org}, you first need to register the necessary
1388 information. Then, you can perform uploads yourself, with no
1389 intervention needed by the system administrators.
1391 The general idea is that releases should be crytographically signed
1392 before they are made publicly available.
1395 * Automated Upload Registration::
1396 * Automated Upload Procedure::
1397 * FTP Upload Directive File - v1.1::
1398 * FTP Upload Directive File - v1.0::
1402 @node Automated Upload Registration
1403 @subsection Automated Upload Registration
1405 @cindex registration for uploads
1406 @cindex uploads, registration for
1408 Here is how to register your information so you can perform uploads
1409 for your GNU package:
1414 Create an account for yourself at @url{http://savannah.gnu.org}, if
1415 you don't already have one. By the way, this is also needed to
1416 maintain the web pages at @url{http://www.gnu.org} for your project
1417 (@pxref{Web Pages}).
1420 In the @samp{My Account Conf} page on @code{savannah}, upload the GPG
1421 key you will use to sign your packages. If you haven't created one
1422 before, you can do so with the command @code{gpg --gen-key} (you can
1423 accept all the default answers to its questions).
1425 Optional but recommended: Send your key to a GPG public key server:
1426 @code{gpg --keyserver keys.gnupg.net --send-keys @var{keyid}}, where
1427 @var{keyid} is the eight hex digits reported by @code{gpg
1428 --list-public-keys} on the @code{pub} line before the date. For full
1429 information about GPG, see @url{http://www.gnu.org/software/gpg}.
1432 Compose a message with the following items in some @var{msgfile}.
1433 Then GPG-sign it by running @code{gpg --clearsign @var{msgfile}}, and
1434 finally email the resulting @file{@var{msgfile}.asc}), to
1435 @email{ftp-upload@@gnu.org}.
1439 Name of package(s) that you are the maintainer for, your
1440 preferred email address, and your Savannah username.
1443 An ASCII armored copy of your GPG key, as an attachment. (@samp{gpg
1444 --export -a @var{your_key_id} >mykey.asc} should give you this.)
1447 A list of names and preferred email addresses of other individuals you
1448 authorize to make releases for which packages, if any (in the case that you
1449 don't make all releases yourself).
1452 ASCII armored copies of GPG keys for any individuals listed in (3).
1456 The administrators will acknowledge your message when they have added
1457 the proper GPG keys as authorized to upload files for the
1458 corresponding packages.
1460 The upload system will email receipts to the given email addresses
1461 when an upload is made, either successfully or unsuccessfully.
1464 @node Automated Upload Procedure
1465 @subsection Automated Upload Procedure
1469 Once you have registered your information as described in the previous
1470 section, you will be able to do ftp uploads for yourself using the
1471 following procedure.
1473 For each upload destined for @code{ftp.gnu.org} or
1474 @code{alpha.gnu.org}, three files (a @dfn{triplet}) need to be
1475 uploaded via ftp to the host @code{ftp-upload.gnu.org}.
1479 The file to be distributed; for example, @file{foo.tar.gz}.
1482 Detached GPG binary signature file for (1); for example,
1483 @file{foo.tar.gz.sig}. Make this with @samp{gpg -b foo.tar.gz}.
1486 A clearsigned @dfn{directive file}; for example,
1487 @file{foo.tar.gz.directive.asc}. Make this by preparing the plain
1488 text file @file{foo.tar.gz.directive} and then run @samp{gpg
1489 --clearsign foo.tar.gz.directive}. @xref{FTP Upload Directive File -
1490 v1.1}, for the contents of the directive file.
1493 The names of the files are important. The signature file must have the
1494 same name as the file to be distributed, with an additional
1495 @file{.sig} extension. The directive file must have the same name as
1496 the file to be distributed, with an additional @file{.directive.asc}
1497 extension. If you do not follow this naming convention, the upload
1498 @emph{will not be processed}.
1500 Since v1.1 of the upload script, it is also possible to upload a
1501 clearsigned directive file on its own (no accompanying @file{.sig} or
1502 any other file) to perform certain operations on the server.
1503 @xref{FTP Upload Directive File - v1.1}, for more information.
1505 Upload the file(s) via anonymous ftp to @code{ftp-upload.gnu.org}. If
1506 the upload is destined for @code{ftp.gnu.org}, place the file(s) in
1507 the @file{/incoming/ftp} directory. If the upload is destined for
1508 @code{alpha.gnu.org}, place the file(s) in the @file{/incoming/alpha}
1511 Uploads are processed every five minutes. Uploads that are in
1512 progress while the upload processing script is running are handled
1513 properly, so do not worry about the timing of your upload. Uploaded
1514 files that belong to an incomplete triplet are deleted automatically
1517 Your designated upload email addresses (@pxref{Automated Upload Registration})
1518 are sent a message if there are any problems processing an upload for your
1519 package. You also receive a message when your upload has been successfully
1522 One automated way to create and transfer the necessary files is to use
1523 the @code{gnupload} script, which is available from the
1524 @file{build-aux/} directory of the @code{gnulib} project at
1525 @url{http://savannah.gnu.org/projects/gnulib}. @code{gnupload} can
1526 also remove uploaded files. Run @code{gnupload --help} for a
1527 description and examples.
1529 @code{gnupload} uses the @code{ncftpput} program to do the actual
1530 transfers; if you don't happen to have the @code{ncftp} package
1531 installed, the @code{ncftpput-ftp} script in the @file{build-aux/}
1532 directory of @code{gnulib} serves as a replacement which uses plain
1533 command line @code{ftp}.
1535 If you have difficulties with an upload, email
1536 @email{ftp-upload@@gnu.org}. You can check the archive of uploads
1538 @url{https://lists.gnu.org/archive/html/ftp-upload-report}.
1541 @node FTP Upload Directive File - v1.1
1542 @subsection FTP Upload Directive File - v1.1
1544 The directive file name must end in @file{directive.asc}.
1546 When part of a triplet, the directive file must always contain the
1547 directives @code{version}, @code{directory} and @code{filename}, as
1548 described. In addition, a 'comment' directive is allowed.
1550 The @code{version} directive must always have the value @samp{1.1}.
1552 The @code{directory} directive specifies the final destination
1553 directory where the uploaded file and its @file{.sig} companion are to
1556 The @code{filename} directive must contain the name of the file to be
1557 distributed (item@tie{}(1) above).
1559 For example, as part of an uploaded triplet, a
1560 @file{foo.tar.gz.directive.asc} file might contain these lines (before
1561 being gpg clearsigned):
1566 filename: foo.tar.gz
1567 comment: hello world!
1570 This directory line indicates that @file{foo.tar.gz} and
1571 @file{foo.tar.gz.sig} are part of package @code{bar}. If you uploaded
1572 this triplet to @file{/incoming/ftp} and the system positively
1573 authenticates the signatures, the files @file{foo.tar.gz} and
1574 @file{foo.tar.gz.sig} will be placed in the directory
1575 @file{gnu/bar/v1} of the @code{ftp.gnu.org} site.
1577 The directive file can be used to create currently non-existent
1578 directory trees, as long as they are under the package directory for
1579 your package (in the example above, that is @code{bar}).
1581 If you upload a file that already exists in the FTP directory, the
1582 original will simply be archived and replaced with the new upload.
1584 @subheading Standalone directives
1586 When uploaded by itself, the directive file must contain one or more
1587 of the directives @code{symlink}, @code{rmsymlink} or @code{archive},
1588 in addition to the obligatory @code{directory} and @code{version}
1589 directives. A @code{filename} directive is not allowed, and a
1590 @code{comment} directive remains optional.
1592 If you use more than one directive, the directives are executed in the
1593 sequence they are specified in. If a directive results in an error,
1594 further execution of the upload is aborted.
1596 Removing a symbolic link (with @code{rmsymlink}) which does not exist
1597 results in an error. However, attempting to create a symbolic link
1598 that already exists (with @code{symlink}) is not an error. In this
1599 case @code{symlink} behaves like the command @command{ln -s -f}: any
1600 existing symlink is removed before creating the link. (But an
1601 existing regular file or directory is not removed.)
1603 Here are a few examples. The first removes a symlink:
1608 rmsymlink: foo-latest.tgz
1609 comment: remove a symlink
1613 Archive an old file, taking it offline:
1618 archive: foo-1.1.tar.gz
1619 comment: archive an old file; it will not be
1620 comment: available through FTP any more.
1624 Archive an old directory (with all contents), taking it offline:
1630 comment: archive an old directory; it and its entire
1631 comment: contents will not be available through FTP anymore
1635 Create a new symlink:
1640 symlink: foo-1.2.tar.gz foo-latest.tgz
1641 comment: create a new symlink
1645 Do everything at once:
1650 rmsymlink: foo-latest.tgz
1651 symlink: foo-1.2.tar.gz foo-latest.tgz
1652 archive: foo-1.1.tar.gz
1653 comment: now do everything at once
1657 @node FTP Upload Directive File - v1.0
1658 @subsection FTP Upload Directive File - v1.0
1660 @dfn{As of June 2006, the upload script is running in compatibility
1661 mode, allowing uploads with either version@tie{}1.1 or
1662 version@tie{}1.0 of the directive file syntax. Support for v1.0
1663 uploads will be phased out by the end of 2006, so please upgrade
1666 The directive file should contain one line, excluding the clearsigned
1667 data GPG that inserts, which specifies the final destination directory
1668 where items (1) and (2) are to be placed.
1670 For example, the @file{foo.tar.gz.directive.asc} file might contain the
1677 This directory line indicates that @file{foo.tar.gz} and
1678 @file{foo.tar.gz.sig} are part of package @code{bar}. If you were to
1679 upload the triplet to @file{/incoming/ftp}, and the system can
1680 positively authenticate the signatures, then the files
1681 @file{foo.tar.gz} and @file{foo.tar.gz.sig} will be placed in the
1682 directory @file{gnu/bar/v1} of the @code{ftp.gnu.org} site.
1684 The directive file can be used to create currently non-existent
1685 directory trees, as long as they are under the package directory for
1686 your package (in the example above, that is @code{bar}).
1690 @section Announcing Releases
1691 @cindex announcements
1693 @cindex @code{info-gnu} mailing list
1694 When you have a new release, please make an announcement. For
1695 official new releases, including those made just to fix bugs, we
1696 strongly recommend using the (moderated) general GNU announcements
1697 list, @email{info-gnu@@gnu.org}. Doing so makes it easier for users
1698 and developers to find the latest GNU releases. On the other hand,
1699 please do not announce test releases on @code{info-gnu} unless it's a
1700 highly unusual situation.
1702 @cindex @url{http://planet.gnu.org}
1703 @cindex Savannah, news area
1704 Please also post release announcements in the news section of your
1705 Savannah project site. Here, it is fine to also write news entries
1706 for test releases and any other newsworthy events. The news feeds
1707 from all GNU projects at savannah are aggregated at
1708 @url{http://planet.gnu.org} (GNU Planet). You can also post items
1709 directly, or arrange for feeds from other locations; see information
1710 on the GNU Planet web page.
1712 @cindex announcement mailing list, project-specific
1713 You can maintain your own mailing list (typically
1714 @email{info-@var{package}@@gnu.org}) for announcements as well if you
1715 like. For your own list, of course you decide as you see fit what
1716 events are worth announcing. (@xref{Mail}, for setting this up, and
1717 more suggestions on handling mail for your package.)
1719 @cindex contents of announcements
1720 When writing an announcement, please include the following:
1724 A very brief description (a few sentences at most) of the general
1725 purpose of your package.
1728 Your package's web page (normally
1729 @indicateurl{http://www.gnu.org/software/@var{package}/}).
1732 Your package's download location (normally
1733 @indicateurl{http://ftp.gnu.org/gnu/@var{package}/}). It is also
1734 useful to mention the mirror list at
1735 @url{http://www.gnu.org/order/ftp.html}, and that
1736 @url{http://ftpmirror.gnu.org/@var{package/}} will automatically
1737 redirect to a nearby mirror.
1740 The @t{NEWS} (@pxref{NEWS File,,, standards, GNU Coding Standards}) for
1741 the present release.
1749 Please write web pages about your package, and install them on
1750 @code{www.gnu.org}. They should follow our usual standards for web
1751 pages (see @url{http://www.gnu.org/server/@/fsf-html-style-sheet.html}).
1752 The overall goals are to support a wide variety of browsers, to focus
1753 on information rather than flashy eye candy, and to keep the site
1756 We encourage you to use the standard @code{www.gnu.org} template as
1757 the basis for your pages:
1758 @url{http://www.gnu.org/server/@/standards/@/boilerplate-source.html}.
1760 Some GNU packages have just simple web pages, but the more information
1761 you provide, the better. So please write as much as you usefully can,
1762 and put all of it on @code{www.gnu.org}. However, pages that access
1763 databases (including mail archives and bug tracking) are an exception;
1764 set them up on whatever site is convenient for you, and make the pages
1765 on @code{www.gnu.org} link to that site.
1768 * Hosting for Web Pages::
1769 * Freedom for Web Pages::
1770 * Manuals on Web Pages::
1771 * CVS Keywords in Web Pages::
1775 @node Hosting for Web Pages
1776 @section Hosting for Web Pages
1778 The best way to maintain the web pages for your project is to register
1779 the project on @code{savannah.gnu.org}. Then you can edit the pages
1780 using CVS, using the separate ``web repository'' available on
1781 Savannah, which corresponds to
1782 @indicateurl{http://www.gnu.org/software/@var{package}/}. You can
1783 keep your source files there too (using any of a variety of version
1784 control systems), but you can use @code{savannah.gnu.org} only for
1785 your gnu.org web pages if you wish; simply register a ``web-only''
1788 If you don't want to use that method, please talk with
1789 @email{webmasters@@gnu.org} about other possible methods. For
1790 instance, you can mail them pages to install, if necessary. But that
1791 is more work for them, so please use Savannah if you can.
1793 If you use Savannah, you can use a special file named @file{.symlinks}
1794 in order to create symbolic links, which are not supported in CVS.
1796 @url{http://www.gnu.org/server/standards/README.webmastering.html#symlinks}.
1799 @node Freedom for Web Pages
1800 @section Freedom for Web Pages
1802 If you use a site other than @code{www.gnu.org}, please make sure that
1803 the site runs on free software alone. (It is ok if the site uses
1804 unreleased custom software, since that is free in a trivial sense:
1805 there's only one user and it has the four freedoms.) If the web site
1806 for a GNU package runs on non-free software, the public will see this,
1807 and it will have the effect of granting legitimacy to the non-free
1810 If you use multiple sites, they should all follow that criterion.
1811 Please don't link to a site that is about your package, which the
1812 public might perceive as connected with it and reflecting the position
1813 of its developers, unless it follows that criterion.
1815 Historically, web pages for GNU packages did not include GIF images,
1816 because of patent problems (@pxref{Ethical and Philosophical
1817 Consideration}). Although the GIF patents expired in 2006, using GIF
1818 images is still not recommended, as the PNG and JPEG formats are
1819 generally superior. See @url{http://www.gnu.org/philosophy/gif.html}.
1822 @node Manuals on Web Pages
1823 @section Manuals on Web Pages
1825 The web pages for the package should include its manuals, in HTML,
1826 DVI, Info, PostScript, PDF, plain ASCII, and Texinfo format (source).
1827 All of these can be generated automatically from the Texinfo source
1828 using Makeinfo and other programs.
1830 When there is only one manual, put it in a subdirectory called
1831 @file{manual}; the file @file{manual/index.html} should have a link to
1832 the manual in each of its forms.
1834 If the package has more than one manual, put each one in a
1835 subdirectory of @file{manual}, set up @file{index.html} in each
1836 subdirectory to link to that manual in all its forms, and make
1837 @file{manual/index.html} link to each manual through its subdirectory.
1839 See the section below for details on a script to make the job of
1840 creating all these different formats and index pages easier.
1842 We would like to list all GNU manuals on the page
1843 @url{http://www.gnu.org/manual}, so if yours isn't there, please send
1844 mail to @code{webmasters@@gnu.org}, asking them to add yours, and they
1845 will do so based on the contents of your @file{manual} directory.
1848 * Invoking gendocs.sh::
1852 @node Invoking gendocs.sh
1853 @subsection Invoking @command{gendocs.sh}
1855 @cindex generating documentation output
1857 The script @command{gendocs.sh} eases the task of generating the
1858 Texinfo documentation output for your web pages
1859 section above. It has a companion template file, used as the basis
1860 for the HTML index pages. Both are available from the Texinfo CVS
1864 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh}
1865 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template}
1868 There is also a minimalistic template, available from:
1871 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template_min}
1874 Invoke the script like this, in the directory containing the Texinfo
1878 gendocs.sh --email @var{yourbuglist} @var{yourmanual} "GNU @var{yourmanual} manual"
1881 @noindent where @var{yourmanual} is the short name for your package
1882 and @var{yourbuglist} is the email address for bug reports (which
1883 should be @code{bug-@var{package}@@gnu.org}). The script processes
1884 the file @file{@var{yourmanual}.texinfo} (or @file{.texi} or
1885 @file{.txi}). For example:
1889 # download gendocs.sh and gendocs_template
1890 gendocs.sh --email bug-texinfo@@gnu.org texinfo "GNU Texinfo manual"
1893 @command{gendocs.sh} creates a subdirectory @file{manual/} containing
1894 the manual generated in all the standard output formats: Info, HTML,
1895 DVI, and so on, as well as the Texinfo source. You then need to move
1896 all those files, retaining the subdirectories, into the web pages for
1899 You can specify the option @option{-o @var{outdir}} to override the
1900 name @file{manual}. Any previous contents of @var{outdir} will be deleted.
1902 The second argument, with the description, is included as part of the
1903 HTML @code{<title>} of the overall @file{manual/index.html} file. It
1904 should include the name of the package being documented, as shown.
1905 @file{manual/index.html} is created by substitution from the file
1906 @file{gendocs_template}. (Feel free to modify the generic template
1907 for your own purposes.)
1909 If you have several manuals, you'll need to run this script several
1910 times with different arguments, specifying a different output
1911 directory with @option{-o} each time, and moving all the output to
1912 your web page. Then write (by hand) an overall index.html with links
1913 to them all. For example:
1917 gendocs.sh --email bug-texinfo@@gnu.org -o texinfo texinfo "GNU Texinfo manual"
1918 gendocs.sh --email bug-texinfo@@gnu.org -o info info "GNU Info manual"
1919 gendocs.sh --email bug-texinfo@@gnu.org -o info-stnd info-stnd "GNU info-stnd manual"
1922 By default, the script uses @command{makeinfo} for generating
1923 @acronym{HTML} output. If you prefer to use @command{texi2html}, use
1924 the @option{--texi2html} command line option, e.g.:
1927 gendocs --texi2html -o texinfo texinfo "GNU Texinfo manual"
1930 The template files will automatically produce entries for additional
1931 HTML output generated by @command{texi2html} (i.e., split by sections
1934 You can set the environment variables @env{MAKEINFO}, @env{TEXI2DVI},
1935 @env{TEXI2HTML} and @env{DVIPS} to control the programs that get
1936 executed, and @env{GENDOCS_TEMPLATE_DIR} to control where the
1937 @file{gendocs_template} file is found.
1939 As usual, run @samp{gendocs.sh --help} for a description of all the
1940 options, environment variables, and more information.
1942 Please email bug reports, enhancement requests, or other
1943 correspondence to @email{bug-texinfo@@gnu.org}.
1946 @node CVS Keywords in Web Pages
1947 @section CVS Keywords in Web Pages
1948 @cindex CVS keywords in web pages
1949 @cindex RCS keywords in web pages
1950 @cindex $ keywords in web pages
1951 @cindex web pages, and CVS keywords
1953 Since @code{www.gnu.org} works through CVS, CVS keywords in your
1954 manual, such as @code{@w{$}Log$}, need special treatment (even if you
1955 don't happen to maintain your manual in CVS).
1957 If these keywords end up in the generated output as literal strings,
1958 they will be expanded. The most robust way to handle this is to turn
1959 off keyword expansion for such generated files. For existing files,
1963 cvs admin -ko @var{file1} @var{file2} ...
1970 cvs add -ko @var{file1} @var{file2} ...
1973 @c The CVS manual is now built with numeric references and no nonsplit
1974 @c form, so it's not worth trying to give a direct link.
1975 See the ``Keyword Substitution'' section in the CVS manual, available
1976 at @url{http://ximbiot.com/cvs/manual}.
1978 In Texinfo source, the recommended way to literally specify a
1979 ``dollar'' keyword is:
1985 The @code{@@w} prevents keyword expansion in the Texinfo source
1986 itself. Also, @code{makeinfo} notices the @code{@@w} and generates
1987 output avoiding the literal keyword string.
1990 @node Ethical and Philosophical Consideration
1991 @chapter Ethical and Philosophical Consideration
1995 The GNU project takes a strong stand for software freedom. Many
1996 times, this means you'll need to avoid certain technologies when their
1997 use would conflict with our long-term goals.
1999 Software patents threaten the advancement of free software and freedom
2000 to program. There are so many software patents in the US that any
2001 large program probably implements hundreds of patented techniques,
2002 unknown to the program's developers. It would be futile and
2003 self-defeating to try to find and avoid all these patents. But there
2004 are some patents which we know are likely to be used to threaten free
2005 software, so we make an effort to avoid the patented techniques. If
2006 you are concerned about the danger of a patent and would like advice,
2007 write to @email{licensing@@gnu.org}, and we will try to help you get
2008 advice from a lawyer.
2010 Sometimes the GNU project takes a strong stand against a particular
2011 patented technology in order to encourage society to reject it.
2013 For example, the MP3 audio format is covered by a software patent in
2014 the USA and some other countries. A patent holder has threatened
2015 lawsuits against the developers of free programs (these are not GNU
2016 programs) to produce and play MP3, and some GNU/Linux distributors are
2017 afraid to include them. Development of the programs continues, but we
2018 campaign for the rejection of MP3 format in favor of Ogg Vorbis format.
2020 A GNU package should not recommend use of any non-free program, nor
2021 should it require a non-free program (such as a non-free compiler or
2022 IDE) to build. Thus, a GNU package cannot be written in a programming
2023 language that does not have a free software implementation. Now that
2024 GNU/Linux systems are widely available, all GNU packages should
2025 provide full functionality on a 100% free GNU/Linux system, and should
2026 not require any non-free software to build or function.
2027 The GNU Coding Standards say a lot more about this issue.
2029 A GNU package should not refer the user to any non-free documentation
2030 for free software. The need for free documentation to come with free
2031 software is now a major focus of the GNU project; to show that we are
2032 serious about the need for free documentation, we must not contradict
2033 our position by recommending use of documentation that isn't free.
2035 Finally, new issues concerning the ethics of software freedom come up
2036 frequently. We ask that GNU maintainers, at least on matters that
2037 pertain specifically to their package, stand with the rest of the GNU
2038 project when such issues come up.
2042 @chapter Terminology Issues
2045 This chapter explains a couple of issues of terminology which are
2046 important for correcting two widespread and important misunderstandings
2050 * Free Software and Open Source::
2054 @node Free Software and Open Source
2055 @section Free Software and Open Source
2056 @cindex free software movement
2058 @cindex movement, free software
2059 @cindex development method, open source
2061 The terms ``free software'' and ``open source'', while describing
2062 almost the same category of software, stand for views based on
2063 fundamentally different values. The free software movement is
2064 idealistic, and raises issues of freedom, ethics, principle and what
2065 makes for a good society. The term open source, initiated in 1998, is
2066 associated with a philosophy which studiously avoids such questions.
2067 For a detailed explanation, see
2068 @url{http://www.gnu.org/philosophy/open-source-misses-the-point.html}.
2070 The GNU Project is aligned with the free software movement. This
2071 doesn't mean that all GNU contributors and maintainers have to agree;
2072 your views on these issues are up to you, and you're entitled to express
2073 them when speaking for yourself.
2075 However, due to the much greater publicity that the term ``open source''
2076 receives, the GNU Project needs to overcome a widespread
2077 mistaken impression that GNU is @emph{and always was} an ``open
2078 source'' activity. For this reason, please use the term ``free
2079 software'', not ``open source'', in GNU software releases, GNU
2080 documentation, and announcements and articles that you publish in your
2081 role as the maintainer of a GNU package. A reference to the URL given
2082 above, to explain the difference, is a useful thing to include as
2087 @section GNU and Linux
2091 The GNU Project was formed to develop a free Unix-like operating system,
2092 GNU. The existence of this system is our major accomplishment.
2093 However, the widely used version of the GNU system, in which Linux is
2094 used as the kernel, is often called simply ``Linux''. As a result, most
2095 users don't know about the GNU Project's major accomplishment---or more
2096 precisely, they know about it, but don't realize it is the GNU Project's
2097 accomplishment and reason for existence. Even people who believe they
2098 know the real history often believe that the goal of GNU was to develop
2099 ``tools'' or ``utilities''.
2101 To correct this confusion, we have made a years-long effort to
2102 distinguish between Linux, the kernel that Linus Torvalds wrote, and
2103 GNU/Linux, the operating system that is the combination of GNU and
2104 Linux. The resulting increased awareness of what the GNU Project has
2105 already done helps every activity of the GNU Project recruit more
2106 support and contributors.
2108 Please make this distinction consistently in GNU software releases, GNU
2109 documentation, and announcements and articles that you publish in your
2110 role as the maintainer of a GNU package. If you want to explain the
2111 terminology and its reasons, you can refer to the URL
2112 @url{http://www.gnu.org/gnu/linux-and-gnu.html}.
2114 To contrast the GNU system properly with respect to GNU/Linux, you can
2115 call it ``GNU/Hurd'' or ``the GNU/Hurd system''. However, when that
2116 contrast is not specifically the focus, please call it just ``GNU'' or
2119 When referring to the collection of servers that is the higher level
2120 of the GNU kernel, please call it ``the Hurd'' or ``the GNU Hurd''.
2121 Note that this uses a space, not a slash.
2126 @cindex CVS repository
2128 @cindex source repository
2129 @cindex version control system
2131 @cindex release site
2134 We recommend using @code{savannah.gnu.org} for the source code
2135 repository for your package, but that's not required. @xref{Old
2136 Versions}, for more information about Savannah.
2138 We strongly urge you to use @code{ftp.gnu.org} as the standard
2139 distribution site for releases. Doing so makes it easier for
2140 developers and users to find the latest GNU releases. However, it is
2141 ok to use another server if you wish, provided it allows access from
2142 the general public without limitation (for instance, without excluding
2145 If you use a company's machine to hold the repository for your
2146 program, or as its release distribution site, please put this
2147 statement in a prominent place on the site, so as to prevent people
2148 from getting the wrong idea about the relationship between the package
2152 The programs <list of them> hosted here are free software packages
2153 of the GNU Project, not products of <company name>. We call them
2154 "free software" because you are free to copy and redistribute them,
2155 following the rules stated in the license of each package. For more
2156 information, see http://www.gnu.org/philosophy/free-sw.html.
2158 If you are looking for service or support for GNU software, see
2159 http://www.gnu.org/gethelp/ for suggestions of where to ask.
2161 If you would like to contribute to the development of one of these
2162 packages, contact the package maintainer or the bug-reporting address
2163 of the package (which should be listed in the package itself), or look
2164 on www.gnu.org for more information on how to contribute.
2170 @cindex Donations, for packages
2171 @cindex Money, donated to packages
2173 As a maintainer, you might want to accept donations for your work,
2174 especially if you pay for any of your own hosting/development
2175 infrastructure. Following is some text you can adapt to your own
2176 situation, and use on your package's web site, @file{README}, or
2177 in wherever way you find it useful:
2180 We appreciate contributions of any size -- donations enable us to spend
2181 more time working on the project, and help cover our infrastructure
2184 If you'd like to make a small donation, please visit @var{url1} and do
2185 it through @var{payment-service}. Since our project isn't a
2186 tax-exempt organization, we can't offer you a tax deduction, but for
2187 all donations over @var{amount1}, we'd be happy to recognize your
2188 contribution on @var{url2}.
2190 We are also happy to consider making particular improvements or
2191 changes, or giving specific technical assistance, in return for a
2192 substantial donation over @var{amount2}. If you would like to discuss
2193 this possibility, write to us at @var{address}.
2195 Another possibility is to pay a software maintenance fee. Again,
2196 write to us about this at @var{address} to discuss how much you want
2197 to pay and how much maintenance we can offer in return. If you pay
2198 more than @var{amount1}, we can give you a document for your records.
2200 Thanks for your support!
2203 We don't recommend any specific payment service. However, GNU
2204 developers should not use a service that requires them to sign a
2205 proprietary software license, such as Google's payment service.
2207 Of course, it is also good to encourage people to join or contribute
2208 to the FSF (@url{http://www.fsf.org}), either instead of or as well as
2209 package-specific donations.
2212 @node Free Software Directory
2213 @chapter Free Software Directory
2214 @cindex Free Software Directory
2215 @cindex Directory, Free Software
2217 The Free Software Directory aims to be a complete list of free
2218 software packages, within certain criteria. Every GNU package should
2219 be listed there, so please see
2220 @url{http://www.gnu.org/help/directory.html#adding-entries} for
2221 information on how to write an entry for your package. Contact
2222 @email{bug-directory@@gnu.org} with any questions or suggestions for
2223 the Free Software Directory.
2226 @node Using the Proofreaders List
2227 @chapter Using the Proofreaders List
2228 @cindex proofreading
2230 If you want help finding errors in documentation,
2231 or help improving the quality of writing,
2232 or if you are not a native speaker of English
2233 and want help producing good English documentation,
2234 you can use the GNU proofreaders mailing list:
2235 @email{proofreaders@@gnu.org}.
2237 But be careful when you use the list,
2238 because there are over 200 people on it.
2239 If you simply ask everyone on the list to read your work,
2240 there will probably be tremendous duplication of effort
2241 by the proofreaders,
2242 and you will probably get the same errors reported 100 times.
2243 This must be avoided.
2245 Also, the people on the list do not want to get
2246 a large amount of mail from it.
2247 So do not ever ask people on the list to send mail to the list!
2249 Here are a few methods that seem reasonable to use:
2253 For something small, mail it to the list,
2254 and ask people to pick a random number from 1 to 20,
2255 and read it if the number comes out as 10.
2256 This way, assuming 50% response, some 5 people will read the piece.
2259 For a larger work, divide your work into around 20 equal-sized parts,
2260 tell people where to get it,
2261 and ask each person to pick randomly which part to read.
2263 Be sure to specify the random choice procedure;
2264 otherwise people will probably use a mental procedure
2265 that is not really random,
2266 such as ``pick a part near the middle'',
2267 and you will not get even coverage.
2269 You can either divide up the work physically, into 20 separate files,
2270 or describe a virtual division, such as by sections
2271 (if your work has approximately 20 sections).
2272 If you do the latter, be sure to be precise about it---for example,
2273 do you want the material before the first section heading
2274 to count as a section, or not?
2277 For a job needing special skills, send an explanation of it,
2278 and ask people to send you mail if they volunteer for the job.
2279 When you get enough volunteers, send another message to the list saying
2280 ``I have enough volunteers, no more please.''
2284 @node GNU Free Documentation License
2285 @appendix GNU Free Documentation License
2287 @cindex FDL, GNU Free Documentation License
2298 eval: (add-hook 'write-file-hooks 'time-stamp)
2299 time-stamp-start: "@set lastupdate "
2300 time-stamp-start: "@set lastupdate "
2302 time-stamp-format: "%:b %:d, %:y"
2303 compile-command: "make -C work.m"