Share via

What makes for successful source code releases?

  • Article

We’re preparing to release the source code to the latest Power Toys for Visual Studio and the question has come up a few times.  What makes for successful source code releases?  Specifically… what makes for successful releases if you’d like to encourage community driven development rather than simply tossing code over the wall?

Personally I’m not a believer that simply throwing the code over the wall is good enough.  I’ll give you the list of things I think are important.  I’d love to get your feedback on missing items and the priority of the items. 

Parachutes that come with the code

  • Well formed code: Code that’s easy to understand, jump in, and contribute to.  Code that’s self explanatory and follows coherent coding guidelines.
  • Unit tests: I’d love to know, if I’m contributing, that I’m not breaking anything. 
  • Scenario tests:  Beyond basic unit tests these tests would validate end to end scenarios with the code.
  • Design documents: These are dev focused documents that aim to teach people about the code in a way that code comments can’t. 
  • Code comments: Well commented code is still a requirement. Even with good design documents.
  • Test Spec: Think of this as a design document for the testing. It explains all the concerns about the code, what tests are the highest priority, how to run the tests, any manual verification that can be performed, etc.
  • Documentation: This is sort of a requirement for any release. : - )
  • Vision document: What’s the vision of the application?  What features may have been requested, but not completed that are in-line with that vision?  What’s easy to accomplish and what’s harder?

Intangibles that can’t come with code

  • A good project leader: Someone to spend 10-20% of their time organizing the contributions of others, setting a schedule, etc. (Time estimate based on small isolated projects like the Power Toys)
  • Experts: People that know the code well enough to help onboard new contributors, answer design questions in a timely fasion, etc.  Expect to spend around 10-20% of someone’s time in this role. 
  • Popularity: Releases with little or no potential consumers won’t attract experts. 
  • Completeness: If a solution is tightly scoped and fairly complete there really isn’t going to be much of a need for community driven development. There probably aren’t many popular releases that fall into this category, but sometimes there’s just no place to go.
     

What’s missing?  So far I think we're ahead of where we were with the VS 2003 Power Toy source releases.  Is there anything more specific that should be listed?  What about wiki’s/forums/blogs?  What’s the best bug/feedback model?

Comments

  • Anonymous
    May 01, 2006
    Great points Josh - too bad so many are ignored when people release software. :)
     
    Along the lines of your "Experts" point - it might be taken for granted, but I think an easy method of talking to the developers is vital.  It doesn't matter what the method is (and multiple methods are good), as long as it is appropriate for your audience.  You mention wikis and forums - both great for what they do, and if your audience is familiar with them, by all means, utilize them.  Email, mailing lists, newsgroups, and IRC are all excellent ways to connect people as well - just pick the ones that cater to your clients.
  • Anonymous
    May 01, 2006
    I like pictures, lots and lots of pictures so...

    1. Architectural overview diagrams.

    2. Relationship trees not just for classes but also for project dependencies.

    3. Definitely forums – at the minimum.  Easy communication with history will help people get recognition and share knowledge.

    I’m looking forward to your release.

    Kim
  • Anonymous
    May 01, 2006
    Some points I'd add:

    Well defined feedback channels: If you want the community to contribute they need to know where, how and under which conditions.

    Involve the community in design decisions: you can't expect the community to contribute if they feel unable to drive the project into directions you had not envisioned before.

    Accessible Source Code: A public SCM instance is worth far more than occasional source drops.  Let me see whether a feature has already been implemented before I start working on it.

    Extension points, plugins ... whatever you want to call it:  Give people an opportunity to contribute something small yet useful.

  • Anonymous
    May 02, 2006
    The comment has been removed
  • Anonymous
    May 02, 2006
    The comment has been removed
  • Anonymous
    May 04, 2006
    The comment has been removed
  • Anonymous
    May 25, 2006
    Those who have been following my blog since my days on the VSCore team probably have noticed that I haven’t...
  • Anonymous
    May 25, 2006
    Those who have been following my blog since my days on the VSCore team probably have noticed that I haven’t...