Lots of discussion going on around the death of NDoc and Open Source as a viable option for .NET projects. A lot of this harkens back to some of the things discussed in "Is Open Source a Crap Idea" from a a few months back.

I said Open Source is free like a Puppy. It requires care, feeding, and in the words of Pete Seale, if you beat it it will run away.

Phil says Open Source is free like a Flower. "I think of Open Source software as being like a nice set of flowers in a common space such as a courtyard. Nobody that lives around the common space owns the flowers, yet they all enjoy the presence of the flowers."

Jeff says Open Source is free as in Free. "The highest compliment you can pay any piece of open source software is to simply use it, because it's worth using."

From my point of view, just USING Open Source software doesn't fix bugs. Volunteers fix bugs, whether they are a member of the project or not. (Assuming you haven't got an Open Source Sugar Daddy or a company that supports your work.)

All that is required for Evil to succeed is that Good Men [and Women] do nothing.

If you have the power to fix a bug (or at least get the fix started), especially in software you're using, why not make THAT your contribution?

Jeff says:

Fine. Create a new blog entry. Walk us through, step by step, the process for contributing a fix to DasBlog. List EVERY step, starting with finding a bug.

If it's that easy, prove it.Jeff Atwood on August 2, 2006 09:40 AM

Kind of a sassy tone that, Jeff ;) but here you go.

Note, the bug might be one line, a single char, or quite involved. It all depends. The point is, any help you can give an Open Source dev, no matter how little is a good thing. If you can give them a line number and an idea, that's contributing. Here's an ideal (and real) bug report that stops just short of including the fix. We'll fix it and submit the patch.

How to fix a bug in an Open Source Project(Or at least one that uses Subversion or CVS and is hosted at SourceForge)

Get the Project

Install TortoiseSVN and/or TortoiseCVS, depending on which source control system the Open Source Project is using. They both work about the same, integrating into Explorer.

Make a new folder, right-click, select Checkout.

Enter the URL of the Source Repository and click OK. In this example, the project at Source Forge is called "dasblogce" and we are getting the "trunk" so the URL is https://svn.sourceforge.net/svnroot/dasblogce/trunk. This is how folks are getting the very latest "bleeding edge" versions of DasBlog, since we haven't released in a while.

Build the Project

Every project is a little different, but most have a build file, readme or some detail that says how to get started.

Assuming you have IIS installed, to build DasBlog, run the CreateDasBlogVdir.vbs file in the tools folder to make the IIS Virtual Directory for your local copy.

Open up DasBlog All.sln in Visual Studio 2003 and build. Your virtual directory is mapped to <projectdir>\newtelligence.DasBlog.Web and your binaries - since this is a web application - are in the <projectdir>\newtelligence.DasBlog.Web\bin folder.

Example: Find a Bug

So perhaps you've found a bug. Maybe you got the Yellow Screen of Death. You likely have a stack trace or a strange bit of behavior.

As George points out in the bug report, we want to UrlEncoded the result, but we don't want to UrlEncode all results. Just some.

He also helpfully points me to a post on a RegularExpressions forum where he tried to get the bug fixed using pure Regex. It doesn't appear possible with just RegEx, so we'll use a System.Text.RegularExpressions.MatchEvalulator like the post suggested. He also recommends a new kind of Content Filter that would UrlEncode. In this case, it'll be necessary because we want to do this:

Note that if we did a blanket UrlEncode on the first string, we'd get + signs in our linked text.

So, we'll take his suggestion. Here's the code for a new ApplyContentFilters function with our changes in red.

Remember, we will be submitting our changes as a DIFF file for the developers/commmiters/admins to check in, as we're assuming we don't have source 'commit' access.

privatestaticstring CustomUrlEncodingRegexReplacer(Match m)

{

// Remove the $<char>() from around the string and encode the result.

if (m.Value.Length < 4) thrownew ArgumentOutOfRangeException("Match",m.Value,"UrlEncoded Content Filters should be in the format $u() where 'u' is any single character. Match strings must be at least 4 characters long.");

So now after our Google filter (or dictionary filter, or any of the dozens of filters that folks use) runs, we'll be able to UrlEncode arbitrary parts of the result.

Now we'll add UrlEncode as an option to the ContentFilters object. We'll make false the default so we don't break our public interface as we don't want to break existing code or change existing behavior.

Content Filters don't have to be edited in the XML file directly, they are managed by a rich UI. We'll want to extend the UI quickly.

On the EditContentFilters page, I'll add a new column to allow us to edit this new option in "EditContentFilters" by copy-pasting from another column.

I also do copy paste of the code to update the config file by using the existing "IsRegEx" example. It's a true/false checkbox-style option, just like the new one we're adding.

Here's a test of the results. Note the + in the URL in the Status Bar.

Making the Patch

Now that we think the bug is fixed, we want to make a patch/diff file that will allow the developer(s) to apply easily so they can consider our patch for committing to the project. We don't want to email them a zip of our project directory. That would mean they'd have to manually diff each file and that's a hassle. Remember the goal here is easy on everyone's part. We don't want to bust our asses sending in the patch and we don't want to stress them out by sending 4 megs of code when we only changed 10 lines.

Now I'll right click in the main folder of my project in Explorer and click Create Patch.

From the Create Patch window I will select the files I changed:

In this example, it was only four files. I'll save the unified diff/patch as "contentfilterchange.patch"

If I look inside the patch file with Notepad2 (with it's lovely diff/patch syntax highlighting) I'll see just my few changes with deletes and adds highlighted.

About Scott

Scott Hanselman is a former professor, former Chief Architect in finance, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed stand-up comic, a cornrower, and a book author.

Well, you still have to have programming knowledge and I agree with Jeff on that part. Just by using it and telling your friends about it, you're helping too

Javache

Wednesday, 02 August 2006 21:15:31 UTC

Very nice tutorial Scott! And now where can we donate $5 to you?

msavage

Wednesday, 02 August 2006 21:18:00 UTC

This post itself already qualifies as helping the cause. Most of the Open Source software I use is for software development, so a large part of their user base can is are potential candidates for the above type of help. Even if you don't have programming skills there are tasks like documentation and site administration that could use some help too.

Sergio Pereira

Wednesday, 02 August 2006 21:43:53 UTC

Simply Excellent !!

I´ll be linking to this post in the "How to help in the Development" link of my project. There is a lot of people that helps to fix bugs or add functionality but them send all the project back and now thanks to you I can said them how to send the changes.

Excellent post. This whole NDoc fiasco has really motivated me to start looking for existing open source projects I use and can contribute to.

BTW, I notice you're using Notepad2. I used that for a long time before I found Notepad++, which is like 900 million times cooler than Notepad2. Not only does is it just as fast as Notepad2, it contains a bunch of filetypes (and an editor to define your own, including keywords, folding keywords, etc), has plugins (cool ones like HTMLTidy integration), and a macro recorder. Oh. And a tabbed interface.

Thank you for show how easy is to contribute to an Open Source Project. Most of the time we are only a bunch of good desires but not always have the real initiative to share a bit (or a bunch) of our time.

Great post. I really think more open source projects should post (or link to) this type of information. Coupled with a "Developer's Guide" document that covers the project "philosophy", code standards, testing strategy, etc, it really lowers the barrier to entry for contributions.

It was your original post on this topic (http://www.hanselman.com/blog/UsingAWindowsVersionOfGNUPatchexeWithCVSAndDiffFiles.aspx) that helped me get over my unwarranted fear of CVS and inspired me to start contributing to DasBlog.

Very nice, Scott. This is a great intro into the mechanics of the process. But, but ... does svn.sourceforge.net support the notion of contributors creating branches? If so, might it be better for contributors to commit the bug fix on "task" branch instead? This allows the project owners to simply do an "svn merge" into the trunk to accept the changes. While patch files are elegant, it is not very subversion-y.