Bug Fix Workflow
Below you’ll find the proper way to go about fixing bugs in our work environment. This workflow can be adapted to your personal work habits but please remember you are working on a team and any changes you make to this workflow have to be compatible with the team’s vision for the project.
A new Redmine issue comes up stating there is a bug in your project. Your first step should be to read what they wrote.
A bug report should have all of the following:
- Description of the problem
- Expected vs observed results
- Affected version(s)
- Steps to reproduce
- Data required to reproduce
- Contact information
- Priority
- ….
Things you should consider:
- Can you understand what’s written? – Issues can often get written quickly as the user is busy and feels that logging bugs in Redmine is a waste of their time. Maybe they’re right, maybe they’re wrong, either way ,if they want it fixed they need to make sure their description makes sense.
- Is this a bug or a feature? – We’ve often noticed that some users believe the software should work a certain way and if it works differently, then it’s a bug. Many times this is just a request for something new. If that is the case, re-categorize the issue and move on (be ready for backlash).
This is when you open a text editor. Look at code. See what needs to be done.
Your customer has in their hands a particular build. You need the code that they are running. Look at what build they have and get the code from there, chances are you’ll want to checkout a particular git branch.
For example:
git checkout master
Next you want to make a branch for your bug fix.
git checkout -b issue#
You’re now on a new branch named after your Redmine issue. You can really name your branches whatever you want, but when we look at merge commits it’s a bit easier to search by issue#.
You should try splitting the task into as many steps as possible. Each step should get its own Redmine issue that is a subtask of the original bug. Use the tracker type Task.
“Test? I haven’t written any code yet!”
You know what is expected to happen. Write a unit test that gives your bad code input and checks that the right output is given. (this step should have its own Redmine issue).
This is how you go about doing that
Git is all about short lived branches. You’ll want one for each sub-task you create in Redmine related to any coding you’re going to do.
That’s it!
A basic unit test’s data consists of two things. Inputs and valid outputs. You’ll need various examples of different kinds of data you’ll get. You should even include invalid inputs that might come up from bad csvs that customers try to load.
Write a test that takes your input, passes it to your buggy code and then reads what comes out. That’s all your unit test has to do.
You can learn about staging by reading the manual.
Again…rtfm
Your commit message should be meaningful. Seriously. If you write a commit message with something like I made some changes you will be mocked.
Your message should:
- make reference to the Redmine issue#
- describe what you wrote
That’s pretty much it.
If you did something particularly complex in your commit, you can describe it in your pull request
Next step is to merge your unit test code into your bug fix branch. There are a few ways to merge.
The first is a standard git merge issue# which will simply merge the code from the branch issue# into the branch you’re currently one. Git does its best to do all the hard work but sometimes you run into conflicts that you need to solve. If this happens, you will need to commit your merge. This generates a new commit object in the git history with a message saying that you’re merging branch B into A and that files X,Y and Z had conflicts. If no conflicts are found, no new commit is created and you have a nice straight git history. This is called fast forwarding.
Another handy way to merge is to disable fast forwarding. You do this by adding --no-ff to your merge parameters. What this will do is always generate a new commit even if the merge resolves itself. Whenever your merge contains more than a couple commits you should disable fast forwarding. Why? Because sometimes you make a mistake and you have to go back. If your mistake contains a bunch of commits, you’ll have to revert each and every one of them. That will take a long time. If you’ve only got one merge commit to revert, it’s fast to fix! Problem solved.
Now it’s time to actually make changes to the program’s code.
If you haven’t already, log another Redmine issue for your code changes.
More branching. Are you annoyed yet? No? Awesome. Yes? That’s unfortunate.
Create a git branch for the new issue you’re working on.
…
You made a unit test for this, give it a shot! If it fails, fix the problem.
You know how to do this because you’ve ready the rest of this guide!
Easy peasy lemon squeasy.
Git has things called pull requests. Basically they’re messages from one developer to another saying “Hey, I have this branch I’d like you to merge into your branch, whatcha think?” Github has a nice gui for doing pull requests. Github even has instructions on how to use them.
You should be generating a pull request from your bug branch to the master branch. Please make sure you get this step right as you can’t change the to/from branches from github (yet).
In your pull request you can describe what you did. This doesn’t mean redescribe the problem. That’s in redmine. Talk about how you fixed it. Customers generally don’t care but other developers love reading how other people solve problems. So show off.
Now you play the waiting game. What are you waiting for?
The code review step. This is the horrible angry mean part. Where you will be judged. You will be criticized. You will be praised. You will be publicly humiliated.
It is up to your colleagues to accept or reject your pull request. Github has a notification system for repositories that you’re watching so your team should see a little blue dot in their github home page. One of them should open up your pull request and see what you’ve done.
If they accept and merge your pull request, you can mark the redmine issue as Testing. This means that whoever is handling QA for your project can now test your fix and determine if the customer can pick up a new build and not hate your software anymore!