Welcome back! The last post in this series got you set up and ready to contribute and took you through step 1. Today we'll take a look at steps 2 to 4.

Step 2: Download the latest Drupal core to your local machine.

You will of course be working locally on your issue, so the next thing to do is download the latest (non-beta) version of Drupal to your machine. On the Mac there is a default “Sites” folder. Within that folder I made a new folder named “contrib” so I can create a Drupal codebase folder for each issue I tackle, since I plan to keep contributing! So in my CLI, I navigated to the “contrib” folder and ran the following git command:

git clone --branch 8.0.x http://git.drupal.org/project/drupal.git 2299361

You can refer to any number of git help resources (including typing “git help” in your CLI) but basically this command will clone the 8.0.x branch of Drupal into a folder named 2299361, which you might have noticed is the (node) number of the issue I chose to work on first. In the future I’ll change the clone command to reflect each issue number I work on. This makes sense to me as it will keep all my issues separate and in order, but do whatever works best for you. This ended up being a good idea because working on this issue lead to working on actual code in core on another issue, more on that later.

Step 3: Create a new branch and download and apply any existing patches

This one threw me for a loop at first but it’s very important! It will get you a safe working copy of the codebase and will ensure that you’re working on the latest version of your issue. There are two things here: creating a new branch and applying existing patches.

The reason to create a new branch is so you can revert back to the core install if you mess up beyond repair. Version control and branching is beyond the scope of this article, but just think of this step as creating a backup of your codebase and working from a copy of it so you can revert. It's always a good idea. The git command for this is pretty simple:

git checkout -b 2299361

This creates a new branch named 2299361, again, the issue number I’m working on. It might have been a good idea to name the branch “01” or “a” so you can create even more branches, but I was keeping it simple. Incidentally, if you edit your bash profile and add the following command, your command prompt will always show you the current branch. I find this to be invaluable. Special thanks to my colleague jmolivas for helping me with this:

# Git branch in prompt.

# parse_git_branch() {

#     git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/ (\1)/'

# }

# export PS1="\u \W\[\033[32m\]\$(parse_git_branch)\[\033[00m\] $ "

Since I added this to my bash profile and use Fish Shell, my command line looks like this after running the git checkout –b command:

This tells me that I’m in the folder 2299361 and that my git branch is 2299361. This might seem redundant, and again, in the step above you might want to name your branch something more meaningful in case you use multiple branches, but it was comforting to me as a contrib novice to see that issue number twice. Go figure.

Okay, now that we have a new branch to work on and we are in the right directory, it’s time to get the codebase up-to-date. In my case, the user wadmiraal had created several accepted patches so I wanted to make sure I applied his latest patch to my codebase so I could accurately extend his work. I found the latest patch he made (comment #13) and applied it. There are several ways to do this, but I will outline my approach below:

1. Search for the last patch on the issue you’re planning to fix and right click on it, then click on “Copy Link Address” (or similar in your browser). This puts the URL of the patch on your clipboard.
2. Use the curl command to download the patch using the URL you copied above. In my case it was this command:

So now our codebase is exactly as he left it, ready to be worked on. Whew! I know it seems like a lot, but all we did in the steps above is download Drupal core to our local machine and apply the latest good patch to our codebase so we could start working.

Okay, now might be a good time to grab a cup of coffee and back up your machine! I can’t remember where I read this – I may have even made it up – but I always go by the maxim: “Digital data doesn’t exist until it’s been backed up, and you don’t own it until it’s been backed up twice.” So true. The Mac has the awesome Time Machine built-in to its OS, but other platforms have similar systems. Use them!

Step 4: Complete your work

Believe it or not, this will be the shortest step in this how-to series. Your work will be completely dependent on the issue you choose. I chose a documentation issue so my job involved reading and learning the code so I could document it properly.

You will see some early mistakes I made in that regard if you read my issue. Okay, so as I was writing the proper documentation I also learned that there is a specific format for Drupal documentation, and it’s there for a reason. Among other things, the Drupal UI uses this formatting for display as you are building a site. You can learn about Drupal documentation and coding standards here. I highly recommend it: 

Once you’re confident that your changes are correct, the next step is to create a patch and an interdiff file and upload them to the issue. So please read on, we’re rapidly approaching the finish line!