You know what kinda bums me out? There's probably nothing more I would like to do than help contribute to Rails but I have no idea where to start. I've read books [0] on a basic idea of how it works, subscribe to every mailing list, answer questions on stack overflow, emailed 2 core contributors on tips, and read a dozen blog posts but I haven't even scratched the surface. For me, the code base is is incredibly intimidating. Every once in a while, I muster the courage to go through pages and pages of Rails issues to try to understand what and where but usually I have no idea what's going on or how to fix it. I think really is a huge problem in OSS. I'm only two years out of school but I'm not allowed to participate in GSoC/Facebook OSS Academy.
Start anywhere. Steve Klabniak has a commit bit on Rails primarily because he showed up one day, said "The docs are a mess", and started writing better docs. As he wrote more he got better knowledge of the Rails internals. He then went through the issue tracker just for gardening, marking issues as duplicates, trying to repro them, etc, and suddenly he was the guy who both knew all the exposed features and all of the bugs. Then he put 2 and 2 together and said "Aha, I think I can probably independently fix this one. Here's a pull request with the patch and tests." And repeated that until they said "OK, OK, enough already, have a commit bit."
Can I make a suggestion though? What are your goals in life over the next few years? Does getting a commit bit on Rails represent the single best thing you could be doing to advance those goals? There are many, many OSS projects in the ecosystem which have lower barriers to entry and higher returns if you do them right. Some of them don't exist yet, but you could solo-deliver them in a number of weeks. There are many plausible goals you could have where solo-delivered gem X is vastly more valuable to you than "Got 3 patches accepted into Rails core."
I am a first year CS student and I really want to contribute to an OSS project, however, I can't find one that I can be productive on. For example - I thought shoes4 was suitable, but after looking at the issues, I honestly have no idea what to do. Something like Rails is probably absolutely out of my league. So where do I start? Docs, like you mentioned?
Docs are a great place to start. Getting started / installation guides, particularly for folks who can't use "the usual" install method, are easy and obvious wins. Curating existing answers into a categorized
FAQ is useful. Having a site rather than a Githubbed Readme is a win, and gives you numerous options to show off web dev skills. Failing that, you can pop open any jQuery plugin or well-used Rails gem, open up the issue tracker, and pick off an issue or two of low-hanging fruit. It might take you a day or two when it would take someone familiar with the codebase 15 minutes, but they clearly haven't done it yet, have they.
The first OSS project I ever committed to was an online Battletech platform. I found an O(n^2) algorithm via visual inspection of code that one of the core devs had mentioned was a hot spot, investigated why it couldn't be quicker, and ended up introducing a caching layer. (It was 10 years ago, but my vague recollection was that caching the results of the inner loop made is essentially O(n).) Immediate perceptible speed boost. The caching code was an abomination but it worked. (The story of my life, I swear.)
Wait, did you work on Megamek? That's...where I got my start doing actual released software too. I was responsible for a bunch of random-ass (and not so wonderfully coded, I'll admit, but I was 16...) features: protomechs, VTOLs, artillery...Hell, I learned Java from scratch to be able to work on Megamek. Those were the days...I haven't played Battletech in ages, but I miss it still, and there's always a nice feeling about the game in my head from its relation to the (very) beginning of my career.
I've authored and maintain a couple of Ruby gems. My perspective: some tasks are no fun and suck out my enthusiasm. I love help with those. Examples: update to work with the newest version of X, track down and fix reported bugs, answer basic user questions.
Think about what "chores" you can take off the maintainers' plate and you're likely to get a warm welcome.
"Rails" is both an ecosystems of projects and one individual project. You might not be able to contribute to the Ruby on Rails software library, but there are hundreds or thousands of third party apps & libraries built around Rails. If you contribute to them (or create your own one, or find something that is abandoned, etc..) you will be contributing to the "Rails ecosystem".
You probably need more experience building and maintaining web apps and general Ruby programming. There are three excellent webcast series that will put rocket boots on your feet. There's Avdi Grimm's RubyTapas,[1] Gary Bernhardt's Destroy All Software,[2] and Ryan Bates' RailsCasts.[3] I consider them required educational materials for the working Ruby/Rails programmer.
Most of the work I do is in java and ruby web apps. I've seen a lot of Railscasts, about 1/4 of DAS, and none of Ruby Tapas. I try not to binge on DAS because I prefer watching them one at a time and fully applying them before moving on. I think my problem is how big the codebase that Rails is and where to start contributing. I see your point to more experience but I'm not sure that's the crux of the issue.
I totally binged on the DAS screencasts. Then when I had trouble implementing anything, I'd go re-watch the relevant vids.
The reason I mention experience is because Ruby itself has a lot of convention that you only get really fluent with through repeated exposure. Just now I went and browsed to a random Active Record source file and had no trouble figuring out what was going on just looking at the source.
A year ago I would have been lost like you. But now I can take individual pieces of a big codebase and grok them without having to understand the rest of it. You only get that fluency through experience.
> For me, the code base is is incredibly intimidating.
You should spend some more time with the source. Honestly, a lot of the code base is better factored than I expected. ActiveRecord is a little hairy but otherwise it's really not that bad.
At risk of repeating the other commenters up-thread, the best thing you can do to get started is use the code. Eventually you'll hit a bug or an undocumented behavior, and at that point you are the most-qualified person to diagnose the situation.
Even if you can't fix a bug you run across, reducing it to a test case or a demo script is massively useful.
Finally, don't underestimate the value of a beginner in reviewing documentation. It's really easy for experienced users to look right past all the background "well, you should just KNOW this" information they're carrying around.
Read the code. If anything you'll learn a lot about Rails itself. Pick a small part, completely grok it, and then work outwards from there. I guarantee you will find something to contribute that way.
Just quickly – this is the general steps that I loosely follow for fixing bugs in Rails and other codebases that I don't fully understand (i.e. I didn't write the code myself):
1. Reproduce the issue: based on the reporter's comment, try to infer what the "buggy" behaviour is and attempt to reproduce it.
For Rails specifically, it means you need to get the code checked out and get comfortable running it locally. For Active Record and Action Controller bugs, you can use these templates as a starting point to create an isolated reproduction without making an entire app every time.
Sometimes this is not possible (the report is too vague, or you cannot reproduce it). In those cases, ask the OP for clarification and move on.
2. Is this "buggy" behaviour indeed a bug? Sometimes a lot bug report boils down to misunderstanding of the API, using the code in ways that the original author did not intend, or it's otherwise previously reported and closed as "won't fix" for various reasons. This is the part where the research skills you learned in school comes into play. It's not actually that different from, say, doing your research for an essay, you just have to map your skills to slightly different tools/problems.
Read the documentation. Understand the test cases. Get comfortable with using git blame (or the github blame view). Dig deep into the history of the method and figure out why it was added in the first place and for what purpose. Search the issue tracker. Read the previous PRs and issues that led to the code changes you are seeing. Study the commit messages. Ping the originally author (e.g. using @mentions on Github) if you are still unsure.
3. Once you are fairly certain that the reported behaviour is indeed a bug, you need to isolate the root cause. In some cases, after your research in step 2 you would already have a pretty good idea about this. In other cases, it's just like how you debug any other programs.
If you have a reproduction ready from step 1, this is going to be a lot easier. If not, consider starting by writing a failing test.Get a stack trace (e.g. "raise 'omg'"). Set breakpoints (or litter the code with puts statements). Basically you want to follow the input and trace it through the various steps and figure out where did it stop working the way you expect. Sometimes it's easier to do this top-down, sometimes it is easier to go from bottom-up (trace the output back to the input).
Another approach that works well for regressions (i.e. things that stopped working or works differently across releases) is to use git bisect to isolate the commit that broke the behaviour and try to relationship between the change and the bug.
4. If you did the previous step right, you should know how to fix the bug by now. Sometimes it is more difficult than simply reverting the offending change, perhaps because code around it and/or the overall architecture have changed significantly. Or perhaps because the offending commit was introduce to fix another bug, etc, and reverting it would negate the primary purpose of the commit. In those cases, you have to get creative and explore the different ways you can fix the bug. You can always document your findings up to this point and ask someone on github if you're unsure.
5. Once you figured out how to fix the bug, then you have to polish your patch. This means following the guidelines of the project and work it to the level that's acceptable for the project. In Rails, this means that you must write a regression test and follow the various guidelines we have[1]. CHANGELOGs, rebase, squash, commit messages, etc. Whatever it takes to make the project's maintainers happy. Once you did it once and figured out the tools, this would quickly turn into a brainless mechanical task.
6. Submit the patch. This is one of the most important step that everyone overlooks. As a responsible maintainer, I cannot simply accept/merge your changes because you claim that it fixed a bug and you have a passing test to go with it. I need to understand the problem and the code enough to help evaluate if you fix is good – whether it causes other unintended effects elsewhere, could it be simplified, is it going to introduce performance problems, etc. Make that easy for me. Explain the problem. Explain what the code is supposed to do and where you got that from. Explain why you chose to fix it this way. Do you have any doubts/concerns about this that you'd like me to help you figure out? Is there anything else I should be aware of?
If one or more of these things are missing, I'd have to spend time understanding them before I can evaluate your patch. If I don't have time to do that (which is usually the case), I might just have to move on to other stuff and park this for "later". Which is a shame, because you already did all the work to learn about these things. (Of course, I can't just take your words for it either. But at least make it easy for me to verify your findings. Linking the commits/issues/docs in the pull request and/or commit message goes a long way.)
7. Rework your patch. Sometimes you get questions/feedback from the reviewers. Address the concerns either by explaining your motivations or fixing the code as suggested. Rinse and repeat.
* * *
At the end of the day, this is just remapping your problem solving skills (which you are obviously very good at, since you are a programmer :) to the right domain and tools. I hope this helps!
If you are looking for things to do, I suggest that you digest what I just typed a bit and try to incorporate some of the ideas here into the contributing to rails guide[1]. Since you still have questions after reading that, obviously there are room for improvement :) Doing that will help save future wasd time as well as giving you a chance to practice steps 3-7.
Well, in that case, you got any plans this weekend? I'm sure we can find the student something else to work on if you fixed it for us over a weekend ;)
Anyone have any suggestions?
[0] Rebuilding Rail - http://rebuilding-rails.com/