Development Workflow

Following steps should be followed from inception of a feature request or bug identification to deploy of changes that address that issue.

1. An issue pops up in the issue list that clearly describes the bug or feature request that has to be addressed. This issue is assigned to appropriate developer.
2. The developer creates a new branch in the form of XXX-some_description(where XXX is the issue number). This branch will accumulate all the changes addressing issue in context.
3. The developer starts working on the issue after understanding all the requirements. He keeps on pushing the changes to the branch created in step 2.
4. After developer is done with coding, he pushes the branch to origin and initiates a pull request. He assigns this pull request to another developer for code review.
5. Code reviewer reviews the code while making sure that all the test cases pass and presence of test cases for new code changes. A code reviewer should add comments in the pull request for anything that could be improved. He should tell the developer about those comments. If review is not good, the developer should start at step 3 again.
6. If review is good, original developer should merge the branch in originating branch after squashing all the commits in one single commit. Label the issue ready-for-testing and assign it to QA. If the change cascades, affecting non-obvious areas of the app, add a comment in the issue describing what to test.

The Github merge button should not be used because it creates a merge commit. Instead following steps should followed on command line.

    git checkout xxx-some_description # Checkout the feature branch.
    git rebase -i HEAD~n                    # Squash all the commits. #n is the number of **new** commits on this branch.
    git checkout master              
    git pull origin master                  # Update master
    git checkout xxx-some_description       # Checkout the feature branch.
    git rebase master                       # Rebase feature branch with master. Follow the rebase instructions to fix any conflicts.
    git push -f origin xxx-some_description # Update the pull request with rebased code.
    git checkout master              
    git merge xxx-some_description          # Merge feature into master.
    git push origin master                  # Push the code changes to origin.

7. If QA is not good, issue should be reassigned to the original developer. Original developer should start on step 3. The same branch created in step 2 should be used to accumulate new changes after QA.
8. If QA is good, the branch created in step 2 should be deleted from repository. And QA should label the issue as ready-for-production.

Note: Squashing commits in step 6 above is very important. Non squashed commits are extremely difficult to release to production because they can not be easily reverted.

---

Releasing code to production

1. Find out all open issues with label ready-for-production.
2. git checkout production
3. One by one, cherry-pick squashed commits from each issue to production branch. (can use git diff production..<ref_on_master> to check that the code is consistent to a certain commit on master)
4. Run all the tests and make sure they are green.
5. Create an annotated tag following our versioning policy. Push this tag to origin.
6. Deploy latest tag to production. bundle exec cap production deploy.
7. Do a smoke test on production and make sure things are working. If everything works, label all deployed issues with deployed and assign them to QA.
8. If something is broken, deploy previous tag to production. And work on fixing the issue following Step 1 in development workflow above.
9. QA checks issues labeled as deployed and closes them if they work as expected on production.

---

There are a few guidelines that should be followed before committing your code changes to the repository.

1. A Github issue number should be present in every commit's message.

Although we try to make sure that our commit messages are explanative but sometimes we do not write good commit messages. "Fixes" and "Some minor refactorings" are not good commit messages. Therefore we must add a github issue number with every commit message. Github links the issue number with the corresponding issue in this project's issue list. This way even if a commit that does not have a good commit message, will lead to a Github issue. That issue will have explanation for which the commit was made. We can find out the reasons for which a change in code took place at any point of time.

One can put issue number anywhere in the commit message. But it is advised to put it at the beginning or at the end of the message. I(Waseem) myself prefer at the beginning of the message. Following is an example of a good commit message with issue number.

"ISSUE #268 Adds Storybook#compile." OR "Refactors App.Models.Storybook ISSUE #175"

The string that describes issue number should be of the form "ISSUE #XXX" where XXX is the issue number. It's important that we have a # before the number string else Github wont link it with corresponding issue.

Remember a good commit message reflects a developer's good intentions. Including an issue number is not a substitute for a bad commit message.

2. There should be a Github issue for everything that requires us to make a change in the code base.

Issues on Github should have proper title and explanation. Collaborators can start discussions around these issues. This will make sure everyone's comments and concerns that is related with a bug or feature are at one place. And it's easier for people to find things. Since every commit should have commit message, it's opposite should be true as well.

An issue should be assigned to a person all the time. So that we know who is working or going to work on it.

3. When reviewing code, people should comment inline in the diff in a pull request and not on an individual commit.

This makes sure all the discussions are at one place i.e. in the pull request issue.