Mercurial > gnulib
annotate doc/maintain.texi @ 17328:603aa5fbb298
autoupdate
| author | Karl Berry <karl@freefriends.org> |
|---|---|
| date | Thu, 14 Feb 2013 09:43:22 -0800 |
| parents | 01978a889dad |
| children | 8826dc2ee3ee |
| rev | line source |
|---|---|
| 4958 | 1 \input texinfo.tex @c -*-texinfo-*- |
| 2 @c %**start of header | |
| 3 @setfilename maintain.info | |
| 11738 | 4 @settitle Information for Maintainers of GNU Software |
| 4958 | 5 @c For double-sided printing, uncomment: |
| 6 @c @setchapternewpage odd | |
| 7 @c This date is automagically updated when you save this file: | |
| 17328 | 8 @set lastupdate February 13, 2013 |
| 4958 | 9 @c %**end of header |
| 10 | |
| 11 @dircategory GNU organization | |
| 12 @direntry | |
| 13 * Maintaining: (maintain). Maintaining GNU software. | |
| 14 @end direntry | |
| 15 | |
| 16 @setchapternewpage off | |
| 17 | |
| 18 @c Put everything in one index (arbitrarily chosen to be the concept index). | |
| 19 @syncodeindex fn cp | |
| 20 @syncodeindex pg cp | |
| 21 | |
| 22 @copying | |
| 23 Information for maintainers of GNU software, last updated @value{lastupdate}. | |
| 24 | |
| 7910 | 25 Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, |
| 14172 | 26 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, |
| 17256 | 27 2010, 2011, 2012, 2013 Free Software Foundation, Inc. |
| 4958 | 28 |
| 29 @quotation | |
| 9639 | 30 Permission is granted to copy, distribute and/or modify this document |
|
10762
d67664a4e01c
Change license to GFDLv1.3+.
Simon Josefsson <simon@josefsson.org>
parents:
10642
diff
changeset
|
31 under the terms of the GNU Free Documentation License, Version 1.3 or |
| 9639 | 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''. | |
| 4958 | 36 @end quotation |
| 37 @end copying | |
| 38 | |
| 39 @titlepage | |
| 11738 | 40 @title Information for Maintainers of GNU Software |
| 4958 | 41 @author Richard Stallman |
| 42 @author last updated @value{lastupdate} | |
| 43 @page | |
| 44 @vskip 0pt plus 1filll | |
| 45 @insertcopying | |
| 46 @end titlepage | |
| 47 | |
| 48 @contents | |
| 49 | |
| 50 @ifnottex | |
| 51 @node Top | |
| 52 @top Version | |
| 53 | |
| 54 @insertcopying | |
| 55 @end ifnottex | |
| 56 | |
| 57 @menu | |
| 6710 | 58 * Preface:: |
| 13230 | 59 * Getting Help:: |
| 16279 | 60 * GNU Accounts and Resources:: |
| 6710 | 61 * Stepping Down:: |
| 62 * Recruiting Developers:: | |
| 63 * Legal Matters:: | |
| 64 * Clean Ups:: | |
| 65 * Platforms:: | |
| 66 * Mail:: | |
| 67 * Old Versions:: | |
| 68 * Distributions:: | |
| 69 * Web Pages:: | |
| 70 * Ethical and Philosophical Consideration:: | |
| 71 * Terminology:: | |
| 16853 | 72 * Interviews and Speeches:: |
| 6710 | 73 * Hosting:: |
| 13857 | 74 * Donations:: |
| 6710 | 75 * Free Software Directory:: |
| 76 * Using the Proofreaders List:: | |
| 9639 | 77 * GNU Free Documentation License:: |
| 6710 | 78 * Index:: |
| 4958 | 79 @end menu |
| 80 | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
81 |
| 4958 | 82 @node Preface |
| 83 @chapter About This Document | |
| 84 | |
| 85 This file contains guidelines and advice for someone who is the | |
| 86 maintainer of a GNU program on behalf of the GNU Project. Everyone is | |
| 87 entitled to change and redistribute GNU software; you need not pay | |
| 13289 | 88 attention to this file to get permission. But if you want to maintain |
| 89 a version for widespread distribution, we suggest you follow these | |
| 90 guidelines. If you are or would like to be a GNU maintainer, then it | |
| 91 is essential to follow these guidelines. | |
| 4958 | 92 |
| 10299 | 93 In addition to this document, please read and follow the GNU Coding |
| 94 Standards (@pxref{Top, , Contents, standards, GNU Coding Standards}). | |
| 95 | |
| 13056 | 96 @cindex @code{bug-standards@@gnu.org} email address |
| 15518 | 97 @cindex Savannah repository for @code{gnustandards} |
| 98 @cindex @code{gnustandards} project repository | |
| 4958 | 99 Please send corrections or suggestions for this document to |
| 12332 | 100 @email{bug-standards@@gnu.org}. If you make a suggestion, please |
| 13230 | 101 include suggested new wording if you can. We prefer a context diff to |
| 102 the Texinfo source, but if that's difficult for you, you can make a | |
| 13289 | 103 diff for some other version of this document, or propose it in any way |
| 104 that makes it clear. The source repository for this document can be | |
| 105 found at @url{http://savannah.gnu.org/projects/gnustandards}. | |
| 10299 | 106 |
| 13230 | 107 @cindex @code{gnustandards-commit@@gnu.org} mailing list |
| 108 If you want to receive diffs for every change to these GNU documents, | |
| 109 join the mailing list @code{gnustandards-commit@@gnu.org}, for | |
| 110 instance via the web interface at | |
| 111 @url{http://lists.gnu.org/mailman/listinfo/gnustandards-commit}. | |
| 112 Archives are also available there. | |
| 11738 | 113 |
| 114 @cindex Piercy, Marge | |
| 4958 | 115 This document uses the gender-neutral third-person pronouns ``person'', |
| 116 ``per'', ``pers'' and ``perself'' which were promoted, and perhaps | |
| 117 invented, by Marge Piercy in @cite{Woman on the Edge of Time}. They are | |
| 118 used just like ``she'', ``her'', ``hers'' and ``herself'', except that | |
| 119 they apply equally to males and females. For example, ``Person placed | |
| 120 per new program under the GNU GPL, to let the public benefit from per | |
| 121 work, and to enable per to feel person has done the right thing.'' | |
| 122 | |
| 13230 | 123 This release of the GNU Maintainer Information was last updated |
| 4958 | 124 @value{lastupdate}. |
| 125 | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
126 |
| 13230 | 127 @node Getting Help |
| 128 @chapter Getting Help | |
| 129 @cindex help, getting | |
| 130 | |
| 131 @cindex @code{mentors@@gnu.org} mailing list | |
| 14719 | 132 If you have any general questions or encounter a situation where it |
| 133 isn't clear how to get something done or who to ask, you (as a GNU | |
| 134 contributor) can always write to @email{mentors@@gnu.org}, which is a | |
| 135 list of a few experienced GNU folks who have volunteered to answer | |
| 136 questions. Any GNU-related question is fair game for the | |
| 137 @code{mentors} list. | |
| 13230 | 138 |
| 139 @cindex advisory committee | |
| 13276 | 140 The GNU Advisory Committee helps to coordinate activities in the GNU |
| 13786 | 141 project on behalf of RMS (Richard Stallman, the Chief GNUisance). If |
| 142 you have any organizational questions or concerns you can contact the | |
| 143 committee at @email{gnu-advisory@@gnu.org}. See | |
| 144 @url{http://www.gnu.org/contact/gnu-advisory.html} for the current | |
| 145 committee members. Additional information is in | |
| 13230 | 146 @file{/gd/gnuorg/advisory}. |
| 147 | |
| 14719 | 148 @cindex down, when GNU machines are |
| 149 @cindex outage, of GNU machines | |
| 150 @cindex @url{http://identi.ca/group/fsfstatus} | |
| 151 If you find that any GNU computer systems (@code{fencepost.gnu.org}, | |
| 152 @code{ftp.gnu.org}, @code{www.gnu.org}, @code{savannah.gnu.org}, | |
| 153 @dots{}) seem to be down, you can check the current status at | |
| 154 @url{http://identi.ca/group/fsfstatus}. Most likely the problem, if | |
| 155 it can be alleviated at the FSF end, is already being worked on. | |
| 156 | |
| 157 @cindex sysadmin, FSF | |
| 158 @cindex FSF system administrators | |
| 159 @cindex GNU system administrators | |
| 160 The FSF system administrators are responsible for the network and GNU | |
| 161 hardware. You can email them at @email{sysadmin@@fsf.org}, but please | |
| 162 try not to burden them unnecessarily. | |
| 13230 | 163 |
| 164 | |
| 16279 | 165 @node GNU Accounts and Resources |
| 166 @chapter GNU Accounts and Resources | |
| 13276 | 167 @cindex shell account, on fencepost |
| 16279 | 168 @cindex @code{fencepost.gnu.org} GNU login host |
| 169 @cindex resources for GNU developers | |
| 170 @cindex development resources | |
| 13276 | 171 |
| 172 @c We want to repeat this text later, so define a macro. | |
| 173 @macro gdgnuorgtext | |
| 174 The directory @file{/gd/gnuorg} mentioned throughout this document is | |
| 175 available on the general GNU server, currently | |
| 176 @code{fencepost.gnu.org}. If you are the maintainer of a GNU package, | |
| 17328 | 177 you should have an account there. If you don't have one already, see |
| 13276 | 178 @url{http://www.gnu.org/software/README.accounts.html}. You can also |
| 179 ask for accounts for people who significantly help you in working on | |
| 17328 | 180 the package. Such GNU login accounts include email |
| 181 (see @url{http://www.fsf.org/about/systems/sending-mail-via-fencepost}). | |
| 13276 | 182 @end macro |
| 183 | |
| 13440 | 184 @gdgnuorgtext{} |
| 13276 | 185 |
| 16279 | 186 Other resources available to GNU maintainers are described at |
| 187 @url{http://www.gnu.org/software/devel.html}, as well as throughout | |
| 188 this document. In brief: | |
| 189 | |
| 190 @itemize @bullet | |
| 191 @item Login accounts (see above). | |
| 192 | |
| 193 @item Version control (@pxref{Old Versions}). | |
| 194 | |
| 195 @item Mailing lists (@pxref{Mail}). | |
| 196 | |
| 197 @item Web pages (@pxref{Web Pages}). | |
| 198 | |
| 199 @item Mirrored release areas (@pxref{Distributions}). | |
| 200 | |
| 201 @cindex Hydra | |
| 202 @cindex @code{platform-testers} mailing list | |
| 203 @item Pre-release portability testing, both automated (via Hydra) and | |
| 204 on request (via volunteers). | |
| 205 | |
| 206 @end itemize | |
| 207 | |
| 13276 | 208 |
| 4958 | 209 @node Stepping Down |
| 210 @chapter Stepping Down | |
| 13230 | 211 @cindex stepping down as maintainer |
| 212 @cindex resigning as maintainer | |
| 4958 | 213 |
| 214 With good fortune, you will continue maintaining your package for many | |
| 215 decades. But sometimes for various reasons maintainers decide to step | |
| 216 down. | |
| 217 | |
| 218 If you're the official maintainer of a GNU package and you decide to | |
| 219 step down, please inform the GNU Project (@email{maintainers@@gnu.org}). | |
| 220 We need to know that the package no longer has a maintainer, so we can | |
| 221 look for and appoint a new maintainer. | |
| 222 | |
| 13230 | 223 @cindex @email{maintainers@@gnu.org} |
| 4958 | 224 If you have an idea for who should take over, please tell |
| 225 @email{maintainers@@gnu.org} your suggestion. The appointment of a new | |
| 226 maintainer needs the GNU Project's confirmation, but your judgment that | |
| 227 a person is capable of doing the job will carry a lot of weight. | |
| 228 | |
| 15518 | 229 As your final act as maintainer, it would be helpful to set up or |
| 230 update the package under @code{savannah.gnu.org} (@pxref{Old | |
| 231 Versions}). This will make it much easier for the new maintainer to | |
| 232 pick up where you left off and will ensure that the source tree is not | |
| 233 misplaced if it takes us a while to find a new maintainer. | |
| 4958 | 234 |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
235 |
| 4958 | 236 @node Recruiting Developers |
| 237 @chapter Recruiting Developers | |
| 238 | |
| 239 Unless your package is a fairly small, you probably won't do all the | |
| 240 work on it yourself. Most maintainers recruit other developers to help. | |
| 241 | |
| 242 Sometimes people will offer to help. Some of them will be capable, | |
| 243 while others will not. It's up to you to determine who provides useful | |
| 244 help, and encourage those people to participate more. | |
| 245 | |
| 246 Some of the people who offer to help will support the GNU Project, while | |
| 247 others may be interested for other reasons. Some will support the goals | |
| 248 of the Free Software Movement, but some may not. They are all welcome | |
| 249 to help with the work---we don't ask people's views or motivations | |
| 250 before they contribute to GNU packages. | |
| 251 | |
| 252 As a consequence, you cannot expect all contributors to support the GNU | |
| 253 Project, or to have a concern for its policies and standards. So part | |
| 254 of your job as maintainer is to exercise your authority on these points | |
| 255 when they arise. No matter how much of the work other people do, you | |
| 256 are in charge of what goes in the release. When a crucial point arises, | |
| 257 you should calmly state your decision and stick to it. | |
| 258 | |
| 259 Sometimes a package has several co-maintainers who share the role of | |
| 260 maintainer. Unlike developers who help, co-maintainers have actually | |
| 261 been appointed jointly as the maintainers of the package, and they carry | |
| 262 out the maintainer's functions together. If you would like to propose | |
| 263 some of your developers as co-maintainers, please contact | |
| 264 @email{maintainers@@gnu.org}. | |
| 265 | |
| 10299 | 266 We're happy to acknowledge all major contributors to GNU packages on |
| 267 the @url{http://www.gnu.org/people/people.html} web page. Please send | |
| 268 an entry for yourself to @email{webmasters@@gnu.org}, and feel free to | |
| 269 suggest it to other significant developers on your package. | |
| 270 | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
271 |
| 4958 | 272 @node Legal Matters |
| 273 @chapter Legal Matters | |
| 274 @cindex legal matters | |
| 275 | |
| 276 This chapter describes procedures you should follow for legal reasons | |
| 277 as you maintain the program, to avoid legal difficulties. | |
| 278 | |
| 279 @menu | |
| 6710 | 280 * Copyright Papers:: |
| 4958 | 281 * Legally Significant:: |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
282 * Recording Contributors:: |
| 7465 | 283 * Copying from Other Packages:: |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
284 * Copyright Notices:: |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
285 * License Notices:: |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
286 * External Libraries:: |
| 4958 | 287 @end menu |
| 288 | |
| 289 @node Copyright Papers | |
| 290 @section Copyright Papers | |
| 291 @cindex copyright papers | |
| 16773 | 292 @cindex assignments, copyright |
| 293 @cindex disclaimers | |
| 4958 | 294 |
| 295 If you maintain an FSF-copyrighted package | |
|
5495
5fe0551f4ec2
update from gnustandards
Karl Berry <karl@freefriends.org>
parents:
5325
diff
changeset
|
296 certain legal procedures are required when incorporating legally significant |
| 4958 | 297 changes written by other people. This ensures that the FSF has the |
| 298 legal right to distribute the package, and the standing to defend its | |
| 299 GPL-covered status in court if necessary. | |
| 300 | |
| 301 @strong{Before} incorporating significant changes, make sure that the | |
| 302 person who wrote the changes has signed copyright papers and that the | |
| 16782 | 303 Free Software Foundation has received and signed them. We may also |
| 304 need an employer's disclaimer from the person's employer, which | |
| 305 confirms that the work was not part of the person's job and the | |
| 306 employer makes no claim on it. However, a copy of the person's | |
| 307 employment contract, showing that the employer can't claim any rights | |
| 308 to this work, is often sufficient. | |
| 309 | |
| 310 If the employer does claim the work was part of the person's job, and | |
| 311 there is no clear basis to say that claim is invalid, then we have to | |
| 312 consider it valid. Then the person cannot assign copyright, but the | |
| 313 employer can. Many companies have done this. Please ask the | |
| 314 appropriate managers to contact @code{assign@@gnu.org}. | |
| 4958 | 315 |
| 316 @cindex data base of GNU copyright assignments | |
| 317 To check whether papers have been received, look in | |
| 318 @file{/gd/gnuorg/copyright.list}. If you can't look there directly, | |
| 319 @email{fsf-records@@gnu.org} can check for you. Our clerk can also | |
| 320 check for papers that are waiting to be entered and inform you when | |
| 321 expected papers arrive. | |
| 322 | |
| 323 @cindex @file{/gd/gnuorg} directory | |
| 324 @c This paragraph intentionally duplicates information given | |
| 325 @c near the beginning of the file--to make sure people don't miss it. | |
| 13440 | 326 @gdgnuorgtext{} |
| 4958 | 327 |
| 328 In order for the contributor to know person should sign papers, you need | |
| 9792 | 329 to ask per for the necessary papers. If you don't know per well, and you |
| 4958 | 330 don't know that person is used to our ways of handling copyright papers, |
| 331 then it might be a good idea to raise the subject with a message like | |
| 332 this: | |
| 333 | |
| 334 @quotation | |
| 335 Would you be willing to assign the copyright to the Free Software | |
| 14172 | 336 Foundation, so that we could install it in @var{package}? |
| 4958 | 337 @end quotation |
| 338 | |
| 339 @noindent | |
| 340 or | |
| 341 | |
| 342 @quotation | |
| 343 Would you be willing to sign a copyright disclaimer to put this change | |
| 14172 | 344 in the public domain, so that we can install it in @var{package}? |
| 4958 | 345 @end quotation |
| 346 | |
| 13230 | 347 If the contributor then wants more information, you can send per the file |
| 4958 | 348 @file{/gd/gnuorg/conditions.text}, which explains per options (assign |
| 349 vs.@: disclaim) and their consequences. | |
| 350 | |
| 351 Once the conversation is under way and the contributor is ready for | |
| 352 more details, you should send one of the templates that are found in | |
| 6698 | 353 the directory @file{/gd/gnuorg/Copyright/}; they are also available |
| 354 from the @file{doc/Copyright/} directory of the @code{gnulib} project | |
| 355 at @url{http://savannah.gnu.org/projects/gnulib}. This section | |
| 356 explains which templates you should use in which circumstances. | |
| 357 @strong{Please don't use any of the templates except for those listed | |
| 358 here, and please don't change the wording.} | |
| 4958 | 359 |
| 360 Once the conversation is under way, you can send the contributor the | |
| 361 precise wording and instructions by email. Before you do this, make | |
| 362 sure to get the current version of the template you will use! We change | |
| 363 these templates occasionally---don't keep using an old version. | |
| 364 | |
| 365 For large changes, ask the contributor for an assignment. Send per a | |
| 366 copy of the file @file{request-assign.changes}. (Like all the | |
| 6698 | 367 @samp{request-} files, it is in @file{/gd/gnuorg/Copyright} and in |
| 368 @code{gnulib}.) | |
| 4958 | 369 |
| 9704 | 370 For medium to small changes, request a personal disclaimer by sending |
| 371 per the file @file{request-disclaim.changes}. | |
| 4958 | 372 |
| 373 If the contributor is likely to keep making changes, person might want | |
| 374 to sign an assignment for all per future changes to the program. So it | |
| 375 is useful to offer per that alternative. If person wants to do it that | |
| 376 way, send per the @file{request-assign.future}. | |
| 377 | |
| 378 When you send a @file{request-} file, you don't need to fill in anything | |
| 379 before sending it. Just send the file verbatim to the contributor. The | |
| 380 file gives per instructions for how to ask the FSF to mail per the | |
| 381 papers to sign. The @file{request-} file also raises the issue of | |
| 9704 | 382 getting an employer's disclaimer from the contributor's employer. |
| 4958 | 383 |
| 15948 | 384 When the contributor emails the form to the FSF, the FSF sends per an |
| 16773 | 385 electronic (usually PDF) copy of the assignment. This, or whatever |
| 386 response is required, should happen within five business days of the | |
| 16853 | 387 initial request. If no reply from the FSF comes after that time, |
| 388 please send a reminder. If you still get no response after an | |
| 389 additional week, please write to @email{maintainers@@gnu.org} about it. | |
| 16773 | 390 |
| 391 After receiving the necessary form, all contributors then print it and | |
| 17159 | 392 sign it. Contributors located in the USA or Germany can then email or |
| 393 fax a scanned copy back to the FSF (or use postal mail, if they | |
| 394 prefer). Contributors residing outside the USA or Germany must mail | |
| 395 the signed form to the FSF via postal mail. To emphasize, the | |
| 396 necessary distinction is between residents and non-residents of these | |
| 397 countries; citizenship does not matter. | |
| 5568 | 398 |
| 4958 | 399 For less common cases, we have template files you should send to the |
| 400 contributor. Be sure to fill in the name of the person and the name | |
| 401 of the program in these templates, where it says @samp{NAME OF PERSON} | |
| 402 and @samp{NAME OF PROGRAM}, before sending; otherwise person might | |
| 403 sign without noticing them, and the papers would be useless. Note | |
| 404 that in some templates there is more than one place to put the name of | |
| 405 the program or the name of the person; be sure to change all of them. | |
| 406 All the templates raise the issue of an employer's disclaimer as well. | |
| 407 | |
| 408 @cindex legal papers for changes in manuals | |
| 409 You do not need to ask for separate papers for a manual that is | |
| 410 distributed only in the software package it describes. But if we | |
| 411 sometimes distribute the manual separately (for instance, if we publish | |
| 412 it as a book), then we need separate legal papers for changes in the | |
| 413 manual. For smaller changes, use | |
| 414 @file{disclaim.changes.manual}; for larger ones, use | |
| 415 @file{assign.changes.manual}. To cover both past and future | |
| 416 changes to a manual, you can use @file{assign.future.manual}. | |
| 5325 | 417 For a translation of a manual, use @file{assign.translation.manual}. |
| 4958 | 418 |
| 9797 | 419 For translations of program strings (as used by GNU Gettext, for |
| 14172 | 420 example; @pxref{Internationalization,,, standards, GNU Coding |
| 9797 | 421 Standards}), use @file{disclaim.translation}. If you make use of the |
| 422 Translation Project (@url{http://translationproject.org}) facilities, | |
| 423 please check with the TP coordinators that they have sent the | |
| 424 contributor the papers; if they haven't, then you should send the | |
| 425 papers. In any case, you should wait for the confirmation from the | |
| 426 FSF that the signed papers have been received and accepted before | |
| 427 integrating the new contributor's material, as usual. | |
|
11480
43db6feede26
remove trailing whitespace to placate Jim, more license syncs
Karl Berry <karl@freefriends.org>
parents:
11396
diff
changeset
|
428 |
| 4958 | 429 If a contributor is reluctant to sign an assignment for a large change, |
| 430 and is willing to sign a disclaimer instead, that is acceptable, so you | |
| 431 should offer this alternative if it helps you reach agreement. We | |
| 432 prefer an assignment for a larger change, so that we can enforce the GNU | |
| 433 GPL for the new text, but a disclaimer is enough to let us use the text. | |
| 434 | |
| 435 If you maintain a collection of programs, occasionally someone will | |
| 436 contribute an entire separate program or manual that should be added to | |
| 437 the collection. Then you can use the files | |
| 438 @file{request-assign.program}, @file{disclaim.program}, | |
| 439 @file{assign.manual}, and @file{disclaim.manual}. We very much prefer | |
| 440 an assignment for a new separate program or manual, unless it is quite | |
| 441 small, but a disclaimer is acceptable if the contributor insists on | |
| 442 handling the matter that way. | |
| 443 | |
| 444 If a contributor wants the FSF to publish only a pseudonym, that is | |
| 445 ok. The contributor should say this, and state the desired pseudonym, | |
| 446 when answering the @file{request-} form. The actual legal papers will | |
| 447 use the real name, but the FSF will publish only the pseudonym. When | |
| 448 using one of the other forms, fill in the real name but ask the | |
| 449 contributor to discuss the use of a pseudonym with | |
| 450 @email{assign@@gnu.org} before sending back the signed form. | |
| 451 | |
| 452 @strong{Although there are other templates besides the ones listed here, | |
| 453 they are for special circumstances; please do not use them without | |
| 454 getting advice from @email{assign@@gnu.org}.} | |
| 455 | |
| 456 If you are not sure what to do, then please ask @email{assign@@gnu.org} for | |
| 457 advice; if the contributor asks you questions about the meaning and | |
| 458 consequences of the legal papers, and you don't know the answers, you | |
| 459 can forward them to @email{assign@@gnu.org} and we will answer. | |
| 460 | |
| 461 @strong{Please do not try changing the wording of a template yourself. | |
| 462 If you think a change is needed, please talk with @email{assign@@gnu.org}, | |
| 463 and we will work with a lawyer to decide what to do.} | |
| 464 | |
| 465 @node Legally Significant | |
| 466 @section Legally Significant Changes | |
| 467 | |
| 468 If a person contributes more than around 15 lines of code and/or text | |
| 9792 | 469 that is legally significant for copyright purposes, we |
| 470 need copyright papers for that contribution, as described above. | |
| 4958 | 471 |
| 472 A change of just a few lines (less than 15 or so) is not legally | |
| 473 significant for copyright. A regular series of repeated changes, such | |
| 474 as renaming a symbol, is not legally significant even if the symbol | |
| 475 has to be renamed in many places. Keep in mind, however, that a | |
| 476 series of minor changes by the same person can add up to a significant | |
| 477 contribution. What counts is the total contribution of the person; it | |
| 478 is irrelevant which parts of it were contributed when. | |
| 479 | |
| 480 Copyright does not cover ideas. If someone contributes ideas but no | |
| 481 text, these ideas may be morally significant as contributions, and | |
| 482 worth giving credit for, but they are not significant for copyright | |
| 483 purposes. Likewise, bug reports do not count for copyright purposes. | |
| 484 | |
| 485 When giving credit to people whose contributions are not legally | |
| 486 significant for copyright purposes, be careful to make that fact | |
| 487 clear. The credit should clearly say they did not contribute | |
| 488 significant code or text. | |
| 489 | |
| 490 When people's contributions are not legally significant because they | |
| 491 did not write code, do this by stating clearly what their contribution | |
| 492 was. For instance, you could write this: | |
| 493 | |
| 494 @example | |
| 495 /* | |
| 496 * Ideas by: | |
| 497 * Richard Mlynarik <mly@@adoc.xerox.com> (1997) | |
| 498 * Masatake Yamato <masata-y@@is.aist-nara.ac.jp> (1999) | |
| 499 */ | |
| 500 @end example | |
| 501 | |
| 502 @noindent | |
| 503 @code{Ideas by:} makes it clear that Mlynarik and Yamato here | |
| 504 contributed only ideas, not code. Without the @code{Ideas by:} note, | |
| 505 several years from now we would find it hard to be sure whether they | |
| 506 had contributed code, and we might have to track them down and ask | |
| 507 them. | |
| 508 | |
| 509 When you record a small patch in a change log file, first search for | |
| 9554 | 510 previous changes by the same person, and see if per past |
| 4958 | 511 contributions, plus the new one, add up to something legally |
| 9554 | 512 significant. If so, you should get copyright papers for all per |
| 4958 | 513 changes before you install the new change. |
| 514 | |
| 515 If that is not so, you can install the small patch. Write @samp{(tiny | |
| 516 change)} after the patch author's name, like this: | |
| 517 | |
| 518 @example | |
| 519 2002-11-04 Robert Fenk <Robert.Fenk@@gmx.de> (tiny change) | |
| 520 @end example | |
| 521 | |
| 522 @node Recording Contributors | |
| 523 @section Recording Contributors | |
| 524 @cindex recording contributors | |
| 525 | |
| 526 @strong{Keep correct records of which portions were written by whom.} | |
| 9792 | 527 This is very important. These records should say which files or |
| 528 parts of files were written by each person, and which files or | |
| 529 parts of files were revised by each person. This should include | |
| 4958 | 530 installation scripts as well as manuals and documentation |
| 531 files---everything. | |
| 532 | |
| 533 These records don't need to be as detailed as a change log. They | |
| 534 don't need to distinguish work done at different times, only different | |
| 535 people. They don't need describe changes in more detail than which | |
| 536 files or parts of a file were changed. And they don't need to say | |
| 13230 | 537 anything about the function or purpose of a file or change---the |
| 4958 | 538 Register of Copyrights doesn't care what the text does, just who wrote |
| 539 or contributed to which parts. | |
| 540 | |
| 541 The list should also mention if certain files distributed in the same | |
| 542 package are really a separate program. | |
| 543 | |
| 544 Only the contributions that are legally significant for copyright | |
| 545 purposes (@pxref{Legally Significant}) need to be listed. Small | |
| 7465 | 546 contributions, bug reports, ideas, etc., can be omitted. |
| 4958 | 547 |
| 548 For example, this would describe an early version of GAS: | |
| 549 | |
| 550 @display | |
| 551 Dean Elsner first version of all files except gdb-lines.c and m68k.c. | |
| 552 Jay Fenlason entire files gdb-lines.c and m68k.c, most of app.c, | |
| 553 plus extensive changes in messages.c, input-file.c, write.c | |
| 554 and revisions elsewhere. | |
| 555 | |
| 556 Note: GAS is distributed with the files obstack.c and obstack.h, but | |
| 557 they are considered a separate package, not part of GAS proper. | |
| 558 @end display | |
| 559 | |
| 560 @cindex @file{AUTHORS} file | |
| 561 Please keep these records in a file named @file{AUTHORS} in the source | |
| 562 directory for the program itself. | |
| 563 | |
| 7465 | 564 You can use the change log as the basis for these records, if you |
| 565 wish. Just make sure to record the correct author for each change | |
| 566 (the person who wrote the change, @emph{not} the person who installed | |
| 567 it), and add @samp{(tiny change)} for those changes that are too | |
| 568 trivial to matter for copyright purposes. Later on you can update the | |
| 569 @file{AUTHORS} file from the change log. This can even be done | |
| 570 automatically, if you are careful about the formatting of the change | |
| 571 log entries. | |
| 572 | |
| 16158 | 573 It is ok to include other email addresses, names, and program |
| 574 information in @file{AUTHORS}, such as bug-reporting information. | |
| 575 @xref{Standard Mailing Lists}. | |
| 576 | |
| 577 | |
| 7465 | 578 @node Copying from Other Packages |
| 579 @section Copying from Other Packages | |
| 580 | |
| 16782 | 581 This section explains legal considerations when merging code from |
| 582 other packages into your package. Using an entire module as a whole, | |
| 583 and maintaining its separate identity, is a different issue; | |
| 584 see @ref{External Libraries}. | |
| 585 | |
| 586 @menu | |
| 587 * Non-FSF-Copyrighted Package:: | |
| 588 * FSF-Copyrighted Package:: | |
| 589 @end menu | |
| 590 | |
| 591 @node Non-FSF-Copyrighted Package | |
| 592 @subsection Non-FSF-Copyrighted Package | |
| 593 | |
| 594 Here we suppose that your package is not FSF-copyrighted. | |
| 595 | |
| 7465 | 596 When you copy legally significant code from another free software |
| 597 package with a GPL-compatible license, you should look in the | |
| 598 package's records to find out the authors of the part you are copying, | |
| 599 and list them as the contributors of the code that you copied. If all | |
| 600 you did was copy it, not write it, then for copyright purposes you are | |
| 601 @emph{not} one of the contributors of @emph{this} code. | |
| 602 | |
| 16782 | 603 If the code is supposed to be in the public domain, make sure that is |
| 604 really true: that all the authors of the code have disclaimed | |
| 605 copyright interest. Then, when copying the new files into your | |
| 606 project, add a brief note at the beginning of the files recording the | |
| 607 authors, the public domain status, and anything else relevant. | |
| 8867 | 608 |
| 609 On the other hand, when merging some public domain code into an | |
| 610 existing file covered by the GPL (or LGPL or other free software | |
| 611 license), there is no reason to indicate the pieces which are public | |
| 612 domain. The notice saying that the whole file is under the GPL (or | |
| 613 other license) is legally sufficient. | |
| 614 | |
| 16782 | 615 Using code that is not in the public domain, but rather released under |
| 616 a GPL-compatible free license, may require preserving copyright | |
| 617 notices or other steps. Of course, you should follow the requirements | |
| 618 stated. | |
| 619 | |
| 620 @node FSF-Copyrighted Package | |
| 621 @subsection FSF-Copyrighted Package | |
| 622 | |
| 623 If you are maintaining an FSF-copyrighted package, please don't copy | |
| 624 in any code without verifying first that we have suitable legal papers | |
| 625 for that code. | |
| 626 | |
| 7465 | 627 If you are copying from another FSF-copyrighted package, then we |
| 628 presumably have papers for that package's own code, but you must check | |
| 629 whether the code you are copying is part of an external library; if | |
| 630 that is the case, we don't have papers for it, so you should not copy | |
| 631 it. It can't hurt in any case to double-check with the developer of | |
| 632 that package. | |
| 633 | |
| 634 When you are copying code for which we do not already have papers, you | |
| 635 need to get papers for it. It may be difficult to get the papers if | |
| 636 the code was not written as a contribution to your package, but that | |
| 637 doesn't mean it is ok to do without them. If you cannot get papers | |
| 638 for the code, you can only use it as an external library | |
| 639 (@pxref{External Libraries}). | |
|
6470
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
640 |
| 8867 | 641 |
| 4958 | 642 @node Copyright Notices |
| 643 @section Copyright Notices | |
| 644 @cindex copyright notices in program files | |
| 645 | |
|
6482
c5451290271b
update notices in all files at once
Karl Berry <karl@freefriends.org>
parents:
6470
diff
changeset
|
646 You should maintain a proper copyright notice and a license |
|
c5451290271b
update notices in all files at once
Karl Berry <karl@freefriends.org>
parents:
6470
diff
changeset
|
647 notice in each nontrivial file in the package. (Any file more than ten |
|
c5451290271b
update notices in all files at once
Karl Berry <karl@freefriends.org>
parents:
6470
diff
changeset
|
648 lines long is nontrivial for this purpose.) This includes header files |
|
c5451290271b
update notices in all files at once
Karl Berry <karl@freefriends.org>
parents:
6470
diff
changeset
|
649 and interface definitions for |
|
c5451290271b
update notices in all files at once
Karl Berry <karl@freefriends.org>
parents:
6470
diff
changeset
|
650 building or running the program, documentation files, and any supporting |
|
c5451290271b
update notices in all files at once
Karl Berry <karl@freefriends.org>
parents:
6470
diff
changeset
|
651 files. If a file has been explicitly placed in the public domain, then |
|
c5451290271b
update notices in all files at once
Karl Berry <karl@freefriends.org>
parents:
6470
diff
changeset
|
652 instead of a copyright notice, it should have a notice saying explicitly |
|
c5451290271b
update notices in all files at once
Karl Berry <karl@freefriends.org>
parents:
6470
diff
changeset
|
653 that it is in the public domain. |
| 4958 | 654 |
| 655 Even image files and sound files should contain copyright notices and | |
| 11605 | 656 license notices, if their format permits. Some formats do not have |
| 657 room for textual annotations; for these files, state the copyright and | |
| 658 copying permissions in a @file{README} file in the same directory. | |
| 4958 | 659 |
| 660 Change log files should have a copyright notice and license notice at | |
| 661 the end, since new material is added at the beginning but the end | |
| 662 remains the end. | |
| 663 | |
| 664 When a file is automatically generated from some other file in the | |
|
6470
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
665 distribution, it is useful for the automatic procedure to copy the |
|
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
666 copyright notice and permission notice of the file it is generated |
|
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
667 from, if possible. Alternatively, put a notice at the beginning saying |
|
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
668 which file it is generated from. |
| 4958 | 669 |
| 670 A copyright notice looks like this: | |
| 671 | |
| 672 @example | |
| 12836 | 673 Copyright (C) @var{year1}, @var{year2}, @var{year3} @var{copyright-holder} |
| 4958 | 674 @end example |
| 675 | |
| 12836 | 676 The word @samp{Copyright} must always be in English, by international |
| 677 convention. | |
| 678 | |
| 4958 | 679 The @var{copyright-holder} may be the Free Software Foundation, Inc., or |
| 680 someone else; you should know who is the copyright holder for your | |
| 681 package. | |
| 682 | |
| 683 Replace the @samp{(C)} with a C-in-a-circle symbol if it is available. | |
| 684 For example, use @samp{@@copyright@{@}} in a Texinfo file. However, | |
| 685 stick with parenthesized @samp{C} unless you know that C-in-a-circle | |
| 686 will work. For example, a program's standard @option{--version} | |
| 687 message should use parenthesized @samp{C} by default, though message | |
| 688 translations may use C-in-a-circle in locales where that symbol is | |
| 12836 | 689 known to work. Alternatively, the @samp{(C)} or C-in-a-circle can be |
| 690 omitted entirely; the word @samp{Copyright} suffices. | |
| 4958 | 691 |
|
6482
c5451290271b
update notices in all files at once
Karl Berry <karl@freefriends.org>
parents:
6470
diff
changeset
|
692 To update the list of year numbers, add each year in which you have |
|
c5451290271b
update notices in all files at once
Karl Berry <karl@freefriends.org>
parents:
6470
diff
changeset
|
693 made nontrivial changes to the package. (Here we assume you're using |
|
c5451290271b
update notices in all files at once
Karl Berry <karl@freefriends.org>
parents:
6470
diff
changeset
|
694 a publicly accessible revision control server, so that every revision |
| 6503 | 695 installed is also immediately and automatically published.) When you |
| 9812 | 696 add the new year, it is not required to keep track of which files have |
| 6503 | 697 seen significant changes in the new year and which have not. It is |
| 698 recommended and simpler to add the new year to all files in the | |
| 699 package, and be done with it for the rest of the year. | |
| 700 | |
| 9792 | 701 Don't delete old year numbers, though; they are significant since they |
| 702 indicate when older versions might theoretically go into the public | |
| 703 domain, if the movie companies don't continue buying laws to further | |
| 704 extend copyright. If you copy a file into the package from some other | |
| 705 program, keep the copyright years that come with the file. | |
| 4958 | 706 |
| 13829 | 707 You can use a range (@samp{2008-2010}) instead of listing individual |
| 708 years (@samp{2008, 2009, 2010}) if and only if: 1)@tie{}every year in | |
| 709 the range, inclusive, really is a ``copyrightable'' year that would be | |
| 710 listed individually; @emph{and} 2)@tie{}you make an explicit statement | |
| 711 in a @file{README} file about this usage. | |
| 4958 | 712 |
| 9792 | 713 For files which are regularly copied from another project (such as |
| 714 @samp{gnulib}), leave the copyright notice as it is in the original. | |
| 715 | |
| 6498 | 716 The copyright statement may be split across multiple lines, both in |
| 717 source files and in any generated output. This often happens for | |
| 718 files with a long history, having many different years of | |
| 719 publication. | |
| 720 | |
| 4958 | 721 For an FSF-copyrighted package, if you have followed the procedures to |
| 722 obtain legal papers, each file should have just one copyright holder: | |
| 5325 | 723 the Free Software Foundation, Inc. You should edit the file's |
| 724 copyright notice to list that name and only that name. | |
| 4958 | 725 |
| 726 But if contributors are not all assigning their copyrights to a single | |
| 727 copyright holder, it can easily happen that one file has several | |
|
6470
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
728 copyright holders. Each contributor of nontrivial text is a copyright |
|
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
729 holder. |
| 4958 | 730 |
| 731 In that case, you should always include a copyright notice in the name | |
| 732 of main copyright holder of the file. You can also include copyright | |
|
6470
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
733 notices for other copyright holders as well, and this is a good idea |
|
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
734 for those who have contributed a large amount and for those who |
|
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
735 specifically ask for notices in their names. (Sometimes the license |
|
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
736 on code that you copy in may require preserving certain copyright |
|
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
737 notices.) But you don't have to include a notice for everyone who |
|
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
738 contributed to the file (which would be rather inconvenient). |
|
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
739 |
|
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
740 Sometimes a program has an overall copyright notice that refers to the |
|
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
741 whole program. It might be in the @file{README} file, or it might be |
|
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
742 displayed when the program starts up. This copyright notice should |
|
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
743 mention the year of completion of the most recent major version; it |
|
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
744 can mention years of completion of previous major versions, but that |
|
6482
c5451290271b
update notices in all files at once
Karl Berry <karl@freefriends.org>
parents:
6470
diff
changeset
|
745 is optional. |
|
6470
cfd1116d819e
Copyright Notices simplification
Karl Berry <karl@freefriends.org>
parents:
5837
diff
changeset
|
746 |
| 4958 | 747 |
| 748 @node License Notices | |
| 749 @section License Notices | |
| 750 @cindex license notices in program files | |
| 751 | |
| 752 Every nontrivial file needs a license notice as well as the copyright | |
| 9085 | 753 notice. (Without a license notice giving permission to copy and |
| 754 change the file, the file is non-free.) | |
| 755 | |
| 10775 | 756 The package itself should contain a full copy of GPL in plain text |
| 757 (conventionally in a file named @file{COPYING}) and the GNU Free | |
| 758 Documentation License (included within your documentation, so there is | |
| 759 no need for a separate plain text version). If the package contains | |
| 760 any files distributed under the Lesser GPL, it should contain a full | |
| 761 copy of its plain text version also (conventionally in a file named | |
| 9085 | 762 @file{COPYING.LESSER}). |
| 4958 | 763 |
| 14172 | 764 If you have questions about licensing issues for your GNU package, |
| 9554 | 765 please write @email{licensing@@gnu.org}. |
| 766 | |
| 9085 | 767 @menu |
| 14172 | 768 * Which: Licensing of GNU Packages. |
| 769 * Canonical: Canonical License Sources. | |
| 770 * Code: License Notices for Code. | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
771 * Documentation: License Notices for Documentation. |
| 14172 | 772 * Other: License Notices for Other Files. |
| 9085 | 773 @end menu |
| 4958 | 774 |
| 9085 | 775 |
| 14172 | 776 @node Licensing of GNU Packages |
| 777 @subsection Licensing of GNU Packages | |
| 778 | |
| 779 Normally, GNU packages should use the latest version of the GNU GPL, | |
| 780 with the ``or any later version'' formulation. @xref{License Notices | |
| 781 for Code}, for the exact wording of the license notice. | |
| 782 | |
| 783 Occasionally, a GNU library may provide functionality which is already | |
| 784 widely available to proprietary programs through alternative | |
| 785 implementations; for example, the GNU C Library. In such cases, the | |
| 786 Lesser GPL should be used (again, for the notice wording, | |
| 787 @pxref{License Notices for Code}). If a GNU library provides unique | |
| 788 functionality, however, the GNU GPL should be used. | |
| 789 @url{http://www.gnu.org/licenses/why-not-lgpl.html} discusses this | |
| 790 strategic choice. | |
| 791 | |
| 792 Some of these libraries need to work with programs released under | |
| 793 GPLv2-only; that is, which allow the GNU GPL version 2 but not later | |
| 794 versions. In this case, the GNU package should be released under a | |
| 795 dual license: GNU GPL version 2 (or any later version) and the GNU | |
| 796 Lesser GPL version 3 (or any later version). Here is the notice for | |
| 797 that case: | |
| 798 | |
| 799 @smallexample | |
| 800 This file is part of GNU @var{package}. | |
| 801 | |
| 802 GNU @var{package} is free software: you can redistribute it and/or | |
| 803 modify it under the terms of either: | |
| 804 | |
| 805 * the GNU Lesser General Public License as published by the Free | |
| 806 Software Foundation; either version 3 of the License, or (at your | |
| 807 option) any later version. | |
| 808 | |
| 809 or | |
| 810 | |
| 811 * the GNU General Public License as published by the Free | |
| 812 Software Foundation; either version 2 of the License, or (at your | |
| 813 option) any later version. | |
| 814 | |
| 815 or both in parallel, as here. | |
| 816 | |
| 817 GNU @var{package} is distributed in the hope that it will be useful, | |
| 818 but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 819 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
| 820 General Public License for more details. | |
| 821 | |
| 822 You should have received copies of the GNU General Public License and | |
| 823 the GNU Lesser General Public License along with this program. If | |
| 824 not, see @url{http://www.gnu.org/licenses/}. | |
| 825 @end smallexample | |
| 826 | |
| 827 For small packages, you can use ``This program'' instead of ``GNU | |
| 828 @var{package}''. | |
| 829 | |
| 830 | |
| 9085 | 831 @node Canonical License Sources |
| 832 @subsection Canonical License Sources | |
| 833 | |
| 834 You can get the official versions of these files from several places. | |
| 4958 | 835 You can use whichever is the most convenient for you. |
| 836 | |
| 837 @itemize @bullet | |
| 838 @item | |
| 839 @uref{http://www.gnu.org/licenses/}. | |
| 840 | |
| 841 @item | |
| 842 The @code{gnulib} project on @code{savannah.gnu.org}, which you | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
843 can access via anonymous Git or CVS. See |
| 4958 | 844 @uref{http://savannah.gnu.org/projects/gnulib}. |
| 845 | |
| 846 @end itemize | |
| 847 | |
| 848 The official Texinfo sources for the licenses are also available in | |
| 849 those same places, so you can include them in your documentation. A | |
| 9085 | 850 GFDL-covered manual should include the GFDL in this way. @xref{GNU |
| 14172 | 851 Sample Texts,,, texinfo, Texinfo}, for a full example in a Texinfo |
| 9085 | 852 manual. |
| 853 | |
| 854 | |
| 855 @node License Notices for Code | |
| 856 @subsection License Notices for Code | |
| 4958 | 857 |
| 858 Typically the license notice for program files (including build scripts, | |
| 859 configure files and makefiles) should cite the GPL, like this: | |
| 860 | |
| 861 @quotation | |
| 14172 | 862 This file is part of GNU @var{package}. |
| 863 | |
| 864 GNU @var{package} is free software: you can redistribute it and/or | |
| 9124 | 865 modify it under the terms of the GNU General Public License as |
| 9125 | 866 published by the Free Software Foundation, either version 3 of the |
| 9124 | 867 License, or (at your option) any later version. |
| 4958 | 868 |
| 14172 | 869 GNU @var{package} is distributed in the hope that it will be useful, |
| 4958 | 870 but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 871 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
| 872 GNU General Public License for more details. | |
| 873 | |
| 874 You should have received a copy of the GNU General Public License | |
| 9124 | 875 along with this program. If not, see @url{http://www.gnu.org/licenses/}. |
| 4958 | 876 @end quotation |
| 877 | |
| 878 But in a small program which is just a few files, you can use | |
| 879 this instead: | |
| 880 | |
| 881 @quotation | |
| 9124 | 882 This program is free software: you can redistribute it and/or modify |
| 4958 | 883 it under the terms of the GNU General Public License as published by |
| 9085 | 884 the Free Software Foundation; either version 3 of the License, or |
| 4958 | 885 (at your option) any later version. |
| 886 | |
| 887 This program is distributed in the hope that it will be useful, | |
| 888 but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 889 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
| 890 GNU General Public License for more details. | |
| 891 | |
| 9085 | 892 You should have received a copy of the GNU General Public License |
| 9124 | 893 along with this program. If not, see @url{http://www.gnu.org/licenses/}. |
| 4958 | 894 @end quotation |
| 895 | |
| 14172 | 896 In either case, for those few packages which use the Lesser GPL |
| 897 (@pxref{Licensing of GNU Packages}), insert the word ``Lesser'' before | |
| 898 ``General'' in @emph{all three} places. | |
| 899 @url{http://@/www.gnu.org/@/licenses/@/gpl-howto.html} discusses application | |
| 900 the GPL in more detail. | |
| 901 | |
| 9085 | 902 |
| 903 @node License Notices for Documentation | |
| 904 @subsection License Notices for Documentation | |
| 905 | |
| 4958 | 906 Documentation files should have license notices also. Manuals should |
| 9085 | 907 use the GNU Free Documentation License. Following is an example of the |
| 908 license notice to use after the copyright line(s) using all the | |
| 909 features of the GFDL. | |
| 4958 | 910 |
| 911 @smallexample | |
| 912 Permission is granted to copy, distribute and/or modify this document | |
|
10762
d67664a4e01c
Change license to GFDLv1.3+.
Simon Josefsson <simon@josefsson.org>
parents:
10642
diff
changeset
|
913 under the terms of the GNU Free Documentation License, Version 1.3 or |
| 4958 | 914 any later version published by the Free Software Foundation; with the |
| 9077 | 915 Invariant Sections being ``GNU General Public License'', with the |
| 9554 | 916 Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts |
| 4958 | 917 as in (a) below. A copy of the license is included in the section |
| 9077 | 918 entitled ``GNU Free Documentation License''. |
| 4958 | 919 |
| 9652 | 920 (a) The FSF's Back-Cover Text is: ``You have the freedom to |
| 921 copy and modify this GNU manual. Buying copies from the FSF | |
| 922 supports it in developing GNU and promoting software freedom.'' | |
| 4958 | 923 @end smallexample |
| 924 | |
| 925 If the FSF does not publish this manual on paper, then omit the last | |
| 6699 | 926 sentence in (a) that talks about copies from GNU Press. If the FSF is |
| 4958 | 927 not the copyright holder, then replace @samp{FSF} with the appropriate |
| 928 name. | |
| 929 | |
| 9085 | 930 Please adjust the list of invariant sections as appropriate for your |
| 931 manual. If there are none, then say ``with no Invariant Sections''. | |
| 932 If your manual is not published by the FSF, and under 400 pages, you | |
| 17328 | 933 can omit both cover texts. However, if it is copyright FSF, always |
| 934 ask the FSF what to do. | |
| 9085 | 935 |
| 14172 | 936 @xref{GNU Sample Texts,,, texinfo, Texinfo}, for a full example in a |
| 9085 | 937 Texinfo manual, and see |
| 938 @url{http://www.gnu.org/licenses/fdl-howto.html} for more advice about | |
| 939 how to use the GNU FDL. | |
| 4958 | 940 |
| 16186 | 941 If you write a manual that people might want to buy on paper, please |
| 942 write to @email{maintainers@@gnu.org} to tell the FSF about it. We | |
| 943 might want to publish it. | |
| 944 | |
|
10991
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
945 If the manual is over 400 pages, or if the FSF thinks it might be a |
|
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
946 good choice for publishing on paper, then please include the GNU GPL, |
|
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
947 as in the notice above. Please also include our standard invariant |
|
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
948 section which explains the importance of free documentation. Write to |
|
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
949 @email{assign@@gnu.org} to get a copy of this section. |
| 4958 | 950 |
| 9085 | 951 When you distribute several manuals together in one software package, |
| 952 their on-line forms can share a single copy of the GFDL (see | |
| 953 section@tie{}6). However, the printed (@samp{.dvi}, @samp{.pdf}, | |
| 954 @dots{}) forms should each contain a copy of the GFDL, unless they are | |
| 955 set up to be printed and published only together. Therefore, it is | |
| 956 usually simplest to include the GFDL in each manual. | |
| 957 | |
| 958 | |
| 959 @node License Notices for Other Files | |
| 960 @subsection License Notices for Other Files | |
| 4958 | 961 |
| 962 Small supporting files, short manuals (under 300 lines long) and rough | |
| 11605 | 963 documentation (@file{README} files, @file{INSTALL} files, etc.)@: can |
| 964 use a simple all-permissive license like this one: | |
| 4958 | 965 |
| 966 @smallexample | |
| 967 Copying and distribution of this file, with or without modification, | |
| 968 are permitted in any medium without royalty provided the copyright | |
| 11524 | 969 notice and this notice are preserved. This file is offered as-is, |
| 11605 | 970 without any warranty. |
| 4958 | 971 @end smallexample |
| 972 | |
| 11605 | 973 Older versions of this license did not have the second sentence with |
| 974 the express warranty disclaimer. There is no urgent need to update | |
| 975 existing files, but new files should use the new text. | |
| 976 | |
|
5622
6cabcbf982ea
propagate license change
Karl Berry <karl@freefriends.org>
parents:
5568
diff
changeset
|
977 If your package distributes Autoconf macros that are intended to be |
|
6cabcbf982ea
propagate license change
Karl Berry <karl@freefriends.org>
parents:
5568
diff
changeset
|
978 used (hence distributed) by third-party packages under possibly |
|
6cabcbf982ea
propagate license change
Karl Berry <karl@freefriends.org>
parents:
5568
diff
changeset
|
979 incompatible licenses, you may also use the above all-permissive |
|
6cabcbf982ea
propagate license change
Karl Berry <karl@freefriends.org>
parents:
5568
diff
changeset
|
980 license for these macros. |
|
6cabcbf982ea
propagate license change
Karl Berry <karl@freefriends.org>
parents:
5568
diff
changeset
|
981 |
| 9085 | 982 |
| 4958 | 983 @node External Libraries |
| 984 @section External Libraries | |
| 985 | |
| 986 When maintaining an FSF-copyrighted GNU package, you may occasionally | |
| 987 want to use a general-purpose free software module which offers a | |
| 988 useful functionality, as a ``library'' facility (though the module is | |
| 989 not always packaged technically as a library). | |
| 990 | |
| 16859 | 991 Make sure the license of the module is compatible with current @emph{and |
| 992 future} GPL versions. ``GNU GPL version 3 or later'' is good, and | |
| 16853 | 993 so is anything which includes permission for use under those GPL |
| 994 versions (including ``GNU GPL version 2 or later'', ``LGPL version | |
| 16859 | 995 @var{n} or later'', ``LGPL version 2.1'', ``GNU Affero GPL version 3 |
| 996 or later''). Lax permissive licenses are ok too, since they are | |
| 16853 | 997 compatible with all GPL versions. |
| 998 | |
| 999 ``GPL version 2 only'' is obviously unacceptable because it is | |
| 17256 | 1000 incompatible with GPL version 3. ``GPL version 3 only'' and ``GPL |
| 1001 version 2 or 3 only'' have a subtler problem: they would be incompatible | |
| 16853 | 1002 with GPL version 4, if we ever make one, so the module would become an |
| 1003 obstacle to upgrading your package's license to ``GPL version 4 or | |
| 1004 later''. | |
| 1005 | |
| 1006 One package you need to avoid is @code{goffice}, since it allows only | |
| 1007 GPL versions 2 and 3. | |
| 1008 | |
| 1009 It would be unreasonable to ask the author of the external module to | |
| 17256 | 1010 assign its copyright to the FSF. After all, person did not write |
| 16853 | 1011 it specifically as a contribution to your package, so it would be |
| 17256 | 1012 impertinent to ask, out of the blue, ``Please give the FSF your |
| 4958 | 1013 copyright.'' |
| 1014 | |
| 16853 | 1015 So make your program use the module but without treating the module as |
| 1016 a part of your program. There are two reasonable methods of doing | |
| 1017 this: | |
| 4958 | 1018 |
| 1019 @enumerate | |
| 1020 @item | |
| 1021 Assume the module is already installed on the system, and use it when | |
| 1022 linking your program. This is only reasonable if the module really has | |
| 1023 the form of a library. | |
| 1024 | |
| 1025 @item | |
| 1026 Include the module in your package, putting the source in a separate | |
| 1027 subdirectory whose @file{README} file says, ``This is not part of the | |
| 1028 GNU FOO program, but is used with GNU FOO.'' Then set up your makefiles | |
| 1029 to build this module and link it into the executable. | |
| 1030 | |
| 1031 For this method, it is not necessary to treat the module as a library | |
| 1032 and make a @samp{.a} file from it. You can link with the @samp{.o} | |
| 1033 files directly in the usual manner. | |
| 1034 @end enumerate | |
| 1035 | |
| 1036 Both of these methods create an irregularity, and our lawyers have told | |
| 1037 us to minimize the amount of such irregularity. So consider using these | |
| 1038 methods only for general-purpose modules that were written for other | |
| 1039 programs and released separately for general use. For anything that was | |
| 1040 written as a contribution to your package, please get papers signed. | |
| 1041 | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
1042 |
| 4958 | 1043 @node Clean Ups |
| 1044 @chapter Cleaning Up Changes | |
| 1045 @cindex contributions, accepting | |
| 1046 @cindex quality of changes suggested by others | |
| 1047 | |
| 1048 Don't feel obligated to include every change that someone asks you to | |
| 1049 include. You must judge which changes are improvements---partly based | |
| 1050 on what you think the users will like, and partly based on your own | |
| 1051 judgment of what is better. If you think a change is not good, you | |
| 1052 should reject it. | |
| 1053 | |
| 1054 If someone sends you changes which are useful, but written in an ugly | |
| 1055 way or hard to understand and maintain in the future, don't hesitate to | |
| 1056 ask per to clean up their changes before you merge them. Since the | |
| 1057 amount of work we can do is limited, the more we convince others to help | |
| 1058 us work efficiently, the faster GNU will advance. | |
| 1059 | |
| 1060 If the contributor will not or can not make the changes clean enough, | |
| 1061 then it is legitimate to say ``I can't install this in its present form; | |
| 1062 I can only do so if you clean it up.'' Invite per to distribute per | |
| 1063 changes another way, or to find other people to make them clean enough | |
| 1064 for you to install and maintain. | |
| 1065 | |
| 1066 The only reason to do these cleanups yourself is if (1) it is easy, less | |
| 1067 work than telling the author what to clean up, or (2) the change is an | |
| 1068 important one, important enough to be worth the work of cleaning it up. | |
| 1069 | |
| 1070 The GNU Coding Standards are a good thing to send people when you ask | |
| 1071 them to clean up changes (@pxref{Top, , Contents, standards, GNU Coding | |
| 1072 Standards}). The Emacs Lisp manual contains an appendix that gives | |
| 10263 | 1073 coding standards for Emacs Lisp programs; it is good to urge Lisp authors to |
| 1074 read it (@pxref{Tips, , Tips and Conventions, elisp, The GNU Emacs Lisp | |
| 4958 | 1075 Reference Manual}). |
| 1076 | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
1077 |
| 4958 | 1078 @node Platforms |
| 1079 @chapter Platforms to Support | |
| 1080 | |
| 1081 Most GNU packages run on a wide range of platforms. These platforms are | |
| 1082 not equally important. | |
| 1083 | |
| 1084 The most important platforms for a GNU package to support are GNU and | |
| 1085 GNU/Linux. Developing the GNU operating system is the whole point of | |
| 1086 the GNU Project; a GNU package exists to make the whole GNU system more | |
| 1087 powerful. So please keep that goal in mind and let it shape your work. | |
| 1088 For instance, every new feature you add should work on GNU, and | |
| 1089 GNU/Linux if possible too. If a new feature only runs on GNU and | |
| 1090 GNU/Linux, it could still be acceptable. However, a feature that runs | |
| 1091 only on other systems and not on GNU or GNU/Linux makes no sense in a | |
| 1092 GNU package. | |
| 1093 | |
| 1094 You will naturally want to keep the program running on all the platforms | |
| 1095 it supports. But you personally will not have access to most of these | |
| 13230 | 1096 platforms---so how should you do it? |
| 4958 | 1097 |
| 1098 Don't worry about trying to get access to all of these platforms. Even | |
| 1099 if you did have access to all the platforms, it would be inefficient for | |
| 1100 you to test the program on each platform yourself. Instead, you should | |
| 1101 test the program on a few platforms, including GNU or GNU/Linux, and let | |
| 1102 the users test it on the other platforms. You can do this through a | |
| 1103 pretest phase before the real release; when there is no reason to expect | |
| 1104 problems, in a package that is mostly portable, you can just make a | |
| 1105 release and let the users tell you if anything unportable was | |
| 1106 introduced. | |
| 1107 | |
| 1108 It is important to test the program personally on GNU or GNU/Linux, | |
| 1109 because these are the most important platforms for a GNU package. If | |
| 13230 | 1110 you don't have access to one of these platforms, as a GNU maintainer |
| 1111 you can get access to the general GNU login machine; see | |
| 1112 @url{http://www.gnu.org/software/README.accounts.html}. | |
| 4958 | 1113 |
| 7374 | 1114 Supporting other platforms is optional---we do it when that seems like |
| 1115 a good idea, but we don't consider it obligatory. If the users don't | |
| 1116 take care of a certain platform, you may have to desupport it unless | |
| 1117 and until users come forward to help. Conversely, if a user offers | |
| 1118 changes to support an additional platform, you will probably want to | |
| 1119 install them, but you don't have to. If you feel the changes are | |
| 1120 complex and ugly, if you think that they will increase the burden of | |
| 1121 future maintenance, you can and should reject them. This includes | |
| 1122 both free or mainly-free platforms such as OpenBSD, FreeBSD, and | |
| 1123 NetBSD, and non-free platforms such as Windows. | |
| 1124 | |
| 4958 | 1125 |
| 1126 @node Mail | |
| 1127 @chapter Dealing With Mail | |
| 13289 | 1128 @cindex email |
| 1129 | |
| 1130 This chapter describes setting up mailing lists for your package, and | |
| 1131 gives advice on how to handle bug reports and random requests once you | |
| 1132 have them. | |
| 4958 | 1133 |
| 13289 | 1134 @menu |
| 1135 * Standard Mailing Lists:: @samp{bug-pkg@@gnu.org} and other standard names. | |
| 1136 * Creating Mailing Lists:: The best way is to use Savannah. | |
| 1137 * Replying to Mail:: Advice on replying to incoming mail. | |
| 1138 @end menu | |
| 1139 | |
| 1140 | |
| 1141 @node Standard Mailing Lists | |
| 1142 @section Standard Mailing Lists | |
| 1143 | |
| 1144 @cindex standard mailing lists | |
| 1145 @cindex mailing lists, standard names of | |
| 1146 | |
| 4958 | 1147 @cindex mailing list for bug reports |
| 1148 Once a program is in use, you will get bug reports for it. Most GNU | |
| 1149 programs have their own special lists for sending bug reports. The | |
| 1150 advertised bug-reporting email address should always be | |
| 14172 | 1151 @samp{bug-@var{package}@@gnu.org}, to help show users that the program |
| 4958 | 1152 is a GNU package, but it is ok to set up that list to forward to another |
| 16158 | 1153 site if you prefer. |
| 4958 | 1154 |
| 13289 | 1155 @cindex @email{bug-gnu-utils@@gnu.org} |
| 4958 | 1156 We also have a catch-all list, @email{bug-gnu-utils@@gnu.org}, which is |
| 1157 used for all GNU programs that don't have their own specific lists. But | |
| 1158 nowadays we want to give each program its own bug-reporting list and | |
| 1159 move away from using @email{bug-gnu-utils}. | |
| 1160 | |
| 15793 | 1161 @xref{Replying to Mail}, for more about handling and tracking bug |
| 1162 reports. | |
| 1163 | |
| 13289 | 1164 @cindex help for users, mailing list for |
| 1165 Some GNU programs with many users have another mailing list, | |
| 14172 | 1166 @samp{help-@var{package}.org}, for people to ask other users for help. |
| 13289 | 1167 If your program has many users, you should create such a list for it. |
| 1168 For a fairly new program, which doesn't have a large user base yet, it | |
| 1169 is better not to bother with this. | |
| 1170 | |
| 1171 @cindex announcements, mailing list for | |
| 1172 If you wish, you can also have a mailing list | |
| 15793 | 1173 @samp{info-@var{package}} for announcements (@pxref{Announcements}). |
| 1174 Any other mailing lists you find useful can also be created. | |
| 13289 | 1175 |
| 16158 | 1176 The package distribution should state the name of all the package's |
| 1177 mailing lists in a prominent place, and ask users to help us by | |
| 1178 reporting bugs appropriately. The top-level @file{README} file and/or | |
| 1179 @file{AUTHORS} file are good places. Mailing list information should | |
| 1180 also be included in the manual and the package web pages (@pxref{Web | |
| 1181 Pages}). | |
| 1182 | |
| 1183 | |
| 13289 | 1184 |
| 1185 @node Creating Mailing Lists | |
| 1186 @section Creating Mailing Lists | |
| 10299 | 1187 |
| 13289 | 1188 @cindex creating mailing lists |
| 1189 @cindex mailing lists, creating | |
| 10299 | 1190 |
| 13289 | 1191 Using the web interface on @code{savannah.gnu.org} is by far the |
| 1192 easiest way to create normal mailing lists, managed through Mailman on | |
| 1193 the GNU mail server. Once you register your package on Savannah, you | |
| 1194 can create (and remove) lists yourself through the `Mailing Lists' | |
| 1195 menu, without needing to wait for intervention by anyone else. | |
| 1196 Furthermore, lists created through Savannah will have a reasonable | |
| 1197 default configuration for antispam purposes (see below). | |
| 1198 | |
| 1199 To create and maintain simple aliases and unmanaged lists, you can | |
| 1200 edit @file{/com/mailer/aliases} on the main GNU server. If you don't | |
| 13455 | 1201 have an account there, please read |
| 16279 | 1202 @url{http://www.gnu.org/software/README.accounts.html} (@pxref{GNU |
| 1203 Accounts and Resources}). | |
| 4958 | 1204 |
| 1205 But if you don't want to learn how to do those things, you can | |
| 1206 alternatively ask @email{alias-file@@gnu.org} to add you to the | |
| 1207 bug-reporting list for your program. To set up a new list, contact | |
| 1208 @email{new-mailing-list@@gnu.org}. You can subscribe to a list managed | |
| 1209 by Mailman by sending mail to the corresponding @samp{-request} address. | |
| 1210 | |
| 13289 | 1211 @cindex spam prevention |
| 5236 | 1212 You should moderate postings from non-subscribed addresses on your |
| 1213 mailing lists, to prevent propagation of unwanted messages (``spam'') | |
| 1214 to subscribers and to the list archives. For lists controlled by | |
| 1215 Mailman, you can do this by setting @code{Privacy Options - Sender | |
| 1216 Filter - generic_nonmember_action} to @code{Hold}, and then | |
| 1217 periodically (daily is best) reviewing the held messages, accepting | |
| 1218 the real ones and discarding the junk. | |
| 1219 | |
| 13289 | 1220 Lists created through Savannah will have this setting, and a number of |
| 1221 others, such that spam will be automatically deleted (after a short | |
| 1222 delay). The Savannah mailing list page describes all the details. | |
| 1223 You should still review the held messages in order to approve any that | |
| 1224 are real. | |
| 1225 | |
| 1226 | |
| 1227 @node Replying to Mail | |
| 1228 @section Replying to Mail | |
| 1229 | |
| 4958 | 1230 @cindex responding to bug reports |
| 13289 | 1231 @cindex bug reports, handling |
| 1232 @cindex help requests, handling | |
| 1233 | |
| 4958 | 1234 When you receive bug reports, keep in mind that bug reports are crucial |
| 1235 for your work. If you don't know about problems, you cannot fix them. | |
| 1236 So always thank each person who sends a bug report. | |
| 1237 | |
| 1238 You don't have an obligation to give more response than that, though. | |
| 1239 The main purpose of bug reports is to help you contribute to the | |
| 1240 community by improving the next version of the program. Many of the | |
| 1241 people who report bugs don't realize this---they think that the point is | |
| 1242 for you to help them individually. Some will ask you to focus on that | |
| 1243 @emph{instead of} on making the program better. If you comply with | |
| 1244 their wishes, you will have been distracted from the job of maintaining | |
| 1245 the program. | |
| 1246 | |
| 1247 For example, people sometimes report a bug in a vague (and therefore | |
| 1248 useless) way, and when you ask for more information, they say, ``I just | |
| 1249 wanted to see if you already knew the solution'' (in which case the bug | |
| 1250 report would do nothing to help improve the program). When this | |
| 1251 happens, you should explain to them the real purpose of bug reports. (A | |
| 1252 canned explanation will make this more efficient.) | |
| 1253 | |
| 1254 When people ask you to put your time into helping them use the program, | |
| 1255 it may seem ``helpful'' to do what they ask. But it is much @emph{less} | |
| 1256 helpful than improving the program, which is the maintainer's real job. | |
| 1257 | |
| 1258 By all means help individual users when you feel like it, if you feel | |
| 1259 you have the time available. But be careful to limit the amount of time | |
| 1260 you spend doing this---don't let it eat away the time you need to | |
| 1261 maintain the program! Know how to say no; when you are pressed for | |
| 1262 time, just ``thanks for the bug report---I will fix it'' is enough | |
| 1263 response. | |
| 1264 | |
| 13289 | 1265 Some GNU packages, such as Emacs and GCC, come with advice about how |
| 1266 to make bug reports useful. Copying and adapting that could be very | |
| 1267 useful for your package. | |
| 4958 | 1268 |
| 15793 | 1269 @cindex @url{http://bugs.gnu.org} |
| 1270 @cindex bug reports, email tracker for | |
| 1271 @cindex bug reports, web tracker for | |
| 1272 If you would like to use an email-based bug tracking system, see | |
| 1273 @url{http://bugs.gnu.org}; this can be connected with the regular | |
| 1274 bug-reporting address. Alternatively, if you would like to use a | |
| 1275 web-based bug tracking system, Savannah supports this (@pxref{Old | |
| 1276 Versions}), but please don't fail to accept bugs by regular email as | |
| 1277 well---we don't want to put up unnecessary barriers against users | |
| 1278 submitting reports. | |
| 1279 | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
1280 |
| 4958 | 1281 @node Old Versions |
| 1282 @chapter Recording Old Versions | |
| 1283 @cindex version control | |
| 1284 | |
| 1285 It is very important to keep backup files of all source files of GNU. | |
| 13921 | 1286 You can do this using a source control system (such as Bazaar, RCS, |
| 15518 | 1287 CVS, Git, Subversion, @dots{}) if you like. An easy way to use |
| 1288 many such systems is via the Version Control library in Emacs | |
| 14719 | 1289 (@pxref{Introduction to VC,, Introduction to Version Control, emacs, |
| 1290 The GNU Emacs Manual}). | |
| 4958 | 1291 |
| 1292 The history of previous revisions and log entries is very important for | |
| 1293 future maintainers of the package, so even if you do not make it | |
| 1294 publicly accessible, be careful not to put anything in the repository or | |
| 1295 change log that you would not want to hand over to another maintainer | |
| 1296 some day. | |
| 1297 | |
| 11738 | 1298 @cindex @code{savannah-hackers@@gnu.org} |
| 15518 | 1299 The GNU Project provides a server that GNU packages can use |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
1300 for source control and other package needs: @code{savannah.gnu.org}. |
| 13921 | 1301 Savannah is managed by @email{savannah-hackers@@gnu.org}. For more |
| 1302 details on using and contributing to Savannah, see | |
| 1303 @url{http://savannah.gnu.org/maintenance}. | |
| 4958 | 1304 |
| 15518 | 1305 It's not an absolute requirement, but all GNU maintainers are strongly |
| 13921 | 1306 encouraged to take advantage of Savannah, as sharing such a central |
| 15518 | 1307 point can serve to foster a sense of community among GNU developers as |
| 1308 well as help in keeping up with project management. Please don't mark | |
| 1309 Savannah projects for GNU packages as private; that defeats a large | |
| 1310 part of the purpose of using Savannah in the first place. | |
| 11738 | 1311 |
| 1312 @cindex @code{savannah-announce@@gnu.org} mailing list | |
| 13230 | 1313 If you do use Savannah, please subscribe to the |
| 11738 | 1314 @email{savannah-announce@@gnu.org} mailing list |
| 1315 (@url{http://lists.gnu.org/mailman/listinfo/savannah-announce}). This | |
| 1316 is a very low-volume list to keep Savannah users informed of system | |
| 1317 upgrades, problems, and the like. | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
1318 |
| 4958 | 1319 |
| 1320 @node Distributions | |
| 1321 @chapter Distributions | |
| 1322 | |
| 16359 | 1323 Please follow the GNU conventions when making GNU software |
| 4958 | 1324 distributions. |
| 1325 | |
| 1326 @menu | |
| 6710 | 1327 * Distribution tar Files:: |
| 1328 * Distribution Patches:: | |
| 1329 * Distribution on ftp.gnu.org:: | |
| 1330 * Test Releases:: | |
| 1331 * Automated FTP Uploads:: | |
| 1332 * Announcements:: | |
| 4958 | 1333 @end menu |
| 1334 | |
| 1335 @node Distribution tar Files | |
| 1336 @section Distribution tar Files | |
| 1337 @cindex distribution, tar files | |
| 1338 | |
| 1339 The tar file for version @var{m}.@var{n} of program @code{foo} should be | |
| 1340 named @file{foo-@var{m}.@var{n}.tar}. It should unpack into a | |
| 1341 subdirectory named @file{foo-@var{m}.@var{n}}. Tar files should not | |
| 1342 unpack into files in the current directory, because this is inconvenient | |
| 1343 if the user happens to unpack into a directory with other files in it. | |
| 1344 | |
| 1345 Here is how the @file{Makefile} for Bison creates the tar file. | |
| 1346 This method is good for other programs. | |
| 1347 | |
| 1348 @example | |
| 1349 dist: bison.info | |
| 1350 echo bison-`sed -e '/version_string/!d' \ | |
| 1351 -e 's/[^0-9.]*\([0-9.]*\).*/\1/' -e q version.c` > .fname | |
| 1352 -rm -rf `cat .fname` | |
| 1353 mkdir `cat .fname` | |
| 1354 dst=`cat .fname`; for f in $(DISTFILES); do \ | |
| 1355 ln $(srcdir)/$$f $$dst/$$f || @{ echo copying $$f; \ | |
| 1356 cp -p $(srcdir)/$$f $$dst/$$f ; @} \ | |
| 1357 done | |
| 1358 tar --gzip -chf `cat .fname`.tar.gz `cat .fname` | |
| 1359 -rm -rf `cat .fname` .fname | |
| 1360 @end example | |
| 1361 | |
| 1362 Source files that are symbolic links to other file systems cannot be | |
| 1363 installed in the temporary directory using @code{ln}, so use @code{cp} | |
| 1364 if @code{ln} fails. | |
| 1365 | |
| 1366 @pindex automake | |
| 1367 Using Automake is a good way to take care of writing the @code{dist} | |
| 1368 target. | |
| 1369 | |
| 1370 @node Distribution Patches | |
| 1371 @section Distribution Patches | |
| 1372 @cindex patches, against previous releases | |
| 1373 | |
| 1374 If the program is large, it is useful to make a set of diffs for each | |
| 1375 release, against the previous important release. | |
| 1376 | |
| 1377 At the front of the set of diffs, put a short explanation of which | |
| 1378 version this is for and which previous version it is relative to. | |
| 1379 Also explain what else people need to do to update the sources | |
| 1380 properly (for example, delete or rename certain files before | |
| 1381 installing the diffs). | |
| 1382 | |
| 1383 The purpose of having diffs is that they are small. To keep them | |
| 1384 small, exclude files that the user can easily update. For example, | |
| 1385 exclude info files, DVI files, tags tables, output files of Bison or | |
| 1386 Flex. In Emacs diffs, we exclude compiled Lisp files, leaving it up | |
| 1387 to the installer to recompile the patched sources. | |
| 1388 | |
| 1389 When you make the diffs, each version should be in a directory suitably | |
| 1390 named---for example, @file{gcc-2.3.2} and @file{gcc-2.3.3}. This way, | |
| 1391 it will be very clear from the diffs themselves which version is which. | |
| 1392 | |
| 1393 @pindex diff | |
| 1394 @pindex patch | |
| 1395 @cindex time stamp in diffs | |
| 1396 If you use GNU @code{diff} to make the patch, use the options | |
| 1397 @samp{-rc2P}. That will put any new files into the output as ``entirely | |
| 15793 | 1398 different''. Also, the patch's context diff headers should have dates |
| 4958 | 1399 and times in Universal Time using traditional Unix format, so that patch |
| 1400 recipients can use GNU @code{patch}'s @samp{-Z} option. For example, | |
| 1401 you could use the following Bourne shell command to create the patch: | |
| 1402 | |
| 1403 @example | |
| 1404 LC_ALL=C TZ=UTC0 diff -rc2P gcc-2.3.2 gcc-2.3.3 | \ | |
| 1405 gzip -9 >gcc-2.3.2-2.3.3.patch.gz | |
| 1406 @end example | |
| 1407 | |
| 1408 If the distribution has subdirectories in it, then the diffs probably | |
| 1409 include some files in the subdirectories. To help users install such | |
| 1410 patches reliably, give them precise directions for how to run patch. | |
| 1411 For example, say this: | |
| 1412 | |
| 1413 @display | |
| 1414 To apply these patches, cd to the main directory of the program | |
| 1415 and then use `patch -p1'. `-p1' avoids guesswork in choosing | |
| 1416 which subdirectory to find each file in. | |
| 1417 @end display | |
| 1418 | |
| 1419 It's wise to test your patch by applying it to a copy of the old | |
| 1420 version, and checking that the result exactly matches the new version. | |
| 1421 | |
| 16712 | 1422 |
| 4958 | 1423 @node Distribution on ftp.gnu.org |
| 1424 @section Distribution on @code{ftp.gnu.org} | |
| 1425 @cindex GNU ftp site | |
| 13355 | 1426 @cindex @code{ftp.gnu.org}, the GNU release site |
| 4958 | 1427 |
| 16712 | 1428 We strongly recommend using @code{ftp.gnu.org} to distribute official |
| 1429 releases. If you want to also distribute the package from a site of | |
| 1430 your own, that is fine. To use some other site instead of | |
| 1431 @code{ftp.gnu.org} is acceptable, provided it allows connections from | |
| 1432 anyone anywhere. | |
| 1433 | |
| 1434 @xref{Automated FTP Uploads}, for the procedural details of putting | |
| 1435 new versions on @code{ftp.gnu.org}. | |
| 1436 | |
| 4958 | 1437 |
| 1438 @node Test Releases | |
| 1439 @section Test Releases | |
| 1440 @cindex test releases | |
| 1441 @cindex beta releases | |
| 1442 @cindex pretest releases | |
| 1443 | |
| 13355 | 1444 @cindex @code{alpha.gnu.org}, test release site |
| 4958 | 1445 When you release a greatly changed new major version of a program, you |
| 1446 might want to do so as a pretest. This means that you make a tar file, | |
| 1447 but send it only to a group of volunteers that you have recruited. (Use | |
| 1448 a suitable GNU mailing list/newsgroup to recruit them.) | |
| 1449 | |
| 13355 | 1450 We normally use the server @code{alpha.gnu.org} for pretests and |
| 16712 | 1451 prerelease versions. @xref{Automated FTP Uploads}, for the procedural |
| 1452 details of putting new versions on @code{alpha.gnu.org}. | |
| 4958 | 1453 |
| 1454 Once a program gets to be widely used and people expect it to work | |
| 1455 solidly, it is a good idea to do pretest releases before each ``real'' | |
| 1456 release. | |
| 1457 | |
| 1458 There are two ways of handling version numbers for pretest versions. | |
| 1459 One method is to treat them as versions preceding the release you are going | |
| 1460 to make. | |
| 1461 | |
| 1462 In this method, if you are about to release version 4.6 but you want | |
| 1463 to do a pretest first, call it 4.5.90. If you need a second pretest, | |
| 1464 call it 4.5.91, and so on. If you are really unlucky and ten pretests | |
| 1465 are not enough, after 4.5.99 you could advance to 4.5.990 and so on. | |
| 1466 (You could also use 4.5.100, but 990 has the advantage of sorting in | |
| 1467 the right order.) | |
| 1468 | |
| 1469 The other method is to attach a date to the release number that is | |
| 1470 coming. For a pretest for version 4.6, made on Dec 10, 2002, this | |
| 1471 would be 4.6.20021210. A second pretest made the same day could be | |
| 1472 4.6.20021210.1. | |
| 1473 | |
| 1474 For development snapshots that are not formal pretests, using just | |
| 1475 the date without the version numbers is ok too. | |
| 1476 | |
| 1477 One thing that you should never do is to release a pretest with the same | |
| 1478 version number as the planned real release. Many people will look only | |
| 1479 at the version number (in the tar file name, in the directory name that | |
| 1480 it unpacks into, or wherever they can find it) to determine whether a | |
| 1481 tar file is the latest version. People might look at the test release | |
| 1482 in this way and mistake it for the real release. Therefore, always | |
| 1483 change the number when you release changed code. | |
| 1484 | |
| 1485 | |
| 1486 @node Automated FTP Uploads | |
| 1487 @section Automated FTP Uploads | |
| 1488 | |
| 1489 @cindex ftp uploads, automated | |
| 1490 In order to upload new releases to @code{ftp.gnu.org} or | |
| 1491 @code{alpha.gnu.org}, you first need to register the necessary | |
| 1492 information. Then, you can perform uploads yourself, with no | |
| 1493 intervention needed by the system administrators. | |
| 1494 | |
| 16359 | 1495 The general idea is that releases should be cryptographically signed |
| 9573 | 1496 before they are made publicly available. |
| 1497 | |
| 4958 | 1498 @menu |
| 1499 * Automated Upload Registration:: | |
| 1500 * Automated Upload Procedure:: | |
| 17274 | 1501 * FTP Upload Release File Triplet:: |
| 1502 * FTP Upload Directive File:: | |
| 1503 * FTP Upload Directory Trees:: | |
| 1504 * FTP Upload File Replacement:: | |
| 1505 * FTP Upload Standalone Directives:: | |
| 6943 | 1506 * FTP Upload Directive File - v1.1:: |
| 1507 * FTP Upload Directive File - v1.0:: | |
| 4958 | 1508 @end menu |
| 1509 | |
| 1510 | |
| 1511 @node Automated Upload Registration | |
| 1512 @subsection Automated Upload Registration | |
| 1513 | |
| 10306 | 1514 @cindex registration for uploads |
| 4958 | 1515 @cindex uploads, registration for |
| 1516 | |
| 9573 | 1517 Here is how to register your information so you can perform uploads |
| 1518 for your GNU package: | |
| 1519 | |
| 1520 @enumerate | |
| 1521 @item | |
| 1522 Create an account for yourself at @url{http://savannah.gnu.org}, if | |
| 1523 you don't already have one. By the way, this is also needed to | |
| 13300 | 1524 maintain the web pages at @url{http://www.gnu.org} for your project |
| 9732 | 1525 (@pxref{Web Pages}). |
| 9573 | 1526 |
| 1527 @item | |
| 1528 In the @samp{My Account Conf} page on @code{savannah}, upload the GPG | |
| 14172 | 1529 key you will use to sign your packages. If you haven't created one |
| 14242 | 1530 before, you can do so with the command @code{gpg --gen-key} (you can |
| 16910 | 1531 accept and/or confirm the default answers to its questions). |
| 14172 | 1532 |
| 1533 Optional but recommended: Send your key to a GPG public key server: | |
| 1534 @code{gpg --keyserver keys.gnupg.net --send-keys @var{keyid}}, where | |
| 1535 @var{keyid} is the eight hex digits reported by @code{gpg | |
| 1536 --list-public-keys} on the @code{pub} line before the date. For full | |
| 1537 information about GPG, see @url{http://www.gnu.org/software/gpg}. | |
| 9573 | 1538 |
| 1539 @item | |
| 11116 | 1540 Compose a message with the following items in some @var{msgfile}. |
| 1541 Then GPG-sign it by running @code{gpg --clearsign @var{msgfile}}, and | |
| 15948 | 1542 finally email the resulting @file{@var{msgfile}.asc} to |
| 11116 | 1543 @email{ftp-upload@@gnu.org}. |
| 4958 | 1544 |
| 1545 @enumerate | |
| 1546 @item | |
| 15335 | 1547 Name of package(s) that you are the maintainer for, your |
| 1548 preferred email address, and your Savannah username. | |
| 4958 | 1549 |
| 1550 @item | |
| 14172 | 1551 An ASCII armored copy of your GPG key, as an attachment. (@samp{gpg |
| 9573 | 1552 --export -a @var{your_key_id} >mykey.asc} should give you this.) |
| 4958 | 1553 |
| 1554 @item | |
| 1555 A list of names and preferred email addresses of other individuals you | |
| 1556 authorize to make releases for which packages, if any (in the case that you | |
| 1557 don't make all releases yourself). | |
| 1558 | |
| 1559 @item | |
| 14172 | 1560 ASCII armored copies of GPG keys for any individuals listed in (3). |
| 4958 | 1561 @end enumerate |
| 9573 | 1562 @end enumerate |
| 4958 | 1563 |
| 1564 The administrators will acknowledge your message when they have added | |
| 1565 the proper GPG keys as authorized to upload files for the | |
| 1566 corresponding packages. | |
| 1567 | |
| 11116 | 1568 The upload system will email receipts to the given email addresses |
| 1569 when an upload is made, either successfully or unsuccessfully. | |
| 1570 | |
| 4958 | 1571 |
| 1572 @node Automated Upload Procedure | |
| 1573 @subsection Automated Upload Procedure | |
| 1574 | |
| 1575 @cindex uploads | |
| 1576 | |
| 10817 | 1577 Once you have registered your information as described in the previous |
| 17274 | 1578 section, you can and should do ftp uploads for your package. There |
| 1579 are two basic kinds of uploads (details in the following sections): | |
| 4958 | 1580 |
| 1581 @enumerate | |
| 1582 @item | |
| 17274 | 1583 Three related files (a ``triplet'') to upload a file destined for |
| 1584 @code{ftp.gnu.org} or @code{alpha.gnu.org}: @pxref{FTP Upload Release | |
| 1585 File Triplet}. | |
| 1586 | |
| 17275 | 1587 @item |
| 17274 | 1588 A single (signed) standalone ``directive file'' to perform operations |
| 1589 on the server: @pxref{FTP Upload Standalone Directives}. | |
| 4958 | 1590 @end enumerate |
| 1591 | |
| 17274 | 1592 In either case, you upload the file(s) via anonymous ftp to the host |
| 1593 @code{ftp-upload.gnu.org}. If the upload is destined for | |
| 1594 @code{ftp.gnu.org}, place the file(s) in the directory | |
| 1595 @file{/incoming/ftp}. If the upload is destined for | |
| 1596 @code{alpha.gnu.org}, place the file(s) in the directory | |
| 1597 @file{/incoming/alpha}. | |
| 6943 | 1598 |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
1599 Uploads are processed every five minutes. Uploads that are in |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
1600 progress while the upload processing script is running are handled |
| 17274 | 1601 properly, so do not worry about the timing of your upload. Spurious |
| 1602 and stale uploaded files are deleted automatically after 24 hours. | |
| 1603 | |
| 1604 Your designated upload email addresses (@pxref{Automated Upload | |
| 1605 Registration}) are sent a message if there are problems processing an | |
| 1606 upload for your package. You also receive a message when an upload | |
| 1607 has been successfully processed. | |
| 1608 | |
| 1609 One programmatic way to create and transfer the necessary files is to | |
| 1610 use the @code{gnupload} script, which is available from the | |
| 10306 | 1611 @file{build-aux/} directory of the @code{gnulib} project at |
| 17274 | 1612 @url{http://savannah.gnu.org/projects/gnulib}. Run |
| 1613 @code{gnupload@tie{}--help} for a description and examples. | |
| 1614 | |
| 1615 @code{gnupload} invokes the program @code{ncftpput} to do the actual | |
| 10306 | 1616 transfers; if you don't happen to have the @code{ncftp} package |
| 10817 | 1617 installed, the @code{ncftpput-ftp} script in the @file{build-aux/} |
| 17274 | 1618 directory of @code{gnulib} can serve as a replacement. It uses the |
| 1619 plain command line @code{ftp} program. | |
| 10306 | 1620 |
| 12439 | 1621 If you have difficulties with an upload, email |
| 15793 | 1622 @email{ftp-upload@@gnu.org}. You can check the archive of uploads |
| 1623 processed at | |
| 1624 @url{https://lists.gnu.org/archive/html/ftp-upload-report}. | |
| 6943 | 1625 |
| 1626 | |
| 17274 | 1627 @node FTP Upload Release File Triplet |
| 1628 @subsection FTP Upload Release File Triplet | |
| 1629 | |
| 1630 @cindex FTP uploads, of release files | |
| 1631 | |
| 1632 Ordinarily, the goal is to upload a new release of your package, let's | |
| 1633 say, the source archive @file{foo-1.0.tar.gz}. To do this, you | |
| 1634 simultaneously upload three files: | |
| 1635 | |
| 1636 @enumerate | |
| 1637 @item | |
| 1638 The file to be distributed; in our example, @file{foo-1.0.tar.gz}. | |
| 1639 | |
| 1640 @item | |
| 1641 Detached GPG binary signature file for (1); for example, | |
| 1642 @file{foo-1.0.tar.gz.sig}. Make this with @samp{gpg -b foo-1.0.tar.gz}. | |
| 1643 | |
| 1644 @item | |
| 1645 A clearsigned @dfn{directive file}; for example, | |
| 1646 @file{foo-1.0.tar.gz.directive.asc}, created with @samp{gpg | |
| 1647 --clearsign foo-1.0.tar.gz.directive}. Its contents are described in | |
| 1648 the next section. | |
| 1649 @end enumerate | |
| 1650 | |
| 1651 The names of the files are important. The signature file must have | |
| 1652 the same name as the file to be distributed, with an additional | |
| 1653 @file{.sig} extension. The directive file must have the same name as | |
| 1654 the file to be distributed, with an additional @file{.directive.asc} | |
| 1655 extension. If you do not follow this naming convention, the upload | |
| 1656 @emph{will not be processed}. | |
| 1657 | |
| 1658 | |
| 1659 @node FTP Upload Directive File | |
| 1660 @subsection FTP Upload Directive File | |
| 1661 | |
| 1662 @cindex directive file, for FTP uploads | |
| 1663 | |
| 1664 To repeat, a (signed) @dfn{directive file} must be part of every | |
| 1665 upload. The unsigned original is just a plain text file you can | |
| 1666 create with any text editor. Its name must be, e.g., | |
| 1667 @file{foo-1.0.tar.gz.directive} for accompanying an upload of | |
| 1668 @file{foo-1.0.tar.gz}. | |
| 1669 | |
| 1670 After creating the file, run @samp{gpg --clearsign | |
| 1671 foo-1.0.tar.gz.directive}, which will create | |
| 1672 @file{foo-1.0.tar.gz.directive.asc}; this is the file to be uploaded. | |
| 1673 | |
| 1674 When part of a triplet for uploading a release file, the directive | |
| 1675 file must always contain the directives @code{version}, | |
| 1676 @code{filename} and @code{directory}. In addition, a @code{comment} | |
| 1677 directive is optional. These directives can be given in any order. | |
| 1678 | |
| 1679 Continuing our example of uploading @file{foo-1.0.tar.gz} for a | |
| 1680 package named @code{foo} to @code{ftp.gnu.org}, the values would be as | |
| 1681 follows: | |
| 1682 | |
| 1683 @table @code | |
| 1684 @item version | |
| 1685 must be the value @samp{1.2} (the current version, as of May@tie{}2012):@* | |
| 1686 @t{version: 1.2} | |
| 1687 | |
| 1688 @item filename | |
| 1689 must be the name of the file to be distributed:@* | |
| 1690 @t{filename: foo-1.0.tar.gz} | |
| 1691 | |
| 1692 @item directory | |
| 1693 specifies the final destination directory where the uploaded file and | |
| 1694 its @file{.sig} companion are to be placed. Here we will put our file | |
| 1695 in the top level directory of the package, as is the most common | |
| 1696 practice:@* | |
| 1697 @t{directory: foo} | |
| 1698 | |
| 1699 @item comment | |
| 1700 is optional, and ignored if present:@* | |
| 1701 @t{comment: let's hope this works!} | |
| 1702 @end table | |
| 1703 | |
| 1704 Putting the above together, the complete contents of the directive | |
| 1705 file @file{foo-1.0.tar.gz.directive} for our example would be: | |
| 1706 | |
| 1707 @example | |
| 1708 version: 1.2 | |
| 1709 directory: foo | |
| 1710 filename: foo-1.0.tar.gz | |
| 1711 comment: let's hope this works! | |
| 1712 @end example | |
| 1713 | |
| 1714 Then you @samp{gpg --clearsign} the file as given above, and upload | |
| 1715 (using anonymous ftp) the three files: | |
| 1716 | |
| 1717 @table @file | |
| 1718 @item foo-1.0.tar.gz | |
| 1719 @item foo-1.0.tar.gz.sig | |
| 17278 | 1720 @item foo-1.0.tar.gz.directive.asc |
| 17274 | 1721 @end table |
| 1722 | |
| 1723 @noindent to the host @file{ftp-upload.gnu.org}, directory | |
| 1724 @file{/incoming/ftp} (for official releases), or the directory | |
| 17275 | 1725 @file{/incoming/alpha} (for test releases). |
| 17274 | 1726 |
| 1727 After the system authenticates the signatures, the files | |
| 1728 @file{foo-1.0.tar.gz} and @file{foo-1.0.tar.gz.sig} are placed in | |
| 17275 | 1729 the directory @file{gnu/foo/} on @code{ftp.gnu.org}. That is, we'll |
| 17274 | 1730 have made our release available at |
| 1731 @indicateurl{http://ftp.gnu.org/gnu/foo/foo-1.0.tar.gz} (and then from | |
| 1732 our many mirrors via | |
| 1733 @indicateurl{http://ftpmirror.gnu.org/foo/foo-1.0.tar.gz}). Whew. | |
| 1734 | |
| 1735 A common reason for the upload not succeeding is your GPG signature | |
| 1736 not being registered with the upload system. There is nothing that | |
| 1737 makes this happen automatically. You must email the system | |
| 1738 administrators as described above (@pxref{Automated Upload | |
| 1739 Registration}). | |
| 1740 | |
| 1741 | |
| 1742 @node FTP Upload Directory Trees | |
| 1743 @subsection FTP Upload Directory Trees | |
| 1744 | |
| 1745 @cindex directory trees, in ftp uploads | |
| 1746 @cindex hierarchy, under ftp upload directory | |
| 1747 @cindex uploads, directory trees in | |
| 1748 | |
| 1749 You can make any directory hierarchy you like under your package | |
| 1750 directory. The system automatically creates any intermediate | |
| 1751 directories you specify in the @code{directory} directive. | |
| 1752 | |
| 1753 Slightly modifying the example above, the following directive file: | |
| 16866 | 1754 |
| 1755 @example | |
| 1756 version: 1.2 | |
| 17274 | 1757 directory: foo/foo-1.0 |
| 1758 filename: foo-1.0.tar.gz | |
| 1759 comment: creates per-version subdirectory as needed | |
| 1760 @end example | |
| 1761 | |
| 1762 @noindent | |
| 1763 would put the tar file in the @file{foo-1.0/} subdirectory of the | |
| 1764 package @code{foo}, thus ending up at | |
| 1765 @indicateurl{ftp.gnu.org:gnu/foo/foo-1.0/foo-1.0.tar.gz}. | |
| 1766 | |
| 1767 However, to keep things simpler for users, we recommend not using | |
| 1768 subdirectories, unless perhaps each release of your package consists | |
| 1769 of many separate files. | |
| 1770 | |
| 1771 | |
| 1772 @node FTP Upload File Replacement | |
| 1773 @subsection FTP Upload File Replacement | |
| 1774 | |
| 1775 @cindex replacing uploaded files | |
| 1776 @cindex uploads, replacing | |
| 1777 | |
| 1778 You can replace existing files that have already been uploaded by | |
| 1779 including a directive line @code{replace:@tie{}true}. For example, | |
| 1780 you might like to provide a README file in the release directory and | |
| 1781 update it from time to time. The full directive file for that would | |
| 1782 look like this: | |
| 1783 | |
| 1784 @example | |
| 1785 replace: true | |
| 1786 version: 1.2 | |
| 1787 directory: foo | |
| 1788 filename: README | |
| 1789 comment: replaces an existing README | |
| 16866 | 1790 @end example |
| 1791 | |
| 17274 | 1792 It is ok if the file to be replaced doesn't already exist; then the |
| 1793 new file is simply added, i.e., the @file{replace} directive has no | |
| 1794 effect. | |
| 1795 | |
| 1796 When an existing file is replaced, the original is archived to a | |
| 1797 private location. There is no automated or public access to such | |
| 1798 archived files; if you want to retrieve or view them, please email | |
| 1799 @email{sysadmin@@fsf.org}. | |
| 1800 | |
| 1801 We very strongly discourage replacing an actual software release file, | |
| 1802 such as @file{foo-1.0.tar.gz}. Releases should be unique, and | |
| 1803 forever. If you need to make fixes, make another release. If you | |
| 1804 have an exigent reason for a particular release file to no longer be | |
| 1805 available, it can be explicitly archived, as described in the next | |
| 1806 section. | |
| 1807 | |
| 1808 If you want to make the current release available under a generic | |
| 1809 name, such as @code{foo-latest.tar.gz}, that is better done with | |
| 1810 symlinks, also as described in the next section. | |
| 1811 | |
| 1812 | |
| 1813 @node FTP Upload Standalone Directives | |
| 1814 @subsection FTP Upload Standalone Directives | |
| 1815 | |
| 1816 @cindex standalone directives, for ftp uploads | |
| 1817 @cindex directives for ftp uploads, standalone | |
| 1818 | |
| 1819 The previous sections describe how to upload a file to be publicly | |
| 1820 released. It's also possible to upload a directive file by itself to | |
| 1821 perform a few operations on the upload directory. The supported | |
| 1822 directives are: | |
| 1823 | |
| 1824 @table @code | |
| 1825 @item symlink | |
| 1826 creates a symlink. | |
| 1827 | |
| 1828 @item rmsymlink | |
| 1829 removes a symlink. | |
| 1830 | |
| 1831 @item archive | |
| 1832 takes a file or directory offline. | |
| 1833 @end table | |
| 1834 | |
| 1835 As for the directives described above, the @code{directory} and | |
| 1836 @code{version} directives are still required, the @code{comment} | |
| 1837 directive remains optional, and the @code{filename} directive is not | |
| 1838 allowed. | |
| 1839 | |
| 1840 When uploaded by itself, the name of the directive file is not | |
| 1841 important. But it must be still be signed, using @samp{gpg | |
| 1842 --clearsign}; the resulting @file{.asc} file is what should be | |
| 1843 uploaded. | |
| 1844 | |
| 1845 Here's an example of the full directive file to create a | |
| 1846 @file{foo-latest.tar.gz} symlink: | |
| 16866 | 1847 |
| 1848 @example | |
| 1849 version: 1.2 | |
| 17274 | 1850 directory: foo |
| 1851 symlink: foo-1.1.tar.gz foo-latest.tar.gz | |
| 1852 comment: create a symlink | |
| 16866 | 1853 @end example |
| 1854 | |
| 17274 | 1855 If you include more than one directive in a standalone upload, the |
| 1856 directives are executed in the sequence they are specified in. If a | |
| 1857 directive results in an error, further execution of the upload is | |
| 1858 aborted. | |
| 1859 | |
| 1860 Removing a symbolic link (with @code{rmsymlink}) which does not exist | |
| 1861 results in an error. On the other hand, attempting to create a | |
| 1862 symbolic link that already exists (with @code{symlink}) is not an | |
| 1863 error. In this case @code{symlink} behaves like the command | |
| 1864 @command{ln -s -f}: any existing symlink is removed before creating | |
| 1865 the link. (But an existing regular file or directory is not replaced.) | |
| 1866 | |
| 1867 Here's an example of removing a symlink, e.g., if you decide not to | |
| 1868 maintain a @file{foo-latest} link any more: | |
| 1869 | |
| 1870 @example | |
| 1871 version: 1.2 | |
| 1872 directory: foo | |
| 1873 rmsymlink: foo-latest.tar.gz | |
| 1874 comment: remove a symlink | |
| 1875 @end example | |
| 1876 | |
| 1877 @noindent | |
| 1878 And here's an example of archiving a file, e.g., an unintended upload: | |
| 1879 | |
| 1880 @example | |
| 1881 version: 1.2 | |
| 1882 directory: foo | |
| 1883 archive: foo-1.1x.tar.gz | |
| 1884 comment: archive an old file; it will not be | |
| 1885 comment: publicly available any more. | |
| 1886 @end example | |
| 1887 | |
| 1888 The @code{archive} directive causes the specified items to become | |
| 1889 inaccessible. This should only be used when it is actively bad for | |
| 1890 them to be available, e.g., you uploaded something by mistake. | |
| 1891 | |
| 1892 If all you want to do is reduce how much stuff is in your release | |
| 1893 directory, an alternative is to email @email{sysadmin@@fsf.org} and | |
| 1894 ask them to move old items to the @file{http://ftp.gnu.org/old-gnu/} | |
| 1895 directory; then they will still be available. In general, however, we | |
| 1896 recommend leaving all official releases in the main release directory. | |
| 1897 | |
| 16866 | 1898 |
| 6943 | 1899 @node FTP Upload Directive File - v1.1 |
| 1900 @subsection FTP Upload Directive File - v1.1 | |
| 1901 | |
| 17274 | 1902 The v1.1 protocol for uploads lacked the @code{replace} directive; |
| 1903 instead, file replacements were done automatically and silently | |
| 1904 (clearly undesirable). This is the only difference between v1.2 and | |
| 1905 v1.1. | |
| 6943 | 1906 |
| 1907 | |
| 1908 @node FTP Upload Directive File - v1.0 | |
| 1909 @subsection FTP Upload Directive File - v1.0 | |
| 1910 | |
| 17274 | 1911 Support for v1.0 uploads was discontinued in May 2012; please upgrade |
| 16866 | 1912 to@tie{}v1.2. |
| 4958 | 1913 |
| 17274 | 1914 In v1.0, the directive file contained one line, excluding the |
| 1915 clearsigned data GPG that inserts, which specifies the final | |
| 1916 destination directory where items (1) and (2) are to be placed. | |
| 1917 | |
| 1918 For example, the @file{foo-1.0.tar.gz.directive.asc} file might contain the | |
| 4958 | 1919 single line: |
| 1920 | |
| 1921 @example | |
| 1922 directory: bar/v1 | |
| 1923 @end example | |
| 1924 | |
| 17274 | 1925 This directory line indicates that @file{foo-1.0.tar.gz} and |
| 1926 @file{foo-1.0.tar.gz.sig} are part of package @code{bar}. If you were to | |
| 4958 | 1927 upload the triplet to @file{/incoming/ftp}, and the system can |
| 1928 positively authenticate the signatures, then the files | |
| 17274 | 1929 @file{foo-1.0.tar.gz} and @file{foo-1.0.tar.gz.sig} will be placed in the |
| 4958 | 1930 directory @file{gnu/bar/v1} of the @code{ftp.gnu.org} site. |
| 1931 | |
| 1932 The directive file can be used to create currently non-existent | |
| 1933 directory trees, as long as they are under the package directory for | |
| 1934 your package (in the example above, that is @code{bar}). | |
| 1935 | |
| 1936 | |
| 1937 @node Announcements | |
| 1938 @section Announcing Releases | |
| 10642 | 1939 @cindex announcements |
| 4958 | 1940 |
| 10642 | 1941 @cindex @code{info-gnu} mailing list |
| 9639 | 1942 When you have a new release, please make an announcement. For |
| 1943 official new releases, including those made just to fix bugs, we | |
| 10642 | 1944 strongly recommend using the (moderated) general GNU announcements |
| 1945 list, @email{info-gnu@@gnu.org}. Doing so makes it easier for users | |
| 1946 and developers to find the latest GNU releases. On the other hand, | |
| 11396 | 1947 please do not announce test releases on @code{info-gnu} unless it's a |
| 1948 highly unusual situation. | |
| 4958 | 1949 |
| 10642 | 1950 @cindex @url{http://planet.gnu.org} |
| 1951 @cindex Savannah, news area | |
| 1952 Please also post release announcements in the news section of your | |
| 13289 | 1953 Savannah project site. Here, it is fine to also write news entries |
| 1954 for test releases and any other newsworthy events. The news feeds | |
| 1955 from all GNU projects at savannah are aggregated at | |
| 1956 @url{http://planet.gnu.org} (GNU Planet). You can also post items | |
| 1957 directly, or arrange for feeds from other locations; see information | |
| 1958 on the GNU Planet web page. | |
| 10642 | 1959 |
| 1960 @cindex announcement mailing list, project-specific | |
| 10299 | 1961 You can maintain your own mailing list (typically |
| 16712 | 1962 @indicateurl{info-@var{package}@@gnu.org}) for announcements as well if you |
| 11396 | 1963 like. For your own list, of course you decide as you see fit what |
| 13289 | 1964 events are worth announcing. (@xref{Mail}, for setting this up, and |
| 1965 more suggestions on handling mail for your package.) | |
| 4958 | 1966 |
| 11396 | 1967 @cindex contents of announcements |
| 1968 When writing an announcement, please include the following: | |
| 1969 | |
| 1970 @itemize @bullet | |
| 1971 @item | |
| 1972 A very brief description (a few sentences at most) of the general | |
| 1973 purpose of your package. | |
| 1974 | |
| 1975 @item | |
| 1976 Your package's web page (normally | |
| 1977 @indicateurl{http://www.gnu.org/software/@var{package}/}). | |
| 1978 | |
| 1979 @item | |
| 1980 Your package's download location (normally | |
| 1981 @indicateurl{http://ftp.gnu.org/gnu/@var{package}/}). It is also | |
| 13355 | 1982 useful to mention the mirror list at |
| 11396 | 1983 @url{http://www.gnu.org/order/ftp.html}, and that |
| 16712 | 1984 @indicateurl{http://ftpmirror.gnu.org/@var{package/}} will automatically |
| 11396 | 1985 redirect to a nearby mirror. |
| 1986 | |
| 1987 @item | |
| 14242 | 1988 The @t{NEWS} (@pxref{NEWS File,,, standards, GNU Coding Standards}) for |
| 11396 | 1989 the present release. |
| 1990 @end itemize | |
| 1991 | |
| 17274 | 1992 You may find the @file{announce-gen} script useful for creating |
| 1993 announcements, which is available from the @file{build-aux/} directory | |
| 1994 of the @code{gnulib} project at | |
| 1995 @url{http://savannah.gnu.org/projects/gnulib}. | |
| 1996 | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
1997 |
| 7720 | 1998 @node Web Pages |
| 4958 | 1999 @chapter Web Pages |
| 2000 @cindex web pages | |
| 2001 | |
| 13230 | 2002 Please write web pages about your package, and install them on |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2003 @code{www.gnu.org}. They should follow our usual standards for web |
| 13230 | 2004 pages (see @url{http://www.gnu.org/server/@/fsf-html-style-sheet.html}). |
| 10299 | 2005 The overall goals are to support a wide variety of browsers, to focus |
| 2006 on information rather than flashy eye candy, and to keep the site | |
| 2007 simple and uniform. | |
| 4958 | 2008 |
| 13289 | 2009 We encourage you to use the standard @code{www.gnu.org} template as |
| 2010 the basis for your pages: | |
| 13380 | 2011 @url{http://www.gnu.org/server/@/standards/@/boilerplate-source.html}. |
| 13289 | 2012 |
| 4958 | 2013 Some GNU packages have just simple web pages, but the more information |
| 2014 you provide, the better. So please write as much as you usefully can, | |
| 2015 and put all of it on @code{www.gnu.org}. However, pages that access | |
| 13289 | 2016 databases (including mail archives and bug tracking) are an exception; |
| 2017 set them up on whatever site is convenient for you, and make the pages | |
| 2018 on @code{www.gnu.org} link to that site. | |
| 4958 | 2019 |
| 11738 | 2020 @menu |
| 2021 * Hosting for Web Pages:: | |
| 2022 * Freedom for Web Pages:: | |
| 2023 * Manuals on Web Pages:: | |
| 2024 * CVS Keywords in Web Pages:: | |
| 2025 @end menu | |
| 2026 | |
| 13289 | 2027 |
| 11738 | 2028 @node Hosting for Web Pages |
| 2029 @section Hosting for Web Pages | |
| 17142 | 2030 @cindex web pages, hosting for |
| 11738 | 2031 |
| 2032 The best way to maintain the web pages for your project is to register | |
| 2033 the project on @code{savannah.gnu.org}. Then you can edit the pages | |
| 2034 using CVS, using the separate ``web repository'' available on | |
| 2035 Savannah, which corresponds to | |
| 2036 @indicateurl{http://www.gnu.org/software/@var{package}/}. You can | |
| 2037 keep your source files there too (using any of a variety of version | |
| 2038 control systems), but you can use @code{savannah.gnu.org} only for | |
| 2039 your gnu.org web pages if you wish; simply register a ``web-only'' | |
| 2040 project. | |
| 2041 | |
| 2042 If you don't want to use that method, please talk with | |
| 2043 @email{webmasters@@gnu.org} about other possible methods. For | |
| 2044 instance, you can mail them pages to install, if necessary. But that | |
| 2045 is more work for them, so please use Savannah if you can. | |
| 2046 | |
| 13230 | 2047 If you use Savannah, you can use a special file named @file{.symlinks} |
| 2048 in order to create symbolic links, which are not supported in CVS. | |
| 2049 For details, see | |
| 11738 | 2050 @url{http://www.gnu.org/server/standards/README.webmastering.html#symlinks}. |
| 2051 | |
| 2052 | |
| 2053 @node Freedom for Web Pages | |
| 2054 @section Freedom for Web Pages | |
| 17142 | 2055 @cindex web pages, freedom for |
| 4958 | 2056 |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2057 If you use a site other than @code{www.gnu.org}, please make sure that |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2058 the site runs on free software alone. (It is ok if the site uses |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2059 unreleased custom software, since that is free in a trivial sense: |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2060 there's only one user and it has the four freedoms.) If the web site |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2061 for a GNU package runs on non-free software, the public will see this, |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2062 and it will have the effect of granting legitimacy to the non-free |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2063 program. |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2064 |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2065 If you use multiple sites, they should all follow that criterion. |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2066 Please don't link to a site that is about your package, which the |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2067 public might perceive as connected with it and reflecting the position |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2068 of its developers, unless it follows that criterion. |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2069 |
| 11738 | 2070 Historically, web pages for GNU packages did not include GIF images, |
| 2071 because of patent problems (@pxref{Ethical and Philosophical | |
| 2072 Consideration}). Although the GIF patents expired in 2006, using GIF | |
| 2073 images is still not recommended, as the PNG and JPEG formats are | |
| 2074 generally superior. See @url{http://www.gnu.org/philosophy/gif.html}. | |
| 2075 | |
| 2076 | |
| 2077 @node Manuals on Web Pages | |
| 2078 @section Manuals on Web Pages | |
| 17142 | 2079 @cindex web pages, including manuals on |
| 2080 @cindex formats for documentation, desired | |
| 11738 | 2081 |
| 4958 | 2082 The web pages for the package should include its manuals, in HTML, |
| 17142 | 2083 DVI, Info, PDF, plain ASCII, and the source Texinfo. All of these can |
| 2084 be generated automatically from Texinfo using Makeinfo and other | |
| 2085 programs. If the Texinfo itself is generated from some other source | |
| 2086 format, include that too. | |
| 11738 | 2087 |
| 2088 When there is only one manual, put it in a subdirectory called | |
| 2089 @file{manual}; the file @file{manual/index.html} should have a link to | |
| 2090 the manual in each of its forms. | |
| 4958 | 2091 |
| 2092 If the package has more than one manual, put each one in a | |
| 2093 subdirectory of @file{manual}, set up @file{index.html} in each | |
| 2094 subdirectory to link to that manual in all its forms, and make | |
| 2095 @file{manual/index.html} link to each manual through its subdirectory. | |
| 2096 | |
| 2097 See the section below for details on a script to make the job of | |
| 2098 creating all these different formats and index pages easier. | |
| 2099 | |
| 13230 | 2100 We would like to list all GNU manuals on the page |
| 2101 @url{http://www.gnu.org/manual}, so if yours isn't there, please send | |
| 2102 mail to @code{webmasters@@gnu.org}, asking them to add yours, and they | |
| 2103 will do so based on the contents of your @file{manual} directory. | |
| 4958 | 2104 |
| 2105 @menu | |
| 2106 * Invoking gendocs.sh:: | |
| 2107 @end menu | |
| 2108 | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2109 |
| 7720 | 2110 @node Invoking gendocs.sh |
| 11738 | 2111 @subsection Invoking @command{gendocs.sh} |
| 4958 | 2112 @pindex gendocs.sh |
| 2113 @cindex generating documentation output | |
| 17142 | 2114 @cindex documentation output, generating |
| 4958 | 2115 |
| 2116 The script @command{gendocs.sh} eases the task of generating the | |
| 2117 Texinfo documentation output for your web pages | |
| 2118 section above. It has a companion template file, used as the basis | |
| 6946 | 2119 for the HTML index pages. Both are available from the Texinfo CVS |
| 4958 | 2120 sources: |
|
10991
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2121 |
|
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2122 @smallformat |
| 4958 | 2123 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs.sh} |
| 2124 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template} | |
|
10991
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2125 @end smallformat |
| 4958 | 2126 |
|
10991
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2127 There is also a minimalistic template, available from: |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2128 |
|
10991
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2129 @smallformat |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2130 @uref{http://savannah.gnu.org/cgi-bin/viewcvs/texinfo/texinfo/util/gendocs_template_min} |
|
10991
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2131 @end smallformat |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2132 |
| 4958 | 2133 Invoke the script like this, in the directory containing the Texinfo |
| 2134 source: | |
|
10991
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2135 |
|
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2136 @smallexample |
|
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2137 gendocs.sh --email @var{yourbuglist} @var{yourmanual} "GNU @var{yourmanual} manual" |
|
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2138 @end smallexample |
| 4958 | 2139 |
|
10991
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2140 @noindent where @var{yourmanual} is the short name for your package |
| 15793 | 2141 and @var{yourbuglist} is the email address for bug reports (which |
| 2142 should be @code{bug-@var{package}@@gnu.org}). The script processes | |
| 2143 the file @file{@var{yourmanual}.texinfo} (or @file{.texi} or | |
| 2144 @file{.txi}). For example: | |
| 4958 | 2145 |
|
10991
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2146 @smallexample |
| 15793 | 2147 cd .../texinfo/doc |
| 4958 | 2148 # download gendocs.sh and gendocs_template |
| 15793 | 2149 gendocs.sh --email bug-texinfo@@gnu.org texinfo "GNU Texinfo manual" |
|
10991
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2150 @end smallexample |
| 4958 | 2151 |
| 2152 @command{gendocs.sh} creates a subdirectory @file{manual/} containing | |
| 2153 the manual generated in all the standard output formats: Info, HTML, | |
| 2154 DVI, and so on, as well as the Texinfo source. You then need to move | |
| 2155 all those files, retaining the subdirectories, into the web pages for | |
| 2156 your package. | |
| 2157 | |
| 2158 You can specify the option @option{-o @var{outdir}} to override the | |
| 2159 name @file{manual}. Any previous contents of @var{outdir} will be deleted. | |
| 2160 | |
| 2161 The second argument, with the description, is included as part of the | |
| 2162 HTML @code{<title>} of the overall @file{manual/index.html} file. It | |
| 2163 should include the name of the package being documented, as shown. | |
| 2164 @file{manual/index.html} is created by substitution from the file | |
| 2165 @file{gendocs_template}. (Feel free to modify the generic template | |
| 2166 for your own purposes.) | |
| 2167 | |
| 2168 If you have several manuals, you'll need to run this script several | |
| 2169 times with different arguments, specifying a different output | |
| 2170 directory with @option{-o} each time, and moving all the output to | |
| 2171 your web page. Then write (by hand) an overall index.html with links | |
| 2172 to them all. For example: | |
|
10991
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2173 |
|
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2174 @smallexample |
| 4958 | 2175 cd .../texinfo/doc |
|
10991
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2176 gendocs.sh --email bug-texinfo@@gnu.org -o texinfo texinfo "GNU Texinfo manual" |
|
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2177 gendocs.sh --email bug-texinfo@@gnu.org -o info info "GNU Info manual" |
|
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2178 gendocs.sh --email bug-texinfo@@gnu.org -o info-stnd info-stnd "GNU info-stnd manual" |
|
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2179 @end smallexample |
| 4958 | 2180 |
| 17064 | 2181 By default, the script uses @command{makeinfo} for generating HTML |
| 2182 output. If you prefer to use @command{texi2html}, use the | |
| 2183 @option{--texi2html} command line option, e.g.: | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2184 |
|
10991
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2185 @smallexample |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2186 gendocs --texi2html -o texinfo texinfo "GNU Texinfo manual" |
|
10991
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2187 @end smallexample |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2188 |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2189 The template files will automatically produce entries for additional |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2190 HTML output generated by @command{texi2html} (i.e., split by sections |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2191 and chapters). |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2192 |
| 4958 | 2193 You can set the environment variables @env{MAKEINFO}, @env{TEXI2DVI}, |
| 17142 | 2194 etc., to control the programs that get executed, and |
| 2195 @env{GENDOCS_TEMPLATE_DIR} to control where the | |
| 4958 | 2196 @file{gendocs_template} file is found. |
| 2197 | |
|
10991
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2198 As usual, run @samp{gendocs.sh --help} for a description of all the |
|
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2199 options, environment variables, and more information. |
|
6a44f8868a74
autoupdate (for gendocs.sh accepting --email)
Karl Berry <karl@freefriends.org>
parents:
10817
diff
changeset
|
2200 |
| 4958 | 2201 Please email bug reports, enhancement requests, or other |
| 17142 | 2202 correspondence about @command{gendocs} to @email{bug-texinfo@@gnu.org}. |
| 4958 | 2203 |
| 2204 | |
| 5011 | 2205 @node CVS Keywords in Web Pages |
| 2206 @section CVS Keywords in Web Pages | |
|
11480
43db6feede26
remove trailing whitespace to placate Jim, more license syncs
Karl Berry <karl@freefriends.org>
parents:
11396
diff
changeset
|
2207 @cindex CVS keywords in web pages |
|
43db6feede26
remove trailing whitespace to placate Jim, more license syncs
Karl Berry <karl@freefriends.org>
parents:
11396
diff
changeset
|
2208 @cindex RCS keywords in web pages |
| 5011 | 2209 @cindex $ keywords in web pages |
|
11480
43db6feede26
remove trailing whitespace to placate Jim, more license syncs
Karl Berry <karl@freefriends.org>
parents:
11396
diff
changeset
|
2210 @cindex web pages, and CVS keywords |
| 5011 | 2211 |
| 2212 Since @code{www.gnu.org} works through CVS, CVS keywords in your | |
| 2213 manual, such as @code{@w{$}Log$}, need special treatment (even if you | |
| 2214 don't happen to maintain your manual in CVS). | |
| 2215 | |
| 2216 If these keywords end up in the generated output as literal strings, | |
| 2217 they will be expanded. The most robust way to handle this is to turn | |
| 2218 off keyword expansion for such generated files. For existing files, | |
| 2219 this is done with: | |
| 2220 | |
| 2221 @example | |
| 2222 cvs admin -ko @var{file1} @var{file2} ... | |
| 2223 @end example | |
| 2224 | |
| 2225 @noindent | |
| 2226 For new files: | |
| 2227 | |
| 2228 @example | |
| 2229 cvs add -ko @var{file1} @var{file2} ... | |
| 2230 @end example | |
| 2231 | |
| 13440 | 2232 @c The CVS manual is now built with numeric references and no nonsplit |
| 2233 @c form, so it's not worth trying to give a direct link. | |
| 2234 See the ``Keyword Substitution'' section in the CVS manual, available | |
| 2235 at @url{http://ximbiot.com/cvs/manual}. | |
| 5011 | 2236 |
| 2237 In Texinfo source, the recommended way to literally specify a | |
| 2238 ``dollar'' keyword is: | |
| 2239 | |
| 2240 @example | |
| 2241 @@w@{$@}Log$ | |
| 2242 @end example | |
| 2243 | |
| 2244 The @code{@@w} prevents keyword expansion in the Texinfo source | |
| 2245 itself. Also, @code{makeinfo} notices the @code{@@w} and generates | |
| 2246 output avoiding the literal keyword string. | |
| 2247 | |
| 2248 | |
| 7720 | 2249 @node Ethical and Philosophical Consideration |
| 4958 | 2250 @chapter Ethical and Philosophical Consideration |
| 2251 @cindex ethics | |
| 2252 @cindex philosophy | |
| 2253 | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2254 The GNU project takes a strong stand for software freedom. Many |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2255 times, this means you'll need to avoid certain technologies when their |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2256 use would conflict with our long-term goals. |
| 4958 | 2257 |
| 2258 Software patents threaten the advancement of free software and freedom | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2259 to program. There are so many software patents in the US that any |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2260 large program probably implements hundreds of patented techniques, |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2261 unknown to the program's developers. It would be futile and |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2262 self-defeating to try to find and avoid all these patents. But there |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2263 are some patents which we know are likely to be used to threaten free |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2264 software, so we make an effort to avoid the patented techniques. If |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2265 you are concerned about the danger of a patent and would like advice, |
| 13230 | 2266 write to @email{licensing@@gnu.org}, and we will try to help you get |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2267 advice from a lawyer. |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2268 |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2269 Sometimes the GNU project takes a strong stand against a particular |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2270 patented technology in order to encourage society to reject it. |
| 4958 | 2271 |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2272 For example, the MP3 audio format is covered by a software patent in |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2273 the USA and some other countries. A patent holder has threatened |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2274 lawsuits against the developers of free programs (these are not GNU |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2275 programs) to produce and play MP3, and some GNU/Linux distributors are |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2276 afraid to include them. Development of the programs continues, but we |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2277 campaign for the rejection of MP3 format in favor of Ogg Vorbis format. |
| 4958 | 2278 |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2279 A GNU package should not recommend use of any non-free program, nor |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2280 should it require a non-free program (such as a non-free compiler or |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2281 IDE) to build. Thus, a GNU package cannot be written in a programming |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2282 language that does not have a free software implementation. Now that |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2283 GNU/Linux systems are widely available, all GNU packages should |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2284 provide full functionality on a 100% free GNU/Linux system, and should |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2285 not require any non-free software to build or function. |
|
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2286 The GNU Coding Standards say a lot more about this issue. |
| 4958 | 2287 |
| 2288 A GNU package should not refer the user to any non-free documentation | |
| 2289 for free software. The need for free documentation to come with free | |
| 2290 software is now a major focus of the GNU project; to show that we are | |
| 2291 serious about the need for free documentation, we must not contradict | |
| 2292 our position by recommending use of documentation that isn't free. | |
| 2293 | |
| 17328 | 2294 Please don't host discussions about your package in a service that |
| 2295 requires nonfree software. For instance, Google+ ``communities'' | |
| 2296 require running a nonfree Javascript program to post a message, so | |
| 2297 they can't be used in the Free World. To host discussions there would | |
| 2298 be excluding people who live by free software principles. | |
| 2299 | |
| 2300 Of course, you can't order people not to use such services to talk | |
| 2301 with each other. What you can do is not legitimize them, and use your | |
| 2302 influence to lead people away from them. For instance, where you say | |
| 2303 where to have discussions related to the program, don't list such a | |
| 2304 place. | |
| 2305 | |
| 4958 | 2306 Finally, new issues concerning the ethics of software freedom come up |
| 2307 frequently. We ask that GNU maintainers, at least on matters that | |
| 2308 pertain specifically to their package, stand with the rest of the GNU | |
| 2309 project when such issues come up. | |
| 2310 | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2311 |
| 4958 | 2312 @node Terminology |
| 2313 @chapter Terminology Issues | |
| 2314 @cindex terminology | |
| 2315 | |
| 2316 This chapter explains a couple of issues of terminology which are | |
| 2317 important for correcting two widespread and important misunderstandings | |
| 2318 about GNU. | |
| 2319 | |
| 2320 @menu | |
| 6710 | 2321 * Free Software and Open Source:: |
| 2322 * GNU and Linux:: | |
| 4958 | 2323 @end menu |
| 2324 | |
| 2325 @node Free Software and Open Source | |
| 2326 @section Free Software and Open Source | |
| 15335 | 2327 @cindex free software movement |
| 4958 | 2328 @cindex open source |
| 15335 | 2329 @cindex movement, free software |
| 2330 @cindex development method, open source | |
| 2331 | |
| 2332 The terms ``free software'' and ``open source'', while describing | |
| 2333 almost the same category of software, stand for views based on | |
| 2334 fundamentally different values. The free software movement is | |
| 2335 idealistic, and raises issues of freedom, ethics, principle and what | |
| 2336 makes for a good society. The term open source, initiated in 1998, is | |
| 2337 associated with a philosophy which studiously avoids such questions. | |
| 2338 For a detailed explanation, see | |
| 2339 @url{http://www.gnu.org/philosophy/open-source-misses-the-point.html}. | |
| 2340 | |
| 2341 The GNU Project is aligned with the free software movement. This | |
| 4958 | 2342 doesn't mean that all GNU contributors and maintainers have to agree; |
| 2343 your views on these issues are up to you, and you're entitled to express | |
| 2344 them when speaking for yourself. | |
| 2345 | |
| 15335 | 2346 However, due to the much greater publicity that the term ``open source'' |
| 2347 receives, the GNU Project needs to overcome a widespread | |
| 2348 mistaken impression that GNU is @emph{and always was} an ``open | |
| 2349 source'' activity. For this reason, please use the term ``free | |
| 9554 | 2350 software'', not ``open source'', in GNU software releases, GNU |
| 4958 | 2351 documentation, and announcements and articles that you publish in your |
| 2352 role as the maintainer of a GNU package. A reference to the URL given | |
| 5097 | 2353 above, to explain the difference, is a useful thing to include as |
| 2354 well. | |
| 4958 | 2355 |
| 15335 | 2356 |
| 4958 | 2357 @node GNU and Linux |
| 2358 @section GNU and Linux | |
| 2359 @cindex Linux | |
| 2360 @cindex GNU/Linux | |
| 2361 | |
| 2362 The GNU Project was formed to develop a free Unix-like operating system, | |
| 2363 GNU. The existence of this system is our major accomplishment. | |
| 2364 However, the widely used version of the GNU system, in which Linux is | |
| 2365 used as the kernel, is often called simply ``Linux''. As a result, most | |
| 2366 users don't know about the GNU Project's major accomplishment---or more | |
| 2367 precisely, they know about it, but don't realize it is the GNU Project's | |
| 2368 accomplishment and reason for existence. Even people who believe they | |
| 2369 know the real history often believe that the goal of GNU was to develop | |
| 15793 | 2370 ``tools'' or ``utilities''. |
| 4958 | 2371 |
| 2372 To correct this confusion, we have made a years-long effort to | |
| 2373 distinguish between Linux, the kernel that Linus Torvalds wrote, and | |
| 2374 GNU/Linux, the operating system that is the combination of GNU and | |
| 2375 Linux. The resulting increased awareness of what the GNU Project has | |
| 2376 already done helps every activity of the GNU Project recruit more | |
| 2377 support and contributors. | |
| 2378 | |
| 2379 Please make this distinction consistently in GNU software releases, GNU | |
| 2380 documentation, and announcements and articles that you publish in your | |
| 2381 role as the maintainer of a GNU package. If you want to explain the | |
| 2382 terminology and its reasons, you can refer to the URL | |
| 2383 @url{http://www.gnu.org/gnu/linux-and-gnu.html}. | |
| 2384 | |
| 16186 | 2385 To make it clear that Linux is a kernel, not an operating system, |
| 2386 please take care to avoid using the term ``Linux system'' in those | |
| 2387 materials. If you want to have occasion to make a statement about | |
| 2388 systems in which the kernel is Linux, write ``systems in which the | |
| 2389 kernel is Linux'' or ``systems with Linux as the kernel.'' That | |
| 2390 explicitly contrasts the system and the kernel, and will help readers | |
| 2391 understand the difference between the two. Please avoid simplified | |
| 2392 forms such as ``Linux-based systems'' because those fail to highlight | |
| 2393 the difference between the kernel and the system, and could encourage | |
| 2394 readers to overlook the distinction. | |
| 2395 | |
| 9554 | 2396 To contrast the GNU system properly with respect to GNU/Linux, you can |
| 15793 | 2397 call it ``GNU/Hurd'' or ``the GNU/Hurd system''. However, when that |
| 4958 | 2398 contrast is not specifically the focus, please call it just ``GNU'' or |
| 15793 | 2399 ``the GNU system''. |
| 4958 | 2400 |
| 2401 When referring to the collection of servers that is the higher level | |
| 15793 | 2402 of the GNU kernel, please call it ``the Hurd'' or ``the GNU Hurd''. |
| 4958 | 2403 Note that this uses a space, not a slash. |
| 2404 | |
| 16856 | 2405 |
| 16853 | 2406 @node Interviews and Speeches |
| 2407 @chapter Interviews and Speeches | |
| 2408 | |
| 2409 Interviews and speeches about your package are an important channel | |
| 2410 for informing the public about the GNU system and the ideas of the | |
| 2411 free software movement. Please avoid saying ``open source'' and avoid | |
| 2412 calling the GNU system ``Linux'', just as you would in the package | |
| 2413 itself (@pxref{Terminology}). Likewise, avoid promoting nonfree | |
| 2414 programs (@pxref{References,,, standards, GNU Coding | |
| 2415 Standards}) as you would in the package itself. | |
| 2416 | |
| 2417 Many GNU users have erroneous ideas about GNU. Outside of our | |
| 2418 community, most people think it is Linux. Please use your opportunity | |
| 2419 to set them straight. Start the presentation with the answers to | |
| 2420 these basic questions: | |
| 2421 | |
| 2422 @itemize @bullet | |
| 2423 @item | |
| 2424 What GNU is (an operating system developed to be Unix-like and totally | |
| 16856 | 2425 free software). It is good to mention @url{http://www.gnu.org}. |
| 16853 | 2426 |
| 2427 @item | |
| 2428 What free software is (the users control it, so it doesn't control | |
| 2429 them). It is good to state the four freedoms and/or refer to | |
| 16856 | 2430 @url{http://www.gnu.org/philosophy/free-sw.html}. |
| 16853 | 2431 |
| 2432 @item | |
| 2433 What GNU/Linux is (Linux filled the last gap in GNU). It is useful to | |
| 16856 | 2434 refer to @url{http://www.gnu.org/gnu/linux-and-gnu.html}. |
| 16853 | 2435 |
| 2436 @item | |
| 2437 What the GNU Project is (the project to develop GNU). | |
| 2438 | |
| 2439 @item | |
| 2440 How your package fits in (it's part of GNU, and the work is part of | |
| 2441 the GNU Project). | |
| 2442 @end itemize | |
| 2443 | |
| 2444 If you feel a social pressure not to say these things, you may be | |
| 2445 coming in contact with some who would prefer that these things not be | |
| 2446 said. That's precisely when we need your support most. | |
| 2447 | |
| 2448 Please don't include advertisements or plugs for any company, product | |
| 2449 or service. Even if the product would meet the standards for the FSF | |
| 2450 to endorse it, an ad for it is out of place in a presentation about a | |
| 2451 GNU package. Likewise, please don't include company slogans. Mention | |
| 2452 a company only when called for by the subject matter. | |
| 2453 | |
| 2454 A few GNU packages are actually business activities of a particular | |
| 2455 company. In that case, it is ok to say so at the start. Otherwise, | |
| 2456 please show that this is a project of the GNU Project, and avoid | |
| 2457 suggesting it is any company's project. | |
| 2458 | |
| 2459 If you are paid by a company to work on the GNU package, it is | |
| 2460 appropriate to thank the company in a discreet way, but please don't | |
| 2461 go beyond that. | |
| 2462 | |
| 2463 Before you do a speech or interview, please contact the GNU Project | |
| 2464 leadership. We can give you advice on how to deal with various | |
| 2465 eventualities. | |
| 2466 | |
| 2467 When your interviews and speech recordings or transcript are posted, | |
| 2468 please tell us about them. Then we can publicize them. | |
| 2469 | |
| 2470 Please post them in formats that are friendly to free software: not in | |
| 2471 Doc or Docx format, not with Flash, not with QuickTime, not with MP3, | |
| 2472 MPEG2 or MPEG4. Plain text, HTML and PDF are good. | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2473 |
| 7720 | 2474 @node Hosting |
| 4958 | 2475 @chapter Hosting |
| 2476 @cindex CVS repository | |
| 2477 @cindex repository | |
| 9639 | 2478 @cindex source repository |
| 2479 @cindex version control system | |
| 4958 | 2480 @cindex FTP site |
| 13355 | 2481 @cindex release site |
| 4958 | 2482 @cindex hosting |
| 2483 | |
| 9639 | 2484 We recommend using @code{savannah.gnu.org} for the source code |
| 13340 | 2485 repository for your package, but that's not required. @xref{Old |
| 2486 Versions}, for more information about Savannah. | |
| 9639 | 2487 |
| 13355 | 2488 We strongly urge you to use @code{ftp.gnu.org} as the standard |
| 15579 | 2489 distribution site for releases. Doing so makes it easier for |
| 2490 developers and users to find the latest GNU releases. However, it is | |
| 2491 ok to use another server if you wish, provided it allows access from | |
| 2492 the general public without limitation (for instance, without excluding | |
| 2493 any country). | |
| 13340 | 2494 |
| 2495 If you use a company's machine to hold the repository for your | |
| 15579 | 2496 program, or as its release distribution site, please put this |
| 2497 statement in a prominent place on the site, so as to prevent people | |
| 2498 from getting the wrong idea about the relationship between the package | |
| 2499 and the company: | |
| 4958 | 2500 |
| 2501 @smallexample | |
| 2502 The programs <list of them> hosted here are free software packages | |
| 2503 of the GNU Project, not products of <company name>. We call them | |
| 2504 "free software" because you are free to copy and redistribute them, | |
| 2505 following the rules stated in the license of each package. For more | |
| 2506 information, see http://www.gnu.org/philosophy/free-sw.html. | |
| 2507 | |
| 2508 If you are looking for service or support for GNU software, see | |
| 13829 | 2509 http://www.gnu.org/gethelp/ for suggestions of where to ask. |
| 4958 | 2510 |
| 2511 If you would like to contribute to the development of one of these | |
| 2512 packages, contact the package maintainer or the bug-reporting address | |
| 2513 of the package (which should be listed in the package itself), or look | |
| 2514 on www.gnu.org for more information on how to contribute. | |
| 2515 @end smallexample | |
| 2516 | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2517 |
| 13857 | 2518 @node Donations |
| 2519 @chapter Donations | |
| 2520 @cindex Donations, for packages | |
| 2521 @cindex Money, donated to packages | |
| 2522 | |
| 2523 As a maintainer, you might want to accept donations for your work, | |
| 2524 especially if you pay for any of your own hosting/development | |
| 13894 | 2525 infrastructure. Following is some text you can adapt to your own |
| 2526 situation, and use on your package's web site, @file{README}, or | |
| 2527 in wherever way you find it useful: | |
| 13857 | 2528 |
| 2529 @smallexample | |
| 2530 We appreciate contributions of any size -- donations enable us to spend | |
| 2531 more time working on the project, and help cover our infrastructure | |
| 2532 expenses. | |
| 2533 | |
| 13894 | 2534 If you'd like to make a small donation, please visit @var{url1} and do |
| 13873 | 2535 it through @var{payment-service}. Since our project isn't a |
| 2536 tax-exempt organization, we can't offer you a tax deduction, but for | |
| 13894 | 2537 all donations over @var{amount1}, we'd be happy to recognize your |
| 2538 contribution on @var{url2}. | |
| 13857 | 2539 |
| 13894 | 2540 We are also happy to consider making particular improvements or |
| 2541 changes, or giving specific technical assistance, in return for a | |
| 2542 substantial donation over @var{amount2}. If you would like to discuss | |
| 2543 this possibility, write to us at @var{address}. | |
| 2544 | |
| 2545 Another possibility is to pay a software maintenance fee. Again, | |
| 2546 write to us about this at @var{address} to discuss how much you want | |
| 2547 to pay and how much maintenance we can offer in return. If you pay | |
| 2548 more than @var{amount1}, we can give you a document for your records. | |
| 13857 | 2549 |
| 2550 Thanks for your support! | |
| 2551 @end smallexample | |
| 2552 | |
| 13873 | 2553 We don't recommend any specific payment service. However, GNU |
| 2554 developers should not use a service that requires them to sign a | |
| 2555 proprietary software license, such as Google's payment service. | |
| 2556 | |
| 17328 | 2557 The FSF can collect donations for a limited number of projects; if you |
| 2558 want to propose that for your project, write to | |
| 2559 @email{maintainers@@gnu.org}. The FSF is required to supervise the | |
| 2560 spending of these funds. | |
| 2561 | |
| 2562 Of course, it is also good to encourage people to join the FSF | |
| 2563 (@url{http://www.fsf.org}) or make a general donation, either instead | |
| 2564 of or as well as package-specific donations. | |
| 13894 | 2565 |
| 13857 | 2566 |
| 4958 | 2567 @node Free Software Directory |
| 2568 @chapter Free Software Directory | |
| 2569 @cindex Free Software Directory | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2570 @cindex Directory, Free Software |
| 4958 | 2571 |
| 10299 | 2572 The Free Software Directory aims to be a complete list of free |
| 2573 software packages, within certain criteria. Every GNU package should | |
| 2574 be listed there, so please see | |
| 2575 @url{http://www.gnu.org/help/directory.html#adding-entries} for | |
| 2576 information on how to write an entry for your package. Contact | |
| 2577 @email{bug-directory@@gnu.org} with any questions or suggestions for | |
| 2578 the Free Software Directory. | |
| 4958 | 2579 |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2580 |
| 4958 | 2581 @node Using the Proofreaders List |
| 2582 @chapter Using the Proofreaders List | |
| 2583 @cindex proofreading | |
| 2584 | |
| 2585 If you want help finding errors in documentation, | |
| 2586 or help improving the quality of writing, | |
| 2587 or if you are not a native speaker of English | |
| 2588 and want help producing good English documentation, | |
| 2589 you can use the GNU proofreaders mailing list: | |
| 2590 @email{proofreaders@@gnu.org}. | |
| 2591 | |
| 2592 But be careful when you use the list, | |
| 2593 because there are over 200 people on it. | |
| 2594 If you simply ask everyone on the list to read your work, | |
| 2595 there will probably be tremendous duplication of effort | |
| 2596 by the proofreaders, | |
| 2597 and you will probably get the same errors reported 100 times. | |
| 2598 This must be avoided. | |
| 2599 | |
| 2600 Also, the people on the list do not want to get | |
| 2601 a large amount of mail from it. | |
| 2602 So do not ever ask people on the list to send mail to the list! | |
| 2603 | |
| 2604 Here are a few methods that seem reasonable to use: | |
| 2605 | |
| 2606 @itemize @bullet | |
| 2607 @item | |
| 2608 For something small, mail it to the list, | |
| 2609 and ask people to pick a random number from 1 to 20, | |
| 2610 and read it if the number comes out as 10. | |
| 2611 This way, assuming 50% response, some 5 people will read the piece. | |
| 2612 | |
| 2613 @item | |
| 2614 For a larger work, divide your work into around 20 equal-sized parts, | |
| 2615 tell people where to get it, | |
| 2616 and ask each person to pick randomly which part to read. | |
| 2617 | |
| 2618 Be sure to specify the random choice procedure; | |
| 2619 otherwise people will probably use a mental procedure | |
| 2620 that is not really random, | |
| 9077 | 2621 such as ``pick a part near the middle'', |
| 4958 | 2622 and you will not get even coverage. |
| 2623 | |
| 2624 You can either divide up the work physically, into 20 separate files, | |
| 2625 or describe a virtual division, such as by sections | |
| 2626 (if your work has approximately 20 sections). | |
| 2627 If you do the latter, be sure to be precise about it---for example, | |
| 2628 do you want the material before the first section heading | |
| 2629 to count as a section, or not? | |
| 2630 | |
| 2631 @item | |
| 2632 For a job needing special skills, send an explanation of it, | |
| 2633 and ask people to send you mail if they volunteer for the job. | |
| 2634 When you get enough volunteers, send another message to the list saying | |
| 9077 | 2635 ``I have enough volunteers, no more please.'' |
| 4958 | 2636 @end itemize |
| 2637 | |
|
9485
4e0536363af3
* doc/fdl.texi, doc/gpl-3.0.texi, doc/lgpl-3.0.texi:
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>
parents:
9125
diff
changeset
|
2638 |
| 9639 | 2639 @node GNU Free Documentation License |
| 2640 @appendix GNU Free Documentation License | |
| 2641 | |
| 2642 @cindex FDL, GNU Free Documentation License | |
| 2643 @include fdl.texi | |
| 2644 | |
| 2645 | |
| 4958 | 2646 @node Index |
| 2647 @unnumbered Index | |
| 2648 @printindex cp | |
| 2649 | |
| 2650 @bye | |
| 2651 | |
| 2652 Local variables: | |
| 2653 eval: (add-hook 'write-file-hooks 'time-stamp) | |
| 2654 time-stamp-start: "@set lastupdate " | |
| 2655 time-stamp-start: "@set lastupdate " | |
| 2656 time-stamp-end: "$" | |
| 2657 time-stamp-format: "%:b %:d, %:y" | |
| 10299 | 2658 compile-command: "make -C work.m" |
| 4958 | 2659 End: |