What makes for successful source code releases?

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 (8)

  1. Wil Clouser says:

    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.

  2. Kim Greenlee says:

    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.


  3. 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.

  4. While I agree with your points, I’d also suggest that the license can be a significant factor. The new Microsoft "permissive" license is beginning to be (correctly) recognized by the open source community as a real Open Source / Free Software license, and I strongly suspect that projects released under that license will get more interest from the open source community than projects released with more restrictions.

    (I seem to remember that out of the 5 licenses MS released a while back, there was another one as well as the permissive one that qualified as Open Source, but I can’t remember what it was called)

    From the perspective of typical Open Source projects (which live or die by community) other things you’re missing:

    – Direct (readonly) access to your source control system to enable easy fetching of the very latest code at any given time (I suspect that would be hard for MS – nightly source snapshots might be an acceptable second-best)

    – Mailing lists. For some reason that’s the de-facto standard means of communication for open source development. If you prefer newsgroups or forums, consider gating them bidirectionally to a mailing list for people who prefer that.

    – An easy and well-documented way for people to submit patches. I’m aware that the normal MS development toolkit doesn’t include anything performing the basic functions of diff and patch in the open source world, which will make this hard for developers regardless. I’m sure this is a much bigger problem than anyone at MS could possibly realize. Some cases you can live without it: If you make a one-line fix it’s easy to just describe it; if you make fifty spread-out fixes to one file you can just send the new version of that file. But what if two people simultaneously make fifty-fix changes to the same file? What if you make one-line fixes to fifty files? Communities live or die by the ability of people to feel "inside" the community. If you have the source and are allowed to make changes but have no ability to even *propose* them for inclusion in the official version, that makes you an outsider – and destroys the community.

  5. Mike says:

    Besides the ones you mentioned:

    – License. F/OSS-inclined folk make up a tiny minority of Microsoft’s target market, true. But they’re a much larger proportion of the people likely to contribute to a source code release, and they generally won’t touch Shared Source with a bargepole. Several of the projects that started as SS now seem to have jumped over to CDT, which is a positive sign.

    – Personally I prefer wikis to fora – they tend to become more polished over time, whereas fora just get bigger. (And it get harder and harder to evaluate the older posts, because it’s not clear whether bugs, tips etc still apply.)

    – Mailing lists can be handy, but don’t make toe-dippers sign up for a high-traffic list just to ask one question; it’ll put a lot of them off.

    – Whatever you pick for bug-tracking, make sure that internal and external people use the same system. I’ve seen a few projects that took the two-track route, and their public systems were desolate wastelands containing nothing but blowing tumbleweed and the occasional plaintive ‘Mrh?’

  6. Philip Rieck says:

    Well-formed code is nice, but an easy way to build the project is essential.

    I can’t tell you how many open source projects I’ve wanted to contribute to and didn’t because it was near impossible to create a build environment.  

    Do I need to install specific versions of perl, bison, gmake, whatever to build?  Provide easy access to them! No, don’t provide links to the place where I can get the source (and more instructions on what I need to build that) – I’m trying to work on *your* project, not the other one.

    after installing all the prereqs, can I just execute a build?  Oops, no, I need eight tools.  And I have to run some utility commands to generate keys/conf files.  Then edit them for my machine.

    Now I can build – Can I build all the way to a setup?  if not, how do I run it outside the dev environment?

    Speaking of, can I quickly debug the code or is more tweaking needed?

    Those of you in the .net world may think I’m exaggerating., but I’m not.  And even some .net projects lack an easy 0-dev path.   Help us help you – it makes a big difference to drop the entry barrier.

  7. Those who have been following my blog since my days on the VSCore team probably have noticed that I haven’t…

  8. Those who have been following my blog since my days on the VSCore team probably have noticed that I haven’t…