Bug fix and new feature review process
Need help? The Energia discussion forum is hosted on 43oh.com.
The goal of this process is to allow for authors to easily share / review / discuss newly implemented features and bug fixes before pushing them into master. The review process will have an author (thats you), the reviewers and the moderator who will give it a final blessing.
This process evolves around topic branches. A “topic” branch is a separate branch that you use when working on a single “topic” (a bug fix, a new feature, or an experimental idea). Working on a topic branch instead of directly on top of “master” is recommended because:
- It allows you to work on multiple, separate topics simultaneously without having them all jumbled together in a single branch.
- Topic branches are easily updated, which means that if the remote “master” evolves while you are working on your topic it is easy to incorporate those changes into your local topic branch before submitting (which in turn will make your topic apply cleanly on top of the current “master”).
- If you receive feedback on your patches, having all the related changes grouped together in a topic makes it easy to tweak them and resubmit.
- Working on a topic branch makes it easy to refactor a patch series into a logical, clear, clean sequence, which in turn makes your contribution easier to review and more likely to be included using the git rebase command.
You are finally ready to address that bug or add that new feature that you have been thinking about. First think you need to do is to create a topic branch.
git checkout master
example:
git checkout master Already on 'master'
Rules for naming your branch:
- If you are adding a new feature, give the branch a name that in short describes the new feature and post fix it with _feat. e.g. when adding a Capacitive Touch library call it cap_touch_feat
- When addressing a bug, you must use the format issue_<issue number>. e.g. issue_31.
git checkout -b issue_23
example:
git checkout -b issue_23 Switched to a new branch 'issue_23'
It is good practice to make sure you are on the right branch before you begin or continue your work using git branch.
example:
git branch * issue_23 master
Now that you have your topic branch setup, it is time to work your magic. You are free to use whatever method you are used to to implement the feature or fix that bug. Try to limit the number of commits you do along the way. This will make it easier later on when we prep the branch for push. If you are working on something for which an github issue exists then do reference that issue in your commits. The format is: Issue #<issue number> e.g. Issue #23. The beauty of this is that once you push your branch all your commits that reference the issue will show up in the issue.
Please do consider following the guidelines set out in Coding Style.
Once you are happy with your work, were it a bug fix or a new feature, it is time to prep your branch for a push up stream. If you have done a log of committing along the way then consider using git rebase to compound commits into one commit, re-order commits or amend your commit comments. Github provides an excellent rebase how to. For the purpose of rebasing our topic branch issue_23 we can run:
git rebase -i
Now that your patches look clean and you are happy with the results, it is time to push the branch up. To push our issue_23 branch up we can run:
git push origin issue_23
example:
git push origin issue_23 Counting objects: 5, done. Delta compression using up to 2 threads. Compressing objects: 100% (3/3), done. Writing objects: 100% (3/3), 329 bytes, done. Total 3 (delta 0), reused 0 (delta 0) To git@github.com:robertinant/topics.git * [new branch] issue_23 -> issue_23
Not that you have pushed everything up, you can start the review process by issuing a pull request. On github, navigate to the code page, select the branch you just committed and press the Pull Request button.
After pressing the Pull Request button, you are presented with a preview page where you can enter a title and optional description, see exactly what commits will be included when the pull request is sent, and also see who the pull request will be sent to:
Switch to the Commits tabs to make sure you are sending the right commits.
Switch to the Files Changed tab to review the diff of changes.
Once you’ve entered the title and description, made any necessary customizations to the commit range, and reviewed the commits and file changes to be sent, press the Send Pull Request button.
After pressing the Send Pull Request button you will be taken to the Pull Request discussion and review page.
note: There is another way to send a pull requests, attached to a GitHub issue, using the hub script. See using hub for more information.
When you receive a pull request, the first thing to do is review the set of proposed changes. Pull requests are tightly integrated with the underlying git repository, so you can see exactly what commits would be merged should the request be accepted.