aboutsummaryrefslogtreecommitdiff
path: root/handbook/submitters.sgml
blob: 16bfdd1b10f96f68bc6faa848ead55aef9a7a8de (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
<!-- $Id: submitters.sgml,v 1.2.4.5 1996-07-16 16:01:35 jkh Exp $ -->
<!-- The FreeBSD Documentation Project -->

<chapt><heading>Contributing to FreeBSD<label id="submitters"></heading>

<p><em>Contributed by &a.jkh;.</em>

<p>So you want to contribute something to FreeBSD?  That is great!
We can always use the help, and FreeBSD is one of those systems
that <em>relies</em> on the contributions of its user base in order
to survive.  Your contributions are not only appreciated, they are
vital to FreeBSD's continued growth!

<p>Contrary to what some people might also have you believe, you do not
need to be a hot-shot programmer or a close personal friend of the
FreeBSD core team in order to have your contributions accepted.  The
FreeBSD Project's development is done by a large and growing number of
international contributors who's ages and areas of technical expertise
vary greatly, and there is always more work to be done than there are
people available to do it.

<p>Since the FreeBSD project is responsible for an entire operating
system environment (and its installation) rather than just a kernel or
a few scattered utilities, our "TODO" list also spans a very wide
range of tasks, from documentation, beta testing and presentation to
highly specialized types of kernel development.  No matter what your
skill level, there is almost certainly something you can do to help the
project!

<p>Commercial entities engaged in FreeBSD-related enterprises are
also encouraged to contact us.  Need a special extension to make your
product work?  You will find us receptive to your requests, given that
they are not too outlandish.  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 a lot of existing
assumptions about how software is developed, sold, and maintained
throughout its life cycle, and we urge you to at least give it a
second look.

<sect><heading>What is needed</heading>

<p>The following list of tasks and sub-projects represents something
of an amalgam of the various core team TODO lists and user requests
we have collected over the last couple of months.  Where possible, tasks
have been ranked by degree of urgency.  If you are interested in
working on one of the tasks you see here, send mail to the coordinator
listed by clicking on their names.  If no coordinator has been
appointed, maybe you would like to volunteer?

<sect1><heading>High priority tasks</heading>
<p>The following tasks are considered to be urgent, usually because
they represent something that is badly broken or sorely needed:
<enum>
<item>3-stage boot issues.  Overall coordination:
&a.hackers
<p><itemize>
<item>Autodetect memory over 64MB properly.
<item>Move userconfig (-c) into 3rd stage boot.
<item>Do WinNT compatible drive tagging so that the 3rd stage can
provide an accurate mapping of BIOS geometries for disks.
</itemize>
<item>Filesystem problems.  Overall coordination:
&a.fs
<itemize>
<item>Fix the MSDOS file system.
<item>Clean up and document the nullfs filesystem code.  Coordinator: &a.gibbs
<item>Fix the union file system.  Coordinator: &a.dyson
<item>Fix the LFS file system.  Coordinator: &a.dyson
</itemize>
<item>Implement kernel and user vm86 support.  Coordinator: &a.hackers
<item>Implement Int13 vm86 disk driver.  Coordinator: &a.hackers
<item>SCSI driver issues.  Overall coordination: &a.hackers
<p><itemize>
<item>Support tagged queuing generically.  Requires a rewrite of how we do
our command queing, but we need this anyway to for prioritized I/O
(CD-R writers/scanners).
<item>Better error handling (Busy status and retries).
<item>Merged Scatter-Gather list creation code.
</itemize>
<item>Kernel issues.  Overall coordination:
&a.hackers
<p><itemize>
<item>Complete the eisaconf conversion of all existing drivers.
<item>Change all interrupt routines to take a (void *) instead of
using unit numbers.
<item>Merge EISA/PCI/ISA interrupt registration code.
<item>Split PCI/EISA/ISA probes out from drivers like bt742a.c (WIP)
<item>Fix the syscons ALT-TAB/vt switching hangs.  Coordinator: &a.sos
<item>Mouse support for syscons.
<item>Merged keyboard code for all console drivers.
<item>Rewrite the Intel Etherexpress 16 driver.
<item>Merge the 3c509 and 3c590 drivers (essentially provide a PCI probe for
ep.c).
<item>Support Adaptec 3985 (first as a simple 3 channel SCSI card)
Coordinator: &a.gibbs
<item>Support Advansys SCSI controller products.  Coordinator: &a.gibbs
</itemize>
</enum>

<sect1><heading>Medium priority tasks</heading>
<p>The following tasks need to be done, but not with any particular
urgency:
<enum>
<item>DOS emulator (for DOS executables)  Coordinator: <tt><htmlurl
url="mailto:jr@jrw.org" name="J.R. Westmoreland"></tt>
<item>Port AFS (Andrew File System) to FreeBSD  Coordinator: <tt><htmlurl
url="mailto:ajones@ctron.com" name="Alexander Seth Jones"></tt>

<item>MCA support?  This should be finalized one way or the other.
<item>Full LKM based driver support/Configuration Manager.
<p><itemize>
<item>Devise a way to do all LKM registration without ld.  This means
some kind of symbol table in the kernel.
<item>Write a configuration manager (in the 3rd stage boot?) that probes
your hardware in a sane manner, keeps only the LKMs required for
your hardware, etc.
</itemize>
<item>PCMCIA/PCCARD.  Coordinators: &a.nate and &a.phk
<itemize>
<item>Documentation!
<item>Reliable operation of the pcic driver (needs testing).
<item>Recognizer and handler for sio.c (mostly done).
<item>Recognizer and handler for ed.c (mostly done).
<item>Recognizer and handler for ep.c (mostly done).
<item>User-mode recognizer and handler (partially done).
</itemize>
<item>Advanced Power Management.  Coordinators: &a.nate and &a.phk
<itemize>
<item>APM sub-driver (mostly done).
<item>IDE/ATA disk sub-driver (partially done).
<item>syscons/pcvt sub-driver.
<item>Integration with the PCMCIA/PCCARD drivers (suspend/resume).
</itemize>
</enum>

<sect1><heading>Low priority tasks</heading>
<p>The following tasks are purely cosmetic or represent such an
investment of work that it is not likely that anyone will get them done
anytime soon:

<p>The first 20 items are from Terry Lambert &lt;terry@lambert.org&gt
<enum>
<item>Ability to make BIOS calls from protected mode using V86 mode
on the processor and return the results via a mapped interrupt
IPC mechanism to the protected mode caller.

<item>Drivers built into the kernel that use the BIOS call mechanism
to allow them to be independent of the actual underlying hardware
the same way that DOS is independent of the underlying hardware.
This includes NetWork and ASPI drivers loaded in DOS prior to
BSD being loaded by a DOS-based loader program, which means
potential polling, which means DOS-not-busy interrupt generation
for V86 machines by the protected mode kernel.

<item>An image format that allows tagging of such drivers data and
text areas in the default kernel executable so that that portion
of the kernel address space may be recovered at a later time,
after hardware specific protected mode drivers have been loaded
and activated.  This includes separation of BIOS based drivers
from each other, since it is better to run with a BIOS based
driver in all cases than to not run at all.

<item>Abstraction of the bus interface mechanism.  Currently, PCMCIA,
EISA, and PCI busses are assumed to be bridged from ISA.  This
is not something which should be assumed.

<item>A configuration manager that knows about PNP events, including
power management events, insertion, extraction, and bus (PNP ISA
and PCMCIA bridging chips) vs. card level event management.

<item>A topological sort mechanism for assigning reassignable addresses
that do not collide with other reassignable and non-reassignable
device space resource usage by fixed devices.

<item>A registration based mechanism for hardware services registration.
Specifically, a device centric registration mechanism for timer
and sound and other system critical service providers.  Consider
Timer2 and Timer0 and speaker services as one example of a single
monolithic service provider.

<item>A kernel exported symbol space in the kernel data space accessible
by an LKM loader mechanism that does relocation and symbol space
manipulation.  The intent of this interface is to support the
ability to demand load and unload kernel modules.

<item>NetWare Server (protected mode ODI driver) loader and subservices
to allow the use of ODI card drivers supplied with network cards.
The same thing for NDIS drivers and NetWare SCSI drivers.

<item>An "upgrade system" option that works on Linux boxes instead
of just previous rev FreeBSD boxes.

<item>Splitting of the console driver into abstraction layers, both to
make it easier to port and to kill the X and ThinkPad and PS/2
mouse and LED and console switching and bouncing NumLock problems
once and for all.

<item>Other kernel emulation environments for other foreign drivers
as opportunity permits.  SCO and Solaris are good candidates,
followed by UnixWare, etc.

<item>Processor emulation environments for execution of foreign binaries.
This is easier than it sounds if the system call interface does not
change much.

<item>Streams to allow the use of commercial streams drivers.

<item>Kernel multithreading (requires kernel preemption).

<item>Symmetric Multiprocessing with kernel preemption (requires kernel
preemption).

<item>A concerted effort at support for portable computers.  This is
somewhat handled by changing PCMCIA bridging rules and power
management event handling.  But there are things like detecting
internal vs. external display and picking a different screen
resolution based on that fact, not spinning down the disk if
the machine is in dock, and allowing dock-based cards to disappear
without affecting the machines ability to boot (same issue for
PCMCIA).

<item>Reorganization of the source tree for multiple platform ports.

<item>A "make world" that "makes the world" (rename the current one
to "make regress" if that is all it is good for).

<item>A 4M (preferably smaller!) memory footprint.

</enum>

<sect><heading>How to contribute</heading>

<p>Contributions to the system generally fall into one or more of
the following 6 categories:

<sect1><heading>Bug reports and general commentary</heading>
<p>If you have a bug to report or a suggestion to make:

<itemize>
	<item>An idea or suggestion of general technical interest should be
	  mailed to the &a.hackers;.
          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 
          &a.majordomo;.
          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>&lt;&gt;</tt>'s and fill in your own 
          information in place of
	  what is 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 the &a.bugs;.
</itemize>

<sect1><heading>Changes to the documentation</heading>

<p>Changes to the documentation are overseen by the &a.doc;.
This does not generally include
changes to manual pages, which should be considered under the category
of "changes to existing source code."

<sect1><heading>Changes to existing source 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
   &a.announce and the &a.current 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 the &a.hackers;.
   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 do not express themselves well as diffs alone
   (e.g. you have 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 the &a.hackers;.
   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 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 <tt><htmlurl url="mailto:core@FreeBSD.ORG"
   name="&lt;core@FreeBSD.ORG&gt;"></tt> rather than the &a.hackers
   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.

<sect1><heading>New code or major value-added packages</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 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
	    <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.5 1996-07-16 16:01:35 jkh Exp $
</verb></tscreen>
For your convenience, a copy of this text can be found in
<tt>/usr/share/examples/etc/bsd-style-copyright</tt>.
		      
        &porting;

<sect1><heading>Money, Hardware or Internet access</heading>
<p>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. 

<sect2><heading>Donating funds</heading>
<p>While the FreeBSD Project is not a 501(C3) (non-profit) corporation and
hence cannot offer special tax incentives for any donations made, any such
donations will be gratefully accepted on behalf of the project by
FreeBSD, Inc.

<p>FreeBSD, Inc. was founded in early 1995 by &a.jkh and &a.davidg with the
goal of furthering the aims of the FreeBSD Project and giving it a minimal
corporate presence.  Any and all funds donated (as well as any profits
that may eventually be realized by FreeBSD, Inc.) will be used exclusively
to further the project's goals.  

Please make any checks payable to FreeBSD, Inc., sent in care of the
following address:

<tscreen><verb>
FreeBSD, Inc.
c/o Jordan Hubbard
4041 Pike Lane, suite #D.
Concord CA, 94520

[temporarily using the Walnut Creek CDROM address until a PO box can be
opened]
</verb></tscreen>

Wire transfers may also be sent directly to:

<tscreen><verb>
Bank Of America
Concord Main Office 
P.O. Box 37176
San Francisco CA, 94137-5176
 
Routing #: 121-000-358
Account #: 01411-07441 (FreeBSD, Inc.)
</verb></tscreen>

If you do not wish to be listed in our <ref id="donors" name="donors">
section, please specify this when making your donation.  Thanks!

<sect2><heading>Donating hardware</heading>

<p>Donations of hardware in any of the 3 following categories are also gladly
accepted by the FreeBSD Project:

<itemize>
<item>General purpose hardware such as disk drives, memory or complete
systems should be sent to the FreeBSD, Inc. address listed in the
<em>donating funds</em> section.

<item>Hardware for which ongoing compliance testing is desired.
We are currently trying to put together a testing lab of all components
that FreeBSD supports so that proper regression testing can be done with
each new release. We are still lacking many important pieces (network cards,
motherboards, etc) and if you would like to make such a donation, please contact
&a.davidg for information on which items are still required.

<item>Hardware currently unsupported by FreeBSD for which you would like to
see such support added.  Please contact the <htmlurl
url="mailto:core@FreeBSD.ORG" name="FreeBSD Core Team"> before sending
such items as we will need to find a developer willing to take on the task
before we can accept delivery of them.  
</itemize>

<sect2><heading>Donating Internet access</heading>

<p>We can always use new mirror sites for FTP, WWW or sup.
If you would like to be such a mirror, please contact
<htmlurl url="mailto:admin@FreeBSD.ORG" name="the FreeBSD project
administrators"> for more information.

<sect><heading>Donors Gallery<label id="donors"></heading>

<p>The FreeBSD Project is indebted to the following donors and would
like to publically thank them here!

<itemize>
	<item><htmlurl url="mailto:ANDRSN@HOOVER.STANFORD.EDU"
	name="Annelise Anderson">

	has generously donated funding for the further development of FreeBSD
	</item>

	<item><htmlurl url="http://www.epilogue.com/" name="Epilogue
        Technology Corporation">has generously donated funding for FreeBSD
	development.
        </item>

	<item><htmlurl url="mailto:gmarco@masternet.it"
	name="Gianmarco Giovannelli"> has generously donated funding for
	FreeBSD development.
	</item>

        <item><htmlurl url="http://www.iijnet.or.jp/laser5/" name="Laser5">
        in Japan has graciously donated a portion of their profits from the
        sale of their <em>FreeBSD for PC98'ers</em> CD, a port of FreeBSD to
        the NEC PC98.
        </item>

	<item><htmlurl url="http://www.cdrom.com" name="Walnut Creek CDROM">
	has donated almost more than we can say (see the
	<ref id="history" name="history"> document for more details).
	In particular, we would like to thank them for the hardware used for
	<em>freefall.FreeBSD.ORG</em>, our primary development machine,
	and for <em>thud.FreeBSD.ORG</em>, our testing and build box.
	We are also indebted to them for funding various contributors over
	the years and providing us with unrestricted use of their T1
	connection to the Internet.
	</item>
</itemize>