3 Collaborating with FreeBSD

Open-source projects like FreeBSD offer finished code of a very high quality [Cov2005]. Previous studies have examined the effect of source code availability on software development [Com2004].

While access to quality source code can reduce the cost of initial development, in the long-term the costs of managing change begin to dominate. As computing environments change over the years and new security vulnerabilities are discovered, your product too needs to change and adapt. Using open-source code is best viewed not as a one-off activity, but as an ongoing process. The best projects to collaborate with are the ones that are live; i.e., with an active community, clear goals and a transparent working style.

3.1 Understanding FreeBSD culture

To be able to work effectively with the FreeBSD project, you need to understand the project's culture.

Volunteer driven projects operate under different rules than for-profit corporates. A common mistake that companies make when venturing into the open-source world is that of underplaying these differences.

Motivation. Most contributions to FreeBSD are done voluntarily without monetary rewards entering the picture. The factors that motivate individuals are complex, ranging from altruism, to an interest in solving the kinds of problems that FreeBSD attempts to solve. In this environment, “elegance is never optional” [Nor1993].

The Long Term View. FreeBSD traces its roots back nearly twenty years to the work of the Computer Science Research Group at the University of California Berkeley.[1] A number of the original CSRG developers remain associated with the project.

The project values long-term perspectives [Nor2001]. A frequent acronym encountered in the project is DTRT, which stands for “Do The Right Thing”.

Development Processes. Computer programs are tools for communication: at one level programmers communicate their intentions using a precise notation to a tool (a compiler) that translates their instructions to executable code. At another level, the same notation is used for communication of intent between two programmers.

Formal specifications and design documents are seldom used in the project. Clear and well-written code and well-written change logs (Figure 3) are used in their place. FreeBSD development happens by “rough consensus and running code” [Carp1996].

Figure 3. A sample change log entry

bde         2005-10-29 16:34:50 UTC

  FreeBSD src repository

  Modified files:
    lib/msun/src         e_rem_pio2f.c
  Log:
  Use double precision to simplify and optimize arg reduction for small
  and medium size args too: instead of conditionally subtracting a float
  17+24, 17+17+24 or 17+17+17+24 bit approximation to pi/2, always
  subtract a double 33+53 bit one.  The float version is now closer to
  the double version than to old versions of itself -- it uses the same
  33+53 bit approximation as the simplest cases in the double version,
  and where the float version had to switch to the slow general case at
  |x| == 2^7*pi/2, it now switches at |x| == 2^19*pi/2 the same as the
  double version.

  This speeds up arg reduction by a factor of 2 for |x| between 3*pi/4 and
  2^7*pi/4, and by a factor of 7 for |x| between 2^7*pi/4 and 2^19*pi/4.

  Revision  Changes    Path
  1.14      +22 -97    src/lib/msun/src/e_rem_pio2f.c
       

Communication between programmers is enhanced by the use of a common coding standard style(9).

Communication Channels. FreeBSD's contributors are spread across the world. Email (and to a lesser extent, IRC) is the preferred means of communication in the project.

3.2 Best Practices for collaborating with the FreeBSD project

We now look at a few best practices for making the best use of FreeBSD in product development.

Plan for the long term

Setup processes that help in tracking the development of FreeBSD. For example:

Track FreeBSD source code. The project makes it easy to mirror its CVS repository using CVSup. Having the complete history of the source is useful when debugging complex problems and offers valuable insight into the intentions of the original developers. Use a capable source control system that allows you to easily merge changes between the upstream FreeBSD code base and your own in-house code.

Figure 4 shows a portion of an annotated listing of the file referenced by the change log in Figure 3. The ancestry of each line of the source is clearly visible. Annotated listings showing the history of every file that is part of FreeBSD are available on the web.

Figure 4. An annotated source listing generated using cvs annotate

#LINE #REV         #WHO      #DATE       #TEXT

62    1.1          (jkh      19-Aug-94):      int32_t __ieee754_rem_pio2f(float x, float *y)
63    1.1          (jkh      19-Aug-94): {
64    1.14         (bde      29-Oct-05):      double z,w,t,r,fn;
65    1.13         (bde      29-Oct-05):      double tx[3];
66    1.14         (bde      29-Oct-05):      int32_t e0,i,nx,n,ix,hx;
67    1.1          (jkh      19-Aug-94):
68    1.1          (jkh      19-Aug-94):      GET_FLOAT_WORD(hx,x);
69    1.1          (jkh      19-Aug-94):      ix = hx&0x7fffffff;
70    1.1          (jkh      19-Aug-94):      if(ix<=0x3f490fd8)   /* |x| ~<= pi/4 , no need for reduction */
71    1.1          (jkh      19-Aug-94):          {y[0] = x; y[1] = 0; return 0;}
72    1.14         (bde      29-Oct-05):      /* 33+53 bit pi is good enough for special and medium size cases */
73    1.2          (bde      07-Apr-95):      if(ix<0x4016cbe4) {  /* |x| < 3pi/4, special case with n=+-1 */
74    1.14         (bde      29-Oct-05):          if(hx>0) {
75    1.15         (bde      06-Nov-05):              z = x - pio2;
76    1.15         (bde      06-Nov-05):              n = 1;
77    1.15         (bde      06-Nov-05):          } else {
78    1.15         (bde      06-Nov-05):              z = x + pio2;
79    1.15         (bde      06-Nov-05):              n = 3;
80    1.9          (bde      08-Oct-05):          }
81    1.15         (bde      06-Nov-05):          y[0] = z;
82    1.15         (bde      06-Nov-05):          y[1] = z - y[0];
83    1.15         (bde      06-Nov-05):          return n;
84    1.15         (bde      06-Nov-05):      }
85    1.15         (bde      06-Nov-05):      if(ix<0x407b53d1) {  /* |x| < 5*pi/4, special case with n=+-2 */
             

Use a gatekeeper. Appoint a gatekeeper to monitor FreeBSD development, to keep an eye out for changes that could potentially impact your products.

Report bugs upstream. If you notice bug in the FreeBSD code that you are using, file a bug report. This step helps ensure that you do not have to fix the bug the next time you take a code drop from upstream.

Leverage FreeBSD's release engineering efforts

Use code from a -STABLE development branch of FreeBSD. These development branches are formally supported by FreeBSD's release engineering and security teams and comprise of tested code.

Donate code to reduce costs

A major proportion of the costs associated with developing products is that of doing maintenance. By donating non-critical code to the project, you benefit by having your code see much wider exposure than it would otherwise get. This in turn leads to more bugs and security vulnerabilities being flushed out and performance anomalies being identified and fixed.

Get support effectively

For products with tight deadlines, it is recommended that you hire or enter into a consulting agreement with a developer or firm with FreeBSD experience. The FreeBSD related employment mailing list is a useful communication channel to find talent. The FreeBSD project maintains a gallery of consultants and consulting firms undertaking FreeBSD work. The BSD Certification Group offers certification for all the major BSD derived OSes.

For less critical needs, you can ask for help on the project mailing lists. A useful guide to follow when asking for help is given in [Ray2004].

Publicize your involvement

You are not required to publicize your use of FreeBSD, but doing so helps both your effort as well as that of the project.

Letting the FreeBSD community know that your company uses FreeBSD helps improve your chances of attracting high quality talent. A large roster of support for FreeBSD also means more mind share for it among developers. This in turn yields a healthier foundation for your future.

Support FreeBSD developers

Sometimes the most direct way to get a desired feature into FreeBSD is to support a developer who is already looking at a related problem. Help can range from hardware donations to direct financial assistance. In some countries, donations to the FreeBSD project enjoy tax benefits. The project has a dedicated donations liaison to assist donors. The project also maintains a web page where developers list their needs.

As a policy the FreeBSD project acknowledges all contributions received on its web site.

Notes

[1]

FreeBSD's source repository contains a history of the project since its inception, and there are CDROMs available that contain earlier code from the CSRG.

This, and other documents, can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.