aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/articles/contributing/article.sgml
blob: b42ff4fe722ddab1935dcf77a40560ac294d6d1e (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
<?xml version="1.0" encoding="ISO8859-1" standalone="no"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.2-Based Extension//EN"
	"../../../share/sgml/freebsd42.dtd" [
<!ENTITY % entities PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Entity Set//EN" "../../share/sgml/entities.ent">
%entities;
]>

<article lang='en'>
  <articleinfo>
    <title>Contributing to FreeBSD</title>

    <abstract>
      <para>This article describes the different ways in which an
	individual or organization may contribute to the FreeBSD
	Project.</para>
    </abstract>

    <authorgroup>
      <author>
	<firstname>Jordan</firstname>
	<surname>Hubbard</surname>
	<contrib>Contributed by </contrib>
      </author>
    </authorgroup>

    <legalnotice id="trademarks" role="trademarks">
      &tm-attrib.freebsd;
      &tm-attrib.ieee;
      &tm-attrib.general;
    </legalnotice>

    <pubdate>$FreeBSD$</pubdate>

    <releaseinfo>$FreeBSD$</releaseinfo>
  </articleinfo>

  <indexterm><primary>contributing</primary></indexterm>

  <para>So you want to contribute to FreeBSD? That is great!  FreeBSD
    <emphasis>relies</emphasis> on the contributions of its user base
    to survive.  Your contributions are not only appreciated, they are
    vital to FreeBSD's continued growth.</para>

  <para>Contrary to what some people might have you believe, you do
    not need to be a hot-shot programmer or a close personal friend of
    the FreeBSD core team to have your contributions accepted.  A
    large and growing number of international contributors, of greatly
    varying ages and areas of technical expertise, develop FreeBSD.
    There is always more work to be done than there are people
    available to do it, and more help is always appreciated.</para>

  <para>The FreeBSD project is responsible for an entire operating
    system environment, rather than just a kernel or a few scattered
    utilities.  As such, our <filename>TODO</filename> lists span a
    very wide range of tasks: from documentation, beta testing and
    presentation, to the system installer and highly specialized types
    of kernel development.  People of any skill level, in almost any
    area, can almost certainly help the project.</para>

  <para>Commercial entities engaged in FreeBSD-related enterprises are
    also encouraged to contact us.  Do you need a special extension to
    make your product work? You will find us receptive to your
    requests, given that they are not too outlandish.  Are you working
    on a value-added product? Please let us know! We may be able to
    work cooperatively on some aspect of it.  The free software world
    is challenging many existing assumptions about how software is
    developed, sold, and maintained, and we urge you to at least give
    it a second look.</para>

  <sect1 id="contrib-what">
    <title>What Is Needed</title>

    <para>The following list of tasks and sub-projects represents
      something of an amalgam of various <filename>TODO</filename>
      lists and user requests.</para>

    <sect2 id="non-programmer-tasks">
      <title>Ongoing Non-Programmer Tasks</title>

      <para>Many people who are involved in FreeBSD are not
	programmers.  The Project includes documentation writers, Web
	designers, and support people.  All that these people need to
	contribute is an investment of time and a willingness to
	learn.</para>

      <orderedlist>
	<listitem>
	  <para>Read through the FAQ and Handbook periodically.  If
	    anything is badly explained, out of date or even just
	    completely wrong, let us know.  Even better, send us a fix
	    (SGML is not difficult to learn, but there is no objection
	    to ASCII submissions).</para>
	</listitem>

	<listitem>
	  <para>Help translate FreeBSD documentation into your native
	    language.  If documentation already exists for your
	    language, you can help translate additional documents or
	    verify that the translations are up-to-date.  First take a
	    look at the <ulink
	    url="&url.books.fdp-primer;/translations.html">Translations
	    FAQ</ulink> in the FreeBSD Documentation Project Primer.
	    You are not committing yourself to translating every
	    single FreeBSD document by doing this &mdash; as a
	    volunteer, you can do as much or as little translation as
	    you desire.  Once someone begins translating, others
	    almost always join the effort.  If you only have the time
	    or energy to translate one part of the documentation,
	    please translate the installation instructions.</para>
	</listitem>

	<listitem>
	  <para>Read the &a.questions; and &ng.misc;
	    occasionally (or even regularly).  It can be very
	    satisfying to share your expertise and help people solve
	    their problems; sometimes you may even learn something new
	    yourself! These forums can also be a source of ideas for
	    things to work on.</para>
	</listitem>
      </orderedlist>
    </sect2>

    <sect2 id="ongoing-programmer-tasks">
      <title>Ongoing Programmer Tasks</title>

      <para>Most of the tasks listed here require either a
	considerable investment of time, or an in-depth knowledge of
	the FreeBSD kernel, or both.  However, there are also many
	useful tasks which are suitable for <quote>weekend
	  hackers</quote>.</para>

      <orderedlist>
	<listitem>
	  <para>If you run FreeBSD-CURRENT and have a good Internet
	    connection, there is a machine <hostid
	    role="fqdn">current.FreeBSD.org</hostid> which builds a
	    full release once a day&mdash;every now and again, try to
	    install the latest release from it and report any failures
	    in the process.</para>
	</listitem>

	<listitem>
	  <para>Read the &a.bugs;.  There might be a
	    problem you can comment constructively on or with patches
	    you can test.  Or you could even try to fix one of the
	    problems yourself.</para>
	</listitem>

	<listitem>
	  <para>If you know of any bug fixes which have been
	    successfully applied to -CURRENT but have not been merged
	    into -STABLE after a decent interval (normally a couple of
	    weeks), send the committer a polite reminder.</para>
	</listitem>

	<listitem>
	  <para>Move contributed software to
	    <filename class="directory">src/contrib</filename> in the
	    source tree.</para>
	</listitem>

	<listitem>
	  <para>Make sure code in
	    <filename class="directory">src/contrib</filename> is up
	    to date.</para>
	</listitem>

	<listitem>
	  <para>Build the source tree (or just part of it) with extra
	    warnings enabled and clean up the warnings.</para>
	</listitem>

	<listitem>
	  <para>Fix warnings for ports which do deprecated things like
	    using <function>gets()</function> or including
	    <filename>malloc.h</filename>.</para>
	</listitem>

	<listitem>
	  <para>If you have contributed any ports and you had to make
	    &os;-specific changes, send your patches
	    back to the original authors (this will make your life
	    easier when they bring out the next version).</para>
	</listitem>

	<listitem>
	  <para>Get copies of formal standards like &posix;.  You can
	    get some links about these standards at the <ulink
	    url="&url.base;/projects/c99/index.html">FreeBSD
	    C99 &amp; POSIX Standards Conformance Project</ulink> web
	    site.  Compare FreeBSD's behavior to that required by the
	    standard.  If the behavior differs, particularly in subtle
	    or obscure corners of the specification, send in a PR
	    about it.  If you are able, figure out how to fix it and
	    include a patch in the PR.  If you think the standard is
	    wrong, ask the standards body to consider the
	    question.</para>
	</listitem>

	<listitem>
	  <para>Suggest further tasks for this list!</para>
	</listitem>
      </orderedlist>
    </sect2>

    <sect2>
      <title>Work through the PR Database</title>

      <indexterm>
	<primary>problem reports database</primary>
      </indexterm>

      <para>The <ulink
	  url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">FreeBSD
	  PR list</ulink> shows all the current active problem reports
	and requests for enhancement that have been submitted by
	FreeBSD users.  The PR database includes both programmer and
	non-programmer tasks.  Look through the open PRs, and see if
	anything there takes your interest.  Some of these might be
	very simple tasks that just need an extra pair of eyes to look
	over them and confirm that the fix in the PR is a good one.
	Others might be much more complex, or might not even have a
	fix included at all.</para>

      <para>Start with the PRs that have not been assigned to anyone
	else.  If a PR is assigned to someone else, but it looks like
	something you can handle, email the person it is assigned to
	and ask if you can work on it&mdash;they might already have a
	patch ready to be tested, or further ideas that you can
	discuss with them.</para>
    </sect2>

    <sect2>
      <title>Pick one of the items from the <quote>Ideas</quote>
	page</title>

      <para>The <ulink url="&url.base;/projects/ideas/">&os; list of
	  projects and ideas for volunteers</ulink> is also available
	for people willing to contribute to the &os; project.  The
	list is being regularly updated and contains items for both
	programmers and non-programmers with information about each
	project.</para>
    </sect2>
  </sect1>

  <sect1 id="contrib-how">
    <title>How to Contribute</title>

    <para>Contributions to the system generally fall into one or more
      of the following 5 categories:</para>

    <sect2 id="contrib-general">
      <title>Bug Reports and General Commentary</title>

      <para>An idea or suggestion of <emphasis>general</emphasis>
	technical interest should be mailed to the &a.hackers;.
	Likewise, people with an interest in such things (and a
	tolerance for a <emphasis>high</emphasis> volume of mail!) may
	subscribe to the &a.hackers;.
	See <ulink
	url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">The
	FreeBSD Handbook</ulink> for more information about this and
	other mailing lists.</para>

      <para>If you find a bug or are submitting a specific change,
	please report it using the &man.send-pr.1; program or its
	<ulink url="&url.base;/send-pr.html">WEB-based
	equivalent</ulink>.  Try to fill-in each field of the bug
	report.  Unless they exceed 65KB, include any patches directly
	in the report.  If the patch is suitable to be applied to the
	source tree put <literal>[PATCH]</literal> in the synopsis of
	the report.  When including patches, <emphasis>do
	  not</emphasis> use cut-and-paste because cut-and-paste turns
	tabs into spaces and makes them unusable.  When patches are a
	lot larger than 20KB, consider compressing them (eg. with
	&man.gzip.1; or &man.bzip2.1;) and using &man.uuencode.1; to
	include their compressed form in your problem report.</para>

      <para>After filing a report, you should receive confirmation
	along with a tracking number.  Keep this tracking number so
	that you can update us with details about the problem by
	sending mail to &a.bugfollowup;.  Use
	the number as the message subject, e.g.  <literal>"Re:
	kern/3377"</literal>.  Additional information for any bug
	report should be submitted this way.</para>

      <para>If you do not receive confirmation in a timely fashion (3
	days to a week, depending on your email connection) or are,
	for some reason, unable to use the &man.send-pr.1; command,
	then you may ask someone to file it for you by sending mail to
	the &a.bugs;.</para>

      <para>See also <ulink
	  url="&url.articles.problem-reports;/article.html">this
	  article</ulink> on how to write good problem reports.</para>
    </sect2>

    <sect2>
      <title>Changes to the Documentation</title>

      <indexterm>
	<primary>documentation submissions</primary>
      </indexterm>

      <para>Changes to the documentation are overseen by the &a.doc;.
	Please look at the
	<ulink url="&url.books.fdp-primer;/index.html">FreeBSD
	  Documentation Project Primer</ulink> for complete
	instructions.  Send submissions and changes (even small ones
	are welcome!) using &man.send-pr.1; as described in
	<link linkend="contrib-general">Bug Reports and General
	  Commentary</link>.</para>
    </sect2>

    <sect2>
      <title>Changes to Existing Source Code</title>

      <indexterm><primary>FreeBSD-CURRENT</primary></indexterm>

      <para>An addition or change to the existing source code is a
	somewhat trickier affair and depends a lot on how far out of
	date you are with the current state of FreeBSD
	development.  There is a special on-going release of FreeBSD
	known as <quote>FreeBSD-CURRENT</quote> which is made
	available in a variety of ways for the convenience of
	developers working actively on the system.  See
	<ulink url="&url.books.handbook;/current-stable.html">The
	FreeBSD Handbook</ulink> for more information about getting
	and using FreeBSD-CURRENT.</para>

      <para>Working from older sources unfortunately means that your
	changes may sometimes be too obsolete or too divergent for
	easy re-integration into FreeBSD.  Chances of this can be
	minimized somewhat by subscribing to the &a.announce; and the
	&a.current; lists, where discussions on the current state of
	the system take place.</para>

      <para>Assuming that you can manage to secure fairly up-to-date
	sources to base your changes on, the next step is to produce a
	set of diffs to send to the FreeBSD maintainers.  This is done
	with the &man.diff.1; command.</para>

      <para>The preferred &man.diff.1; format for submitting patches
	is the unified output format generated by <command>diff
	  -u</command>.  However, for patches that substantially
	change a region of code, a context output format diff
	generated by <command>diff -c</command> may be more readable
	and thus preferable.</para>

      <indexterm>
	<primary><command>diff</command></primary>
      </indexterm>

      <para>For example:</para>

      <screen>&prompt.user; <userinput>diff -c oldfile newfile</userinput></screen>

      <para>or</para>

      <screen>&prompt.user; <userinput>diff -c -r olddir newdir</userinput></screen>

      <para>would generate such a set of context diffs for the given
	source file or directory hierarchy.</para>

      <para>Likewise,</para>

      <screen>&prompt.user; <userinput>diff -u oldfile newfile</userinput></screen>

      <para>or</para>

      <screen>&prompt.user; <userinput>diff -u -r olddir newdir</userinput></screen>

      <para>would do the same, except in the unified diff
	format.</para>

      <para>See the manual page for &man.diff.1; for more
	details.</para>

      <para>Once you have a set of diffs (which you may test with the
	&man.patch.1; command), you should submit them for inclusion
	with FreeBSD.  Use the &man.send-pr.1; program as described in
	<link linkend="contrib-general">Bug Reports and General
	Commentary</link>.  <emphasis>Do not</emphasis> just send the
	diffs to the &a.hackers; or they will get lost! We greatly
	appreciate your submission (this is a volunteer project!);
	because we are busy, we may not be able to address it
	immediately, but it will remain in the PR database until we
	do.  Indicate your submission by including
	<literal>[PATCH]</literal> in the synopsis of the
	report.</para>

      <indexterm>
	<primary><command>uuencode</command></primary>
      </indexterm>

      <para>If you feel it appropriate (e.g. you have added, deleted,
	or renamed files), bundle your changes into a
	<command>tar</command> file and run the &man.uuencode.1;
	program on it.  Archives created with &man.shar.1; are also
	welcome.</para>

      <para>If your change is of a potentially sensitive nature,
	e.g. you are unsure of copyright issues governing its further
	distribution or you are simply not ready to release it without
	a tighter review first, then you should send it to &a.core;
	directly rather than submitting it with &man.send-pr.1;.  The
	&a.core; reaches a much smaller group of people who
	do much of the day-to-day work on FreeBSD.  Note that this
	group is also <emphasis>very busy</emphasis> and so you should
	only send mail to them where it is truly necessary.</para>

      <para>Please refer to &man.intro.9; and &man.style.9; for
	some information on coding style.  We would appreciate it if
	you were at least aware of this information before submitting
	code.</para>
    </sect2>

    <sect2>
      <title>New Code or Major Value-Added Packages</title>

      <para>In the case of a significant contribution of a large body
	work, or the addition of an important new feature to FreeBSD,
	it becomes almost always necessary to either send changes as
	uuencoded tar files or upload them to a web or FTP site for
	other people to access.  If you do not have access to a web or
	FTP site, ask on an appropriate FreeBSD mailing list for
	someone to host the changes for you.</para>

      <para>When working with large amounts of code, the touchy
	subject of copyrights also invariably comes up.  Acceptable
	copyrights for code included in FreeBSD are:</para>

      <orderedlist>
	<listitem>
	  <indexterm><primary>BSD copyright</primary></indexterm>

	  <para>The BSD copyright.  This copyright is most preferred
	    due to its <quote>no strings attached</quote> nature and
	    general attractiveness to commercial enterprises.  Far
	    from discouraging such commercial use, the FreeBSD Project
	    actively encourages such participation by commercial
	    interests who might eventually be inclined to invest
	    something of their own into FreeBSD.</para>
	</listitem>

	<listitem>
	  <indexterm>
	    <primary>GPL</primary>
	    <see>GNU General Public License</see>
	  </indexterm>

	  <indexterm>
	    <primary>GNU General Public License</primary>
	  </indexterm>

	  <para>The GNU General Public License, or <quote>GPL</quote>.
	    This license is not quite as popular with us due to the
	    amount of extra effort demanded of anyone using the code
	    for commercial purposes, but given the sheer quantity of
	    GPL'd code we currently require (compiler, assembler, text
	    formatter, etc) it would be silly to refuse additional
	    contributions under this license.  Code under the GPL also
	    goes into a different part of the tree, that being
	    <filename class="directory">/sys/gnu</filename> or
	    <filename class="directory">/usr/src/gnu</filename>, and
	    is therefore easily identifiable to anyone for whom the
	    GPL presents a problem.</para>
	</listitem>
      </orderedlist>

      <para>Contributions coming under any other type of copyright
	must be carefully reviewed before their inclusion into FreeBSD
	will be considered.  Contributions for which particularly
	restrictive commercial copyrights apply are generally
	rejected, though the authors are always encouraged to make
	such changes available through their own channels.</para>

      <para>To place a <quote>BSD-style</quote> copyright on your
	work, include the following text at the very beginning of
	every source code file you wish to protect, replacing the text
	between the <literal>%%</literal> with the appropriate
	information:</para>

      <programlisting>Copyright (c) %%proper_years_here%%
        %%your_name_here%%, %%your_state%%  %%your_zip%%.  
	All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer as
   the first lines of this file unmodified.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

        &#36;Id&#36;</programlisting>

      <para>For your convenience, a copy of this text can be found in
	<filename>/usr/share/examples/etc/bsd-style-copyright</filename>.</para>
    </sect2>

    <sect2>
      <title>Money, Hardware or Internet Access</title>

      <para>We are always very happy to accept donations to further
	the cause of the FreeBSD Project and, in a volunteer effort
	like ours, a little can go a long way! Donations of hardware
	are also very important to expanding our list of supported
	peripherals since we generally lack the funds to buy such
	items ourselves.</para>

      <sect3>
	<title><anchor id="donations"/>Donating Funds</title>

	<para>The FreeBSD Foundation is a non-profit, tax-exempt
	  foundation established to further the goals of the FreeBSD
	  Project.  As a 501(c)3 entity, the Foundation is generally
	  exempt from US federal income tax as well as Colorado State
	  income tax.  Donations to a tax-exempt entity are often
	  deductible from taxable federal income.</para>

	<para>Donations may be sent in check form to:
	  <address>
	    The FreeBSD Foundation
	    <street>7321 Brockway Dr.</street>
	    <city>Boulder</city>,
	    <state>CO</state> <postcode>80303</postcode>
	    <country>USA</country>
	  </address></para>

	<para>The FreeBSD Foundation is now able to accept donations
	  through the web with PayPal.  To place a donation, please
	  visit the Foundation
	  <ulink url="http://www.freebsdfoundation.org">web
	    site</ulink>.</para>

	<para>More information about the FreeBSD Foundation can be
	  found in <ulink
	    url="http://people.FreeBSD.org/~jdp/foundation/announcement.html">The
	    FreeBSD Foundation -- an Introduction</ulink>.  To contact
	  the Foundation by email, write to
	  <email>bod@FreeBSDFoundation.org</email>.</para>
      </sect3>

      <sect3>
	<title>Donating Hardware</title>
	<indexterm><primary>donations</primary></indexterm>

	<para>The FreeBSD Project happily accepts donations of
	  hardware that it can find good use for.  If you are
	  interested in donating hardware, please contact the
	  <ulink url="&url.base;/donations/">Donations Liaison
	    Office</ulink>.</para>
      </sect3>

      <sect3>
	<title>Donating Internet Access</title>

	<para>We can always use new mirror sites for FTP, WWW or
	  <command>cvsup</command>.  If you would like to be such a
	  mirror, please see the
	  <ulink url="&url.articles.hubs;/index.html">Mirroring
	    FreeBSD</ulink> article for more information.</para>
      </sect3>
    </sect2>
  </sect1>

</article>