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 — 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—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 & 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—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.
$Id$</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>
|