July 27, 2015
My First Drupal Commit - Part Two
Today I’m going to dive deeper into step 1, but before I do that, you'll want to make sure you have a certain minimal tool set installed on your machine. Most if not all of these are free or shareware, and in some cases are absolutely necessary to get the job done. Note: I'm using a Mac but these instructions apply to Linux and Windows as well. I'll provide links to these tools so you can download and learn about installing each of them.
- We will be using the Command Line Interface (CLI) for this work. Don't be intimidated by it like I was when I first started; it really is the fastest way to work. On the Mac you can use the built-in CLI, "terminal," but I prefer to use the free iTerm2. Either one will work.
- drupal.org uses Git for version control so you will need to download and install Git for your local machine.
- Do yourself a favor and install Homebrew. It’s a package manager that will make your life easier. We will use it to install patchutils, which will help us create an interdiff file.
- I highly recommend dreditor, which is a browser plugin for Chrome, Firefox, and Safari. It injects several useful buttons into the drupal.org issue page, most notably the “Patchname suggestion” button, which we will discuss below.
- Find an IDE (Integrated Development Environment) like phpStorm, or one of the many code editors out there. I like BBEdit and Sublime Text.
- If you're an experienced CLI user, or even not, like me, you will love Fish Shell. Its autocomplete alone is worth the price of admission, which is free. You will see its colorful and useful output in the screenshots below. Not necessary, but recommended.
- And lastly, it’s nice (but not necessary for this) to have a LAMP stack running on your machine to use for testing. And, well, just because you should have one anyway. I use MAMP Pro but there are many options out there.
The Path to Contributing
Step 1: Find an issue to work on.
It's crucial, especially if you're just starting out, to find an issue that you can contribute to successfully. I don't advise getting into the weeds with code or critical core issues until you know the process of contributing. Again, that's what we're here to discuss, how to contribute. The “why” should be obvious, and the “what” can come later and is up to you, but for now I recommend searching the Drupal 8 issue queue for issues tagged "novice" and "documentation." That's what I did and I'm glad of it. This is so you won't get bogged down in trying to figure out deep core code, and you can get right to the process of contributing.
It's also important to learn the preferred style of Drupal documentation. It's specific, and for a very good reason. So, here's a link that will take you to a list of good potential D8 core issues. (Notice the keywords in the query.)
For the record, here’s a link to the first issue I found and contributed to. It consists of documentation for the SimpleTest module that is now part of D8 core and has been renamed “Testing.” I’m Drupal user trgreen17 so you can read and follow my comments and patches. And again, this being my first commit, you can see my hesitation and timidity at the beginning of the issue, and also the time it took me between patch uploads. But by the end you can see that my confidence and speed had both improved, in no small part to jhodgdon’s considerable patience and excellent advice. We’ve all heard it said that the Drupal community is friendly and approachable, and if you read this issue you will see direct evidence of that!
As of this writing my patches have been accepted and the issue went into “RTBC” (Reviewed and Tested By the Community) and back out into “Needs work” and “Needs Review.” This is what’s so cool about the community. As I am taking a break from contrib work and my new project to write this post, another user has picked up where I left off, and it might even be committed by the time you read this. It truly is a worldwide team effort.
You can see in this issue that at first I was simply doing what was asked, and I didn't really read the module’s code, which of course is necessary in order to document it. I must admit, like you might be thinking, that documentation seemed like a trivial thing at first, but then it occurred to me that developers would use it for years! In some ways it’s as crucial as the code itself and is a perfect way to start this part of your Drupal life. I made some silly mistakes at first as you can see, but the community didn’t make me feel bad about it, and was very patient. This helped tremendously with my confidence. Tomorrow we’ll continue on to step 2 so be sure to check back in.