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
|
Thank you for your offer of this driver! It does look like it will be of
use to our many japanese users. I am appending a copy of my standard
"how to submit code to FreeBSD" document below. It hopefully explains
any questions you may have, though please do not hesitate in contacting
me should you have any further questions.
Jordan
-- A submitter's guide to FreeBSD --
This guide is intended for those who are moderately familar with FreeBSD
and are now to the point where they have some locally developed
customizations or fixes to the system which they'd like to incorporate
back into the mainstream sources, thus saving the work of having to
re-integrate the changes for each subsequent FreeBSD release. Submitting
something to the FreeBSD project is also an excellent way of getting your
code seriously *tested*! Many people have developed an original concept
far beyond what they might have envisioned at the start just 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,
and 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
documentation! :-)
Submissions to FreeBSD can generally be classified into four catagories:
1. Ideas, general suggestions, bug reports.
2. Addition, deletion, renaming or patching of existing sources.
3. Significant contribution of a large body of independant work.
4. Porting of freely available software.
A submission in *any* of these catagories is highly welcomed as they
are each, in their own way, quite significant to the project.
1. An idea, suggestion or fix can be communicated in one of the following
ways:
o An idea or suggestion of general technical interest should be
mailed to <hackers@freebsd.org>. Likewise, people with an interest
in such things (and a tolerance for a HIGH volume of mail!) may
subscribe by sendimg mail to <majordomo@freebsd.org>. See also the
file /usr/share/FAQ/mailing-list.FAQ.
o An actual bug report should be filed by using the send-pr(1)
command (``man send-pr'' for information). This will prompt
you for various fields to fill in. Simply go to the fields
surrounded by <>'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 (which you should also reference 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 send-pr command, then you may also
file a bug report (or follow-up to one) by sending mail to:
<bugs@freebsd.org>
2. 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" and made available in a variety of
ways (see /usr/share/FAQ/current-policy.FAQ and /usr/share/FAQ/ctm.FAQ) for
the convenience of developers who wish to actively work on the system.
Working from older sources unfortunately means that your changes may
sometimes be too obsolute to use, or too divergent to allow for easy
re-integration. This can be minimized somewhat by subscribing to the
<announce@freebsd.org> mailing list (among others) where periodic
announcements concerning the current state of the system are made.
If you see a change being proposed for which you have a better solution,
then please, by all means come forward with your contribution and we
will do our very best to evaluate it fairly and perhaps integrate it if
it is indeed a better (or easier :) solution.
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 for evaluation and possible adoption. This is done
with the diff(1) command, with the FreeBSD maintainers preferring to receive
diffs in `context diff' form. See the man page for diff for more details
on producing both context and recursive context diffs
(diff -c <oldfile> <newfile> or diff -c -r <olddir> <newdir>).
Once you have a set of diffs that are capable of taking a copy of the
original code and bringing it to a state identical to the "new" sources
(you may test this with the patch(1) command - see patch man page), you
should bundle them up in an email message and send it, along with a brief
description of what the diffs are for, to <hackers@freebsd.org>. 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 any
others into a tar file and running the `uuencode' program on it before
sending the output of that to <hackers@freebsd.org>. See the man pages
on tar and uuencode for more info on bundling files through the mail 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 <core@freebsd.org> rather than <hackers@freebsd.org>. 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 VERY BUSY and so
you should really only mail to them in cases where mailing to hackers
truly is impractical.
3. 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 (see above)
or upload them to our ftp site:
ftp://freefall.cdrom.com/pub/FreeBSD/incoming
Users may log in anonymously and upload their work or download the
work-in-progress files left by others.
When working with large amounts of code, the touchy subject of copyrights
also invariably comes up. The view of the FreeBSD project towards
acceptable copyrights (for code included in FreeBSD) are:
3a. Contributions under the BSD copyright (see the file
/usr/share/examples/etc/bsd-style-copyright for a template)
is greatly preferred due to its "no strings attached"
nature and general attractiveness to commercial enterprises
who might then be inclined to invest something of their own
into FreeBSD.
3b. Contributions under the GNU Public License, or "GPL". This is
not quite as popular a solution for us, due to (all religious
issues aside) the amount of extra effort demanded of anyone
using the code for commercial purposes. However, given the
sheer quantity of GPL'd code we currently require (compiler,
assembler, text formatter, etc), it would be silly to pretend
that we couldn't deal with the GPL at all and so we have become
more willing to accept code with either the BSD or the GPL
copyright. Code under the GPL also goes into a different part
of the tree, that being /sys/gnu or /usr/src/gnu.
3c. Contributions coming under any other type of copyright must be
carefully reviewed before their inclusion into FreeBSD will even
be considered. Contributions for which particularly restrictive
commercial copyrights apply are generally rejected, though the
authors are always free to make the changes available through
their own channels.
4. The porting of freely available software, while perhaps not as gratifying
as developing your own package 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
hierarchy know as ``the ports collection''. This collection enables
a new user to get a complete overview of what's available in a short time,
and with a logical (we hope) framework. The ports collection also saves
considerable space by not actually containing the the majority of the
sources being ported. This can be confusing to the new user and the file
/usr/share/FAQ/ports.FAQ goes some way towards explaing how it all works.
If you have the ports collection on your machine, the file
/usr/ports/GUIDELINES also helps to explain the process of creating
and contributing a port of your own. For more information on the ports
collection (that wasn't available in the FAQ), you may also send mail to
<ports@freebsd.org>.
Whichever way you decide to contribute, we hope you'll find it an enjoyable
process and also realize how valuable your contributions are to the project!
FreeBSD is one of those great projects where the more we all put in, the
more we all get back out of it again, and with enough steady contributions
it begins to aquire a momentum of its own. It is through such momentum
that mountains are moved! :-)
Jordan
|
