Help your favorite open source project by helping yourself
Hello, my name is Sebastiaan and I work for Umbraco.
When I started working for Umbraco we had a large but manageable community of people building sites with Umbraco and figuring out the best solutions for their problems with our software. Problems? Yes, we have an approximately 15-year old codebase, which had many bugs when I started working at Umbraco we have many bugs we have yet to fix.
We used to be able to mostly keep up with bugs people were dealing with, we more often than not were able to give tips on the forums, on Twitter and in the issue tracker. This is fun and thankful work and I still love helping out whenever I can.
However, these days, with the amount of people using our software, this is no longer manageable. Many people want to use our software and this is great. I still love to help people but I can't dive into every problem in depth, nor can my colleagues. This is why we offer support contracts, if you need help and you're willing to pay for it then you get to jump the line of people who also want help but are not willing to pay for it.. or not able to pay for it. Your money allows us to hire and train more people to help out!
But that last category of people, the ones that simply cannot pay for priority support are sometimes out of luck. We have a wonderful community, donating a lot of their spare time to try and help out. But their time is also limited and they will not always be able to give you a solution either.
Most of the time we will spend the time to pick up high priority problems that affect a lot of Umbraco users anyway, so most people are not left high and dry when there's bad bugs.
On the other hand, the problem you're facing might only apply to you, or it has a workaround that's acceptable to most people or it only applies to a particular setup that we are unable to replicate. What to do?
Contributing to open source software
As a developer myself, I use open source tools that help me do my job better or easier. I often get annoyed or blocked by some bug in the software. So, I like giving back!
Over the years I've contributed to projects like Git Extensions, lets-encrypt-win-simple, ACMESharp, ImageProcessor, UmbracoTracelogViewer and other projects. Some of these were directly related to work I was doing for Umbraco, most in my spare time.
And here is where I have a confession to make: most of my contributions initially were born out of pure frustration. Bugs that were annoying, features that didn't work the way I liked them, missing features, etc. So that's the dirty truth: I mostly contributed out of pure selfishness.
However, the happy outcome of these contributions has always been: a change for the better, not just for me but for all the other users of that software. It may come as no surprise but it feels really, REALLY good to help turn that frown upside down!
Help yourself
So, dear Umbraco users, let me give you some tips on how you can help yourself (and help us in the process!). You are in the unique position to investigate your particular problem.
By digging into the specific bug you're encountering you can give us a hint or some proof of where our code is doing something wrong, You might even be able to send us a pull request so we can look at it and go "ha! how could we have been so silly as to believe that would ever work correctly?". After which we'll happily click the "Merge" button to get your code into the next release of Umbraco and you potentially make many people's life better!
Here are a few steps you should take:
1. Identify the exact problem
What exactly is happening?
It's like going to the doctor: if I press here, it hurts here. The better you can describe which steps you take to get into an unwanted situation, the better your chances that it can be fixed.
2. Pinpoint the problem
Following up to point 1: is it just you?
Download a fresh copy of the Umbraco version you're running and install it without any plugins and without your custom code in there. Follow the same steps you took to identify the problem (see point number 1). Do you still see the problem? If not, the problem is likely a configuration difference, due to some plugin you installed or caused by some of the custom code you wrote.
At this point I usually start to compare configuration files and if they're the same, I'd start taking some custom components out of the site, to see if I can narrow it down to some plugin or to some of my own code.
3. Eliminate the problem
Is the problem fixed already?
If you see an error message: Google it, add the word "Umbraco" in quotes to your query to get the best results. Is there an issue on the issue tracker with a "Due in version" set? Is the version higher than the version you're running now? Time to attempt an upgrade to see if the problem is already fixed! Take a backup of your site and database, upgrade the backup to the latest version and try steps 1 and 2 again.
Hint: issues on the tracker almost always point to the code we changed, it might give you a good idea of if your particular problem is going to be fixed.
4. Investigate the problem
Did none of the above help? Time to get your hands dirty! This is where the fun part starts!
Each Umbraco release is tagged when we release it, so you can find the particular version you're using and get the exact source code for it. You can clone the Umbraco repository and with a command like `git checkout tags/release-7.4.2` you would get to the exact code that your Umbraco 7.4.2 site is using right now.
With that code, you can now do great things! Open up `umbraco.sln` in Visual Studio and build it. The build output will not only give you the same dlls you are using right now but also the pdb files, the symbols to debug the code.
If you go into the `~/src/Umbraco.Web.UI/bin` directory you can find the files that were just modified.
Go ahead and copy these files right into the problematic website. You now have full debugging capabilities for that website, while maintaining the exact functionality that was in our dlls in the first place!
Back in Visual Studio you can attach it to the process that is running your website, for example IISExpress (the easiest way) or the w3wp process.
Now you can set breakpoints in our code to narrow down that problem that's been annoying the heck out of you!
Pro tip - if your problem only occurs on the live server and you cannot attach to the process to set breakpoints: add copious logging to the areas you suspect of having problems, update the dlls on your server with the new ones that add logging and see what you can find.
5. Report back to us!
Hopefully by now you will have figured out the root cause of your particular problem, or at least you got closer to it. You should be able to tell us in great detail (describing the previous steps in depth) what the problem is and maybe even how we could fix it.
At this point people sometimes feel like they've spent too much time on this already and tell us: the code in file x on line y is wrong; you should change it from a KiloJoule to a Pancake.
This doesn't really tell us very much though, you might be right but to us a KiloJoule doesn't look like a Pancake at all so we would love to hear the process that led you to this conclusion. The more details you can give the easier we can help get this fixed.
We love pull requests, send us the fixed code so it's easy for us to look at it, get embarrassed about our silly mistake and accept that fix as quick as we can.
Hint: unit tests are a great way to prove your fix does what it says it does and doesn't break something else. Not required, but much appreciated.
If you can't provide a unit test: be as detailed as you can in your description.
Avoiding rabbit holes
Aha, now you have the power!
Something you should be careful of: changing loads of code. We understand, more than anyone, that our code might make you angry, that it's all wrong and not following best practices. There are reasons for this. We are dealing with legacy code, some of it might go away soon. We have coding styles that you may hate, we understand (even within our team there's the constant I Hate #Regions battle).
Rarely will we accept a code clean-up pull request. It is not very useful, and might lead to a refactor gone wrong which introduces subtle bugs.
We also know that you are really missing feature X and you know exactly how to build it and, by golly, you're doing it, sinking a month's worth of weekends into it, emerging with a beautiful pull request.
We understand, completely, but.. talk to us first! Please, before you go down a rabbit hole, discuss it first, open an issue on the issue tracker, describe what you want to do and make sure we want you to do it.
It is always a good idea to lobby for an issue/feature by asking around about it on Twitter and adding a discussion in the dedicated forum "Contributing to Umbraco CMS". This should give you a bit of an idea of how useful other people think your proposal is.
Remember: we can't put everything in Umbraco, some things are much more suitable for a plugin. We would love to guide you.
Conclusion
The power of open source software is that you can poke at it, you can look into everything that's happening behind the scenes and get and better understanding of a problem you're having. That understanding may even lead to a bugfix, which would be great. But if anything, it will teach you something and by poking at problems in our code, you're not just helping yourself grow, eventually you might also help someone else, or many people in the process.
The true power of OSS is that by being selfish and helping yourself, you can turn that frown upside down for many people.