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
|
<!-- $Id: submitters.sgml,v 1.2.4.2 1995-10-12 03:16:37 jfieber Exp $ -->
<!-- The FreeBSD Documentation Project -->
<chapt><heading>Contributing to FreeBSD<label id="submitters"></heading>
<p><em>Contributed by &a.jkh;.</em>
This guide is intended for those who are moderately familiar with
FreeBSD and have reached a point where they have some locally
developed customizations or fixes to the system which they'd like to
incorporate back into the mainstream sources. Submitting something to
the FreeBSD project ensures that you won't have to continually
reintegrate it with each subsequent release and is also an excellent
way of getting your code seriously <em>tested</em>! Many people have
seen an original concept develop far beyond what they might have
originally envisioned simply due to the flood of feedback and ideas
generated by the many thousands of users of FreeBSD. Contributions
are also what FreeBSD lives and grows from, so your contributions are
very important to the continued survival of this communal effort of
ours---we're very glad to see you reading this document!
Submissions to FreeBSD can generally be classified into four categories:
<enum>
<item>Ideas, general suggestions, bug reports.
<item>Changes to existing sources.
<item>Significant contribution of a large body of independent work.
<item>Porting of freely available software.
</enum>
A submission in <em>any</em> of these categories is highly welcomed as they
are each, in their own way, quite significant to the project.
<sect><heading>Ideas and suggestions</heading>
<p>An idea, suggestion or fix can be communicated in one of the following ways:
<itemize>
<item>An idea or suggestion of general technical interest should be
mailed to <tt><hackers@freebsd.org></tt>.
Likewise, people with an interest
in such things (and a tolerance for a <em>high</em>
volume of mail!) may
subscribe to the hackers mailing list by sending mail to
<tt><majordomo@freebsd.org></tt>.
See <ref id="eresources:mail" name="mailing lists">
for more information about this and other mailing lists.
<item>An actual bug report should be filed by using the
<tt>send-pr(1)</tt> program. This will prompt
you for various fields to fill in. Simply go to the fields
surrounded by <tt><></tt>'s and fill in your own
information in place of
what's suggested there. You should receive confirmation of your
bug report and a tracking number. Keep this tracking number and use
it in any subsequent correspondence.
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 <tt>send-pr(1)</tt> command,
then you may also file a bug report by sending mail to
<tt><bugs@freebsd.org></tt>.
</itemize>
<sect><heading>Changes to the existing code</heading>
<p>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 the core FreeBSD development. There is a special on-going release
of FreeBSD known as ``FreeBSD-current'' which is made available in
a variety of ways for the convenience of developers working
actively on the system. See <ref id="current" name="Staying
current with FreeBSD"> for more information about getting and using
FreeBSD-current.
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
<tt><announce@freebsd.org></tt> and
<tt><current@freebsd.org></tt> mailing lists, where discussions
on the current state of the system take place.
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 <tt>diff(1)</tt> command,
with the `context diff' form being preferred. For example:
<tscreen><verb>
diff -c oldfile newfile
</verb></tscreen>
or
<tscreen><verb>
diff -c -r olddir newdir
</verb></tscreen>
would generate such a set of context diffs for the given source file
or directory hierarchy. See the man page for <tt>diff(1)</tt> for more
details.
Once you have a set of diffs (which you may test with the
<tt>patch(1)</tt> command), you should bundle them up in an
email message and send it, along with a brief description of
what the diffs are for, to
<tt><hackers@freebsd.org></tt>. Someone will very
likely get back in touch with you in 24 hours or less,
assuming of course that your diffs are interesting! :-)
If your changes don't express themselves well as diffs alone
(e.g. you've perhaps added, deleted or renamed files as well)
then you may be better off bundling any new files, diffs and
instructions for deleting/renaming others into a <tt>tar</tt>
file and running the <tt>uuencode(1)</tt> program on it before
sending the output of that to <tt><hackers@freebsd.org></tt>.
See the man pages on <tt>tar(1)</tt> and <tt>uuencode(1)</tt> for more
information on bundling files this way.
If your change is of a potentially sensitive nature, e.g.
you're unsure of copyright issues governing its further distribution
or you're simply not ready to release it without a tighter review first,
then you should send it to <tt><core@freebsd.org></tt> rather than
<tt><hackers@freebsd.org></tt>. The core mailing list
reaches a much smaller group of people who do much of the
day-to-day work on FreeBSD. Note that this group is also
<em>very busy</em> and so you should only send mail to them
in cases where mailing to hackers is truly impractical.
<sect><heading>Contributions of new code</heading>
<p>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 our ftp site <url
url="ftp://ftp.freebsd.org/pub/FreeBSD/incoming">.
When working with large amounts of code, the touchy subject of
copyrights also invariably comes up. Acceptable copyrights
for code included in FreeBSD are:
<enum>
<item>The BSD copyright. This copyright is most preferred
due to its ``no strings attached'' 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.
<item>The GNU Public License, or ``GPL''. This license isn't 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
<tt>/sys/gnu</tt> or <tt>/usr/src/gnu</tt>, and is therefore
easily identifiable to anyone for whom the GPL presents a problem.
</enum>
<p>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.
To place a ``BSD-style'' 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 `<tt>%%</tt>' with
the appropriate information.
<tscreen><verb>
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.
3. All advertising materials mentioning features or use of this software
must display the following acknowledgment:
This product includes software developed by %%your_name_here%%.
4. The name of the author may not be used to endorse or promote products
derived from this software without specific prior written permission.
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: submitters.sgml,v 1.2.4.2 1995-10-12 03:16:37 jfieber Exp $
</verb></tscreen>
For your convenience, a copy of this text can be found in
<tt>/usr/share/examples/etc/bsd-style-copyright</tt>.
<sect><heading>Porting of software</heading>
<p>The porting of freely available software, while perhaps not as
gratifying as developing your own from scratch, is still a vital part
of FreeBSD's growth and of great usefulness to those who wouldn't
otherwise know where to turn for it. All ported software is organized
into a carefully organized hierarchy know as ``the ports collection''.
The collection enables a new user to get a quick and complete overview
of what's available for FreeBSD in an easy-to-compile form. It also
saves considerable space by not actually containing the the majority
of the sources being ported, but merely those differences required for
running under FreeBSD. See <ref id="ports" name="The ports
collection"> for more information on using the ports collection and
<ref id="porting" name="Porting applications"> for guidelines on
creating new ports. You may also send mail to
<tt><ports@freebsd.org></tt>.
Whichever way you decide to contribute, we hope you'll find it an
enjoyable and rewarding process. Such contributions are also very
valuable to FreeBSD's continued progress, and as a free software
effort, the more we all put in the more we all get back out of it!
|
