Inaka's Development Flow

Inaka's Development Flow

In all of our projects (specially those hosted in our own github repositories) we work with Pull Requests and Code Reviews. The process in a nutshell is:

• Grab a pivotal story/jira issue/github issue and mark it as started (e. g. let's say I want to work on piv #123456 which is a piv story about editing this document).
• Open a branch with your name and the story id on it (e. g. elbrujohalcon.123456.edit.this.document). One or more commits per pivotal story, but no more than one pivotal id per commit.
• Tag all your commits with the story id (e. g. git commit -m "[#123456] First edition").
• Once you're done, submit a Pull Request in github and assign it to a colleague of yours to review it (if none of them are available, assign it to your CTO).
  • While you wait for that review, you can pick a different task and start this process over. If the PR is a blocker, warn whoever is responsible to communicate your block.
• When opening a pull request to generate a page on which the changes can be discussed, make sure to have [WIP] at the beginning of the pull request title so that it is not merged. When the discussion concludes, change the title to remove [WIP] and notify the reviewer so they can merge the pull request.
• The reviewer will then write comments on the PR and you'll have the chance to discuss them and/or fix them.
• We also have automated tools (like elvis) that will review your code.
• When the review is done, your reviewer will merge your code into master.
• The branch should then be deleted.

Note that, mostly depending on the language and the product, there might be some exceptions in the aforementioned workflow, but the PRs and Code Reviews will always be there. We embrace code reviews for a number of reasons:

• It helps the devs spot small issues that would've gone undetected without a review.
• It keeps the general knowledge of the projects shared between, at least, two people.
• It's a great way to spot and learn useful practices and to start defining guidelines.
• It allows automatic code-style checking to be performed by special tools, like elvis and houndCI.
• It keeps a nice and shinny git history that let us move back and forward in history and understand what happened and why during the course of the projects development.

To get all the best from code reviews, while either submitting or performing a code review, keep in mind the following points:

• Adopt a positive attitude!
• Try to evaluate the actual code (Is it easy to understand? is it maintanable? Are the right data structures being used? Are the variable and function/method names descriptive enough?, etc) instead of the formatting. Ideally the formatting should be validated by automatic tools, not by humans.
• As a reviewer, try to break your reviews into short sessions instead of one long time consuming session. Also, try to have your own personal checklist of things to check for.
• As a submitter, keep your code short. The idea of a code review is to catch possible bugs, not show how much you can type in an hour.
• If your methodology is to collapse multiple stories into one PR, try to create at least one PR a day. Don't let your PRs grow over time, if you can avoid it.
• Don't forget to link PRs with stories/issues/etc. by adding [#PIV-ID] to the PR description
• You can easily reduce the burden of the whole workflow to just 3 commands using AW.
• The blog post "Effective Code Review" has a nice discussion of this topic.