Github Workflow

Describe how we use github in our daily activities. Tell more about hub and other github utilities … Ensure each commit is tied to an issue number [shell script] https://github.com/uberVU/thehole/pull/5502#issuecomment-13822089 Keep your commits small! https://github.com/uberVU/thehole/commit/b7c104894605fade60efb4097d31683bf1db2dad

How does uberVU use GitHub to organize work?

First of all, let’s rule out bugs: they are created in Asana by our non-technical team and after they are signaled to and diagnosed by the development team, they are translated into one or more GitHub issues for the problems at hand.

It’s good to create a GitHub issue for one isolated problem, because solving an isolated problem will usually be deployed faster. Also, it’s a good idea to explain what the bug is about, so if other colleagues want to learn from your work (and believe me, they will), it will make things easier for them. Also, it helps keep the team aware of the problems in the product.

Usually such a bug will either be created into the “Bug” or “Chore” milestone. All other issues will be created into a per-project milestone, which will contain in its description a link to the Google Doc with a minimal technical spec of the project. When a new project is created, such a milestone will be created too - and after some initial discussions and technical spec-ing, there will be a number of initial issues to work on. Having a milestone helps developers and management personnel know the progress of each project and the (approximate) percentage of work already done. This doesn’t mean that if a project’s milestone is 90% done it can be shipped tomorrow, but if it’s 50% we know for sure it will take a while.

How do I work on an individual issue?

First of all, assign it to yourself and make sure it has the proper labels and that it’s in the proper milestone. If you feel the description is incomplete, feel free to complete it and to also include a working plan in the issue description.

Create a branch containing the issue number with the format:

f/#3199-reports-master-branch

where: - the prefix can be f/ (feature), b/ (bug), c/ (chore) - #3199 is the actual issue number - reports master branch is a short human-readable description of what the branch is for

Adhering to this naming convention has several advantages:

1. When I see the master commit log, I can immediately spot when a bug, a feature or an improvement has been deployed (due to the prefix of the branch name).

2. Having the branch name contain the issue number makes it easier to trace back to the issue and to some more context.

3. Having a short, human-readable description will give you an idea of what your colleagues are working on when you do a “git fetch” - notice how you gain an immediate overview of what someone else has been working on since your last git fetch

4. Doing a “git branch -l” will list features grouped together in chronological order, bugs, etc.

So: - create the branch - create individual commits in the branch, describing with a short message what the commit was actually doing. For example, if in the function foo(x) I’m treating the edge case x == -1, and I’m committing a fix to that function and a test, I might write the commit message “Making sure that x == -1 works correctly. (#1234)”. Notice that the #1234 in the commit message is the issue number striking again. Some people choose to include the file name in the commit message but please note that it’s already stored in the meta-data of the git commit. - when you’re finished writing commits, push your branch to github and make a pull request (either to master, or to the project master branch) - wait for your colleague’s feedback. If you’re merging the branch immediately, there’s no point in creating a pull request at all - you might as well commit your code to master directly. The pull request is for you to obtain feedback - deploy it on live or fix your stuff (be it bugs signaled by QA or feedback from your colleagues)

Now, why is it important to put the issue number in each commit? 1) all work being done for that issue will appear on the issue page 2) when you do git blame on a modified file, you will know the cause for each line being modified. When you see the issue number next to a row you don’t remember why it was modified, you will be able to click through and gain more context. Especially useful for the core parts of the system, which get modified pretty often. 3) when you see the log of each file (using git log), it will give you an overview of when and why this file was touched. Let me give you an example from Mozaic’s core/base_model.coffee:

commit b335e839a2a0b4dbb71551bff706287d4ac38c0f Author: Valentin Zberea [email protected] Date: Mon Dec 10 13:41:01 2012 +0200

no need to override toJSON in base_model #3716

commit 1de5bc4c99a7c740f531ef41de7c729a15a19d08 Author: Andrei Ismail [email protected] Date: Mon Dec 10 13:10:31 2012 +0200

toJSON() in backbone model is not bound to correct this. (#3716)

commit 7591a1a24a138b6478aca85626018f2d030d1e57 Author: Ovidiu Chereches [email protected] Date: Fri Dec 7 18:11:08 2012 +0200

Added the entire set of attributes in the base model custom set listeners #3643

commit 96b836adbc2946296a6ddde1b062199938710426 Author: Ovidiu Chereches [email protected] Date: Wed Dec 5 13:59:19 2012 +0200

Enhanced base model's custom setter listeners #3581

commit b2ccba12e4aa1ed6f9daa17d44478cde75a84c9f Author: Ovidiu Chereches [email protected] Date: Tue Dec 4 23:50:24 2012 +0200

Create support for individual setter listeners in base model #3581