Advogato: 'Best Practices' for Open Source ?

'Best Practices' for Open Source ?

I've been thinking about project management methods & coding standards for use with Open Source Projects. Most programmers would agree that some form of management, and some standards are necessary. Its the which ones part we have problems with. Traditional 'best practices' need a little tweaking to fit with OSS development. So here's my attempt - I would love feedback & suggestions....

  The main problems with traditional methods/methodologies stem from the fact that they were developed to support scarce resources. A result of this scarcity was that these resources were also expensive. Not only were programmer time, & machine time expensive, distribution was as well. The cost of distribution was not just limited to physically moving the code from one place to another, but often incurred additional expenses such as technicians to install the code. This made frequent releases of development code impractical. A side effect of this was that 'end user' input was often unavailable until the project was nearly completed. As software was so expensive to develop, it was paramount that it be maintainable otherwise there was no hope of recouping the cost of development. These conditions resulted in strict methods that required in-depth requirements docs up front. Users were forced to determine all their needs in advance, with little feedback as development progressed. Detailed specs & designs were produced from the requirements, along with detailed schedules. The entire process was documented heavily, with numerous 'sign-offs' meant to ensure everyone agreed on what needed to be done and how it was to be accomplished. Once implementation was begun, formal coding standards were used to increase code readability, maintainability and shorten the learning curve for new developers. While the methods could be 'heavy' in terms of startup cost, the anticipation was they would reduce the overall project cost & improve the quality of the resultant product.
A few of the benefits of these traditional methods are:
   Predictable & Repeatable (at least theoretically :-) )
   Project spec. established 'scope' & got everyone on the same page.
   Master schedule projected resource requirements & delivery date
   Coding Standards aided maintainability
   Extensive documentation shortened learning curve for developers & users.
As well as liabilities:
   Long development cycles with limited customer input
   Doesn't scale well
   'Heavy' processes

  OSS projects function in a different atmosphere. Resources have become 'cheap' or even free. Programmers are no longer an expensive commodity; they're a freely available asset. Machines have become fast, cheap & plentiful. Languages and toolkits have evolved, allowing programmers to produce programs much faster then ever before. Last but not least, the Internet has provides a fast, easy way to tie all the pieces together. It is now possible for people scattered across the globe to collborate almost as easily as people in the same room. Additionally, the low cost & ease of distribution the 'net offers (along with standardized hardware & packaging systems) allows 'customers' to watch a project develop, and actively participate in its development. These changes have shattered the old, monolithic development model and turned program development into a much faster, more dynamic process.
To take full advantage of this 'distributed development' model, 3 key areas must be addressed:
   Communication
   Project Management
   Programming Practices

Communication

  Communication is the key to any group activity, and is especially important with groups as geographically distributed, as OSS projects tend to be. While the project web site & mailing lists are generally the main methods of communication, don't overlook other tools. IRC channels, Newsletters, or Wiki's can all be used to increase communication between team members. It is also important to realize that 'end-users' are part of the development team. They function as QA testers, first line support, even documentation writers all rolled into one. The key is to have accurate information, easily available to all team members. Documentation must be easy to find, easy to understand, and up to date. This allows new developers and users to 'come up to speed' rapidly. Note that the larger a project (in terms of number of participants or code size), the more important documentation becomes!
At the minimum, the web site should contain:
   A clear, succinct definition of the project goals
   Design documentation
   User documentation
   Project plan & implementation Schedule
   A listing of each module, along with status & 'owner' information
   Online bug tracking
   Project News
   Information on how to obtain the latest code from CM
   Regularly produced 'beta' snapshots for more casual users
   Project mailing lists & archives
   Any additional resources (related projects, Wiki's, IRC channels, etc)
   Optional: Who we are, Sponsors, Case studies, press clippings, etc.
Note: The project website needs to be updated often - nothing makes a project appear 'dead' more than a web site that hasn't been updated in 6 months...

Project Management

Project management tends to be a religious issue, so I'll limit my comments here to: Use It!!
It doesn't matter what method you use, as long as the overhead is low (i.e. It shouldn't require more then 5 to 10 minutes per week from participants). A simplified version of Earned Value reporting has worked well for me in the past, however many examples of PM techniques are available on the web. Two of the most common questions team members are asked are "When will feature FOO be ready?" & "How can I help" - good PM can help provide realistic answers. The 'PM' should track progress and work with the project lead & module owners to resolve any issues (i.e. Locate resources, balance work load etc.) Current status by module should be posted back to the project web site.

A modular, detailed design and a good 'PM' can be crucial to alleviating two of the most common problems I've encountered in OSS projects: relatively high numbers of design changes, and turnover. Due to the increased 'customer' involvement in OSS projects, design changes and enhancements are a common occurrence. Team members come and go, depending upon their interest level and amount of free time. Having project management in place allows the team to judge how these changes will affect the overall project, both in terms of resources required & implementation timeline.

Programming Practices

Good programming practices start with the initial design. Make sure everyone has a clear understanding of the project goals. Determine a written set of requirements for the project. In short, make sure everyone knows what the team is trying to acomplish. Once this is done, initial design work can begin. The design will consume a significant amount of time, and its important to resist the urge to start coding immediately. A good design is the difference between a solid, general purpose tool, and a 'one-off' that only works during certain phases of the moon. For OSS projects a modular design with 'staged' or 'incremental' rollout is usually the best bet. A modular design is particularly applicable to OSS, as it allows project to 'evolve' while maximizing code re-use. This can be a simple 'top-down' program design, or a more extreme 'plug-in' architecture that allow virtually complete customization at run time using re-usable components (for instance, GIMP). 'Staged rollout' simply means releasing a program in 'stages' with successively more features implemented. This allows users to test, and become familiar with a program before its fully implemented. In turn, feedback can be given much earlier in the project life cycle. This differs slightly from the traditional 'release early, release often', as stages are slightly more formal. Stages are presumed not to break existing features, nor to damage data - in short stages are usable, 'mini-programs' or 'lite' versions of the finished project. These techniques can be used together and are complementary. Stages roughly correspond to a #.X release, while 'bugfix' releases correspond to a #.#.Y release.

This brings up an important point: You must design for reuse, it doesn't just happen !!
In order for code to be reused, it must satisfy a number of criteria. It must be easily understood. It must provide a specific well, documented function. It must be easily relocated (ie. code that relies upon numerous global vars. or external 'state' is a P.I.T.A. to reuse.). In short, modules must be small, well documented, and free from 'side-effects' - a 'blackbox' that can be picked up and moved wherever its needed. Physically writing out 'psuedo code' for the design can be a great aid in determining potential candidates for a module. Refactor Often.

At this stage, it may be helpful to code up 'testbeds' to evaluate various designs, data structures, etc. Resist the urge to 'hack' the testbed into a finished project, without a final design !! Though it may seem time consuming, a good design will more then pay for itself with the time saved later and the stability of the finished project.

Once the design is ready, it should be compared to the requirements to make sure it meets the project's goals. Next, the 'critical path' should be determined. The critical path is the smallest set of modules that must be implemented in order to produce a 'usable' system. The critical path modules should be implemented first, with the other modules 'stubbed out'. This method not only supports 'staged rollout' but allows features the end-users need to be implemented before lower priority features. This is also the time to start planning test cases, using whatever methods the team is comfortable with.

As an example of 'staged rollout' , a project to produce a word processor might rollout the following :
  stage 1: full top-level gui interface, simple 'edit box' functions, and load/save functions.
     Most of the gui would do nothing - it would be tied to 'stubbed out' functions. However, it allows users to 'test drive' the gui, checking
     the 'feel'. It also provides an opportunity for users to provide suggestions for enhancements, clarify requirements, & report bugs.
  stage 2: 'Print' menu stubbed out, along with basic 'print' functionality.
     Advanced features, such as paper orientation,etc. may not be implemented yet.
  Successive stages would activate more of the gui - search & replace, spell checking, etc.

The finished design & critical path must be fully documented, along with test cases. This information, along with a list of modules, projected completion dates, and module 'owners' (with contact info.) should be posted on the website. This information will not only guide existing team members, but will allow new developers to join the team without having to read & understand all of the source code.
Design Notes:
   Make sure everyone is designing the same program! USE the requirements.
   Avoid side effects in modules wherever possible !!
     This can be the single greatest aid to reuse & maintainability!
     (In short, a module should only rely on its parms. However, more info. is available on the web.)
  As a rule of thumb, a single module should not be more then 10-15 hours work. (If it is, break it into sub-modules)
  Test the Failure Modes!!
     All programs get bad input at some point, or machines suffer hardware failures.
     Make sure testing covers the 'worst case' scenarios.
  Design Changes Happen
     Live with it, plan for it, use the requirements & project goal to make sure changes make sense.

Programming standards are a must! This has long been recognized, notably by the venerable FSF & the new kid on the block, Java. As with PM, the important thing with programming standards is to use them. The initial project team can pick whatever works best for them, but once decided upon the conventions need to be followed! The same can be said for commenting & documentation systems. Find a set that is comfortable, and stick with them ! (javadoc, Doxygen, etc)

  Use of a source control system such as cvs, aegis, perforce is a must. Even better is use of a build management system. Simple automated builds can help ensure a tree remains consistent, but do little else. A much better solution is regression tests automated into the build cycle. Regression tests check that new code hasn't broken old functionality, and can be collected by designing a test case each time a function is completed or a bug fixed. This results in a surprisingly thorough set of tests in a very short time (ie - whole classes of bugs, such as handling of invalid parameters get caught very early in the development cycle). A 'test down' method works well, and simply means checking return & error conditions any modules your module depends on. This can be quite handy - especially when someone changes the returns of one of your dependencies & doesn't tell you. Don't forget to test the failure modes of your module as well! How it performs under error conditions is a critical piece of system stability.

( Out of time - gotta go...below is a list of tools that may be of some use...)
The Mozilla project has a very nice setup of build management tools.
  Highly recommended
Aegis features configuration mgmt. with built in Regression testing.
  Just starting to play with this one.....However, its been in use for years, and is supposed to be very stable.
Perforce is free for use in OSS Projects & lacks cvs's more annoying habits.
  Perforce also has a collection of OSS tools, such as web browsing the repository. Look here