http://blogs.clariusconsulting.net/kzu

Daniel Cazzulino's Blog

Go Back to
kzu′s Latest post

A better way to encourage contributions to OSS

Currently in the .NET world, most OSS projects are available via a NuGet package. Users have a very easy path towards *using* the project right away.

But let’s say they encounter some isssue (maybe a bug, maybe a potential improvement) with the library. At this point, going from user to contributor (of a fix, or a good bug repro or even a spike for a new feature) is a very steep and non trivial multi-step process of registering with some open source hosting site (codeplex, github, bitbucket, etc.), learning how to grab the latest sources, build the project, formulate a patch (or fork the code), learn the source control software they use (mercurial, git, svn, tfs), install whatever tools are needed for it, read about the contributors workflow for the project (do you fork & send pull requests? do you just send a patch file? do you just send a snippet? a unit test? etc.), and on, and on, and on. Granted, you may be lucky and already know the source control system the project uses, but in really, I’d say the chances are pretty low. I believe most developers *using* OSS are far from familiar with them, much less with contributing back to various projects. We OSS devs like to be on the cutting edge all the time, ya’ know, always jumping on the new SCC system, the new hosting site, the new agile way of managing work items, bug tracking, code reviews, etc. etc. etc.. But most of our OSS users are largely the “dark matter developers”, they simply don’t have the time to put through all that friction just to contribute back. Even if they want to, it’s just WAY too much. It’s discouraging.

We can do better.

How about this flow?

  1. User installs library: install-package Moq
  2. He/she uses it happily for years (let’s say Winking smile), until one day an issue comes up that’s becoming annoying or doesn’t look like it has a known workaround. So it’s time for a time-boxed investigation to see if it’s truly a library bug or a user bug.
  3. User uninstalls library: uninstall-package Moq
  4. User installs library source package: install-package Moq.Source
    • At this point, they get the entire *source* for the project, as content (source) files in the SAME project they were previously using the library reference. Everything should still compile just like before. All that changed is that now you’re building against the actual sources, not the library.
    • Any dependencies the library uses for compiling got added automatically by NuGet to the users’ project.
  5. In order to understand a bit the library source code and how it’s being tested, the user installs the library unit tests source package: install-package Moq.Tests
    • At this point, they can run the entire test suite for the library, inspect the tests to learn how to isolate various pieces, and learn about the structuring of the code a bit.
    • Note that the tests source would typically be installed in a test project on the user’s solution.
  6. Now the user goes and creates a new unit test to try to repro in isolation the issue he/she found.
  7. After a successful repro, the time-box may be over. But still, the clean repro he/she got is very useful in its own.
    • If the user has enough time, they may even be able to fix the issue in the code itself, or add the missing behavior.
    • Because of the way NuGet works, when you install a package that brings “content” (code, markup, config files, etc.) into your project, you now have two copies of that content: the original one under the packages folder alongside the solution file, and the potentially modified one in your own project.
  8. At this point, a little bit of VS extensibility and automation could detect that you made changes to that code, and offer a context menu to “Send Feedback”, which could pre-package the diff (patch file, .zip, clone/commit/whatever), allow the user to enter briefly an explanation of the issue, and be done.
  9. Now, if the issue was really a showstopper, the user now has a way forward, that didn’t even require them to leave their own solution. Granted, checking into a company source control the actual source for an entire OSS project is typically unfeasible. So the alternative is for them to just uninstall-package Moq.Source, go back to install-package Moq and go on by implementing a workaround. But they have actively contributed back to a project they appreciate, they now have a real explanation (for dev leads, upper management) of why something proved harder than expected, and they probably even came out of the experience learning a new trick or two that they found in that codebase while they were investigating. An all around win-win situation.

 

I believe this is totally worth exploring. I’m willing to give this a try for Moq v5, as we talked about in our first hangout. What do you think? Is this something that looks reasonable and useful?

Comments

15 Comments

  1. Seriously that is a great idea, and there are at least three times in the last year when I would have taken advantage of a setup like this to send feedback specifically for Moq. I have a counterexample though: what happens when I find out it’s a bug with one of the project’s dependencies that’s been patched in a newer version of the dependency, but hasn’t been updated in the project I’m targeting? E.g., earlier this month I ran into Moq issue 259 (http://code.google.com/p/moq/issues/detail?id=259) but short of dropping in the latest version of dynamicproxy and crossing my fingers (and having a branched version of Moq on my hands), what’s the best way to deal with something like that?

    Also (and totally unrelated), do you know of anyone selling Moq shirts? I’ve found that a lot of OSS projects encourage me to contibute (financially, anyway) by selling me shirts :-) Thanks for all the hard work! I’m a big fan of Moq and I evangelize it whenever I can.

    • Good point on T-shirts :) Should get some done for the fans (including me!).

      Don’t miss the next moq hangout where we’ll be talking about the contribution flow, the new site, and we will even fix a bug or two in real time, he :) .

      http://kzu.to/yAWmlb

  2. Number 8 sounds like a great feature.

  3. You can create custom NuGet tasks which now get picked up by the NuGet core. You should be able to use this to add an extension to VS to “Send Feedback” via whichever OSS API is required – so TFS for Codeplex, JSON for GitHub/Google Code, etc., etc… sounds like fun ;-)

  4. +1000.
    By the way, if I wanna contribute to Moq in the way you’re working right now.
    Should I go to code.google…, pick an issue, fix it and commit my changes? Or you have a special mechanism for that matter?
    i.e
    me: I wanna fix the issue 195
    you: Ok go for it. Or no, we prefer that you fix 222.

    I ‘ve read the section how to contribute but I cannot find how the issues are assigned or picked up.

  5. It should be possible to add a script to your nuget that add a command to the console to replace the nuget with last version of the source. This would require a download of mercurial or git, pull the code, update project references. The hook an event in visual studio and send a patch by mail.
    No easy, but doable.

  6. The idea of simplifying contributions is a good one.

    But step 4 sounds absolutely horrible. Why would you want to pollute the users project with the library sources, add references, set up compiler constants and whatnot? If Moq.Sources in the example had any resources, you wouldn’t even be able to make it work without changing the user project’s root namespace or forcing the Moq team to spend their time writing scripts to adjust the resource designer files.

    I’d strongly prefer to always add the project(s) of an external library to the current solution and just update the assembly references (preferably solution-wide, so there won’t be colliding versions of the assembly around).

    • That’s how nuget works, at a project level, I’m afraid. But I think it’s far from horrible. It would all go into a folder “Moq” (say) inside your tests project. What’s the big deal?

      And you need to have that co-located with your own code (tests failing!) so that you can debug and see what’s going on…

  7. One challenge that occurs to me is how to deal with users who don’t update to the latest and greatest. Last I checked, update notification is sort of hidden as a setting and, even with it on, users might ignore it.

    So, maybe I have some old version of Moq and I find a bug or problem. What’s the flow then? Am I notified as soon as I start modifying source that my source is outdated? Does this happen only when I try to submit my changes? Does it not happen at all? Obviously, earlier is better, but I don’t know enough logistics of Nuget operation to know what’s most practical.

    Anyway, perhaps something to consider.

    • Well, the moment they do install-package Moq.Source, they would get the latest and greatest (that was published by the OSS author). There needs to be some sort of CI process for those “source packages”, otherwise, it won’t work so well.

  8. Not everyone wants to update to the latest and greatest (or sometimes, not so great). I would rather the source be downloaded for the exact version I am using in my project, which should be a labeled release in the source control of the library. Updating a dependency (and possibly others related) only to fix a bug in production code does not sound very appealing.

  9. I think its a good idea to try and streamline the process of becoming a contributor. I’ve previously considered contributing to projects but then didn’t follow through because it wasn’t easy to contribute ;)

    I do have concerns about a solution that might result in the source code of the OSS project being “too close” to my source code because my source code is closed and we don’t want to have to worry about the specific license on the OSS project.

    • Fair concern. That’s why you can uninstall-package the source and leave no trace behind. Also, you just as easily just start a new blank solution for repro and fix work. The process would be the same in either case.