Contributing a Bug Fix
This is a simple exercise for those interested in contributing to Bricolage. Say that you find a bug in Bricolage, or decide to fix an existing bug reported in our ticket tracker. I’m assuming that the bug is in the main branch of the project, master. Assuming that you have read Working with Git and are ready to start hacking on your forked repository, let’s get started:
cd bricolage git checkout master git pull git pull upstream master
What you’ve done here is to check out the master branch and to make sure that you have all the latest changes from both your forked repository on GitHub and from the Bricolage project’s upstream repository. Now you’re ready to fix the bug. All you have to do is create a new branch and start hacking:
git checkout -b 1449
This command creates a new local branch named “1449” and checks it out. I’ve named it as such for the bug number. And I say “local branch” because it only exists in the local repository; think of it as a working branch to be used just for the duration of fixing the bug. So now, go ahead and fix it! As you work, commit early and commit often. You can use git add to add one or more files to commit and then commit them:
git add lib/Bric.pm git commit -m 'Fixed typo in `Bric.pm`.'
Or, if you don’t add any new files, you can commit all your current changes at once with git commit -a:
git commit -am 'Removed the `$Id` variable from all files.'
We strongly recommend that you write Git-preferred commit messages, as they will really help you to review older commits in the future.
Also, there are some great tutorials and howtos out there, so check them out for more on day-to-day use of Git. Overall, you’ll want to commit in lots of small commits rather than one big final commit, so that you can easily go back and change things if you need to.
When you’re done, the bug is fixed, and all tests pass, make sure everything is committed and then push the branch to your forked repository on GitHub (using the nifty Git 1.7 syntax):
git push origin --set-upstream +1449
Great! Now your own fork has the changes on GitHub, free to be pulled in by anyone else who has cloned your fork. But your aim, of course, is to get the bug fix into the project repository. Chances are good that a project administrator will see your bug fix sooner or later and simply pull them in.
But if you’d like to alert them to the fix so that they pull it in sooner rather than later, hit the home page for your fork of the project and click the “New Pull Request” button. This will open up a lightbox window in which you can type up a message to the project administrators, perhaps something like:
Fellow Bricoleurs,
I’ve fixed Bug #1449 in the branch named “1449” in my fork. As you know, this is a particularly insidious bug that has affected a lot of our user base. I think it’d be worthwhile to pull it into the project repository in order to get it into the next release of Bricolage.
Thanks!
Be sure that the checkbox next to “bricoleurs” is checked and then hit the “Send Pull Request” button. There, you’re done.
Once we’ve pulled your bug fix into the main repository, your next git pull upstream master will fetch it into your local copy. You can then drop the “1449” branch and push to your GitHub fork to have things all synced with the upstream repository:
git checkout master git pull upstream master git push git branch -D 1449 git push origin --delete 1449
Thank you for your contribution, we greatly appreciate it. And we hope you enjoy hacking on Bricolage on GitHub.