Eigenbase Joint Development Guidelines

The Eigenbase Project

Joint Development Guidelines

This document defines guidelines which all contributors to The Eigenbase Project are expected to read, understand, and follow. Corporate contributors must ensure that all individuals submitting contributions on behalf of the corporation have read and agreed to these guidelines.

Project Directory Organization

Files checked in to Eigenbase source control are organized into hierarchical directories. For the main development trunk, the top level directories correspond to Eigenbase sub-projects and auxiliary components:

Directory Contents

//open/dev/bootstrap support for build automation

//open/dev/farrago the Farrago sub-project

//open/dev/fennel the Fennel sub-project

//open/dev/luciddb the LucidDB sub-project

//open/dev/saffron the Saffron project (Saffron is owned by Disruptive Tech and has not been contributed to Eigenbase, although--like the Mondrian project--it is currently maintained in the same source control server)

//open/dev/thirdparty pre-packaged distributions of third-party components on which Eigenbase sub-projects depend

Within each sub-project there may be certain subdirectories whose contents are designated as restricted contributions by a particular contributor (these subdirectories are known as "yellow zones"; everything else is termed "green zone"). Currently, the yellow zones are as follows:

Restricted Subdirectory Controlling Contributor

//open/dev/farrago/src/com/disruptivetech Disruptive Tech

//open/dev/farrago/src/com/lucidera LucidEra, Inc.
//open/dev/fennel/disruptivetech Disruptive Tech
//open/dev/fennel/lucidera LucidEra, Inc.
//open/dev/luciddb LucidEra, Inc.
//open/dev/saffron Disruptive Tech

Please note that these directory structures may be replicated in each branch as described in the next section. However, a branched copy of a file obeys the zone definitions above regardless of the branch.

Branching and Merging

Eigenbase maintains and controls the primary development trunk //open/dev/... and from time to time creates additional release branches, e.g. //open/dev/r0.1/.... Checkin rules for these locations are as follows:

all checkins to the primary development trunk must pass all enabled tests for all sub-projects on all officially supported platforms (currently Linux and Windows); failures will be resolved by a compensating checkin which reverses the problematic checkin
checkins to release branches must be either the branch creation or an attempted fix for an issue whose resolution has been approved for the corresponding release

Because the rules for trunk checkins are so stringent, Eigenbase encourages each contributor to create a separate development branch. Development teams typically share a branch; individual contributors may have a completely private branch. For example, the Disruptive Tech team uses //open/dt/dev/.... The multi-team development process works like this:

Write access for a team branch is restricted to members of that team. This means that a team member must be responsible for periodically merging changes made by other teams down from the Eigenbase development trunk.
Everyone has read access to all checked in code (regardless of team). This also means that anyone can merge changes from a team's development branch up to the Eigenbase development trunk (after first verifying that it passes the rules given above). However, in practice, it's best to handle merges in both directions together, so this should usually be done by a member of the appropriate team.
A team may create multiple branches (e.g. a primary development branch and multiple release branches).
Each team defines the checkin policy for each of its branches. However, because eventually all checkins should get merged up to the Eigenbase development trunk where all tests must be passed, it is a good idea for everyone to maintain all tests, even those for functional code primarily maintained by other teams.

Here's a diagram (solid horizontal rays represent codelines; dashed rays represent branch definitions from source to target codelines):

After the initial branch definition, changes can be merged in either direction between the two codelines connected by branching. Changes should never be merged directly between unrelated codelines (e.g. //open/team2/release/beta1 and //open/dev); instead, equivalent multiple merges should be used (e.g. first from //open/team2/release/beta1 to //open/team2/dev, and then from there to //open/dev).

Coordination of Changes

When planning and executing source code changes, two very important points should be taken into account:

All changes have a potential for causing difficulties for other contributors during merge.
Not all dependent source code is visible as part of Eigenbase; contributors and users may create dependencies on Eigenbase code from other projects (both open-source and closed-source) which are not part of Eigenbase.

Consequently, all contributors should follow these guidelines:

When possible, make changes in such a way that no dependencies could possibly be broken. For example, suppose a method on a utility class currently takes three parameters, and a new parameter is needed. The wrong action is to just add the extra parameter; this is guaranteed to break dependencies. The correct action is usually to add a new method (possibly an overload of the existing one) which takes the extra parameter, and then change the existing method to call the new one, passing in a reasonable default value for the new parameter. If appropriate, mark the old method as deprecated so that it can eventually be removed in a future cleanup release after everyone has had fair warning.
Build in resilience to change. For example, when defining a Java interface, provide a corresponding abstract class definition and encourage others to subclass the abstract class instead of directly implementing the interface. This way, if a method ever needs to be added to the interface, it can be done (without breaking dependencies) by adding a default implementation to the abstract class at the same time.
Use member access control to prevent unwarranted dependencies. Don't make a class or method public unless it needs to be. Provide accessor methods instead of defining non-private data members. Mark classes as final unless they are truly designed for subclassing. Use comments to warn others about code which isn't ready for reuse.
Don't make sweeping changes or cleanups without engaging others in a review process first. Sometimes such changes really are necessary, and letting bad code ossify is never desirable. When a contributor decides that a large-scale change really is needed, the correct action is to raise the issue on a mailing list and seek general agreement on the correct improvement and publish a detailed description. The next step is to come up with a plan for making the proposed changes in such a way that they won't interfere with the release schedules of affected parties. Finally, once the changes have been executed, follow up by publishing the details, potential impact, and an offer to help with resulting merges.
When considering an upgrade for a thirdparty library, use the procedure given above for large-scale changes.
Limit changes according to stability guarantees. For example, on a release branch, a minimal fix is usually the right one (even if it isn't the cleanest one). Likewise, if an interface has been declared as frozen for a particular release, resist the urge to slip in a few more improvements. Instead, keep a TODO list and make sure those improvements get considered early in the next release cycle.

Source Code Headers

All source files must have a standard header containing:

the source control file ID tag
a standard one-line description of the sub-project which contains this file
copyright notices
a standard license header; normally, this should be the GNU GPL, and must always be GPL for files making up restricted contributions

For files constituting the framework portion of the Farrago sub-project (packages net.sf.farrago and org.eigenbase), the copyrights should appear as below. For files which were created before 2005, the first year may be different for some parties; for files created in 2005 or after, the year ranges should be the same for all parties. Contributors other than the parties listed here may add their own copyrights with the phrase "Portions Copyright", but must list the three joint owners first, without the "Portions" prefix.


/*
 * $Id: //open/dt/dev/farrago/src/net/sf/farrago/query/FarragoPreparingStmt.java#36 $
// Farrago is an extensible data management system.
// Copyright (C) 2002-2005 The Eigenbase Project
// Copyright (C) 2002-2005 Disruptive Tech
// Copyright (C) 2005-2005 LucidEra, Inc.
//
// This program is free software; you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by the Free
// Software Foundation; either version 2 of the License, or (at your option)
// any later version approved by The Eigenbase Project.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

For files constituting a restricted contribution from a particular contributor, the copyrights should appear as below. The contributor should be listed first, and The Eigenbase Project second. Contributors other than these two parties may add their own copyrights prefixed with the phrase "Portions Copyright", but must list the two joint owners first, without the "Portions" prefix.


/*
// $Id: //open/dev/farrago/src/com/disruptivetech/farrago/volcano/VolcanoPlanner.java#6 $
// Farrago is an extensible data management system.
// Copyright (C) 2002-2005 Disruptive Tech
// Copyright (C) 2005-2005 The Eigenbase Project
//
// This program is free software; you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by the Free
// Software Foundation; either version 2 of the License, or (at your option)
// any later version approved by The Eigenbase Project.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

...


/*
// $Id: //open/dev/fennel/lucidera/sorter/ExternalSortMerger.h#1 $
// Fennel is a library of data storage and processing components.
// Copyright (C) 2004-2005 LucidEra, Inc.
// Copyright (C) 2005-2005 The Eigenbase Project
//
// This program is free software; you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by the Free
// Software Foundation; either version 2 of the License, or (at your option)
// any later version approved by The Eigenbase Project.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
*/

Issue Tracking, Mailing Lists, and Wikis

Eigenbase maintains publicly accessible issue tracking systems, mailing lists, and wikis for users and developers. Contributors may also maintain private systems on their own. It is up to each team to set policy for when to use public systems and when to use private systems, but Eigenbase recommends that all contributors should use public systems for issues and discussions which do not relate to confidential information. Public issue tracking and mailing list activity helps to demonstrate project health and provides a valuable knowledge base for all developers and users.

Note that it is the responsibility of contributors to ensure that confidential information never enters the public systems, as such leakage may be very difficult or impossible to reverse. Contributors using public forums should observe standard netiquette.

Responsibility for issue resolution may be reassigned across team boundaries based on module ownership, but since teams do not dictate schedules for other teams, the policy for issue resolution is as follows:

In general, if an issue is critical to a particular team, it is up to that team to resolve it within their scheduling constraints.
However, if an issue is agreed to be the result of a mistake recently made by another team, the team which made the mistake should provide timely assistance in resolving it.
When there is disagreement for more than one month about the priority, responsibility, or proposed resolution for a particular issue, the issue should be addressed at an Eigenbase operational meeting.