When a project is maintained by a team (more than 1 developer) it's highly required that this team follows some coding rules and guidelines. This will keep source code tidy and easy to support.

But project is not only code, it's also a repository in VCS (Git in our case). We store all code on github.com, but also have heroku repos, which we use for deployment purposes. The way repos are updated determines how easy and productive the project can be maintained and moved forward.

This page describes development workflow, which includes branch naming, commits convetions, code review and a few more git best practices.

Here you go:

• The master branch is stable and safe to deploy
• We keep our releases and versions in the production branch
• To work on something new, choose a ticket and create a descriptively named branch off of master
• Commit to that branch locally and regularly push your work to the same named branch on GitHub
• When you need code-review/feedback or help, or you think the branch is ready for merging, open a pull request
• After someone else has reviewed and signed off on the feature, you can merge it into master
• Once it is merged and pushed to ‘master’, you can deploy it;

That is the entire flow. So, let’s look at each of these steps in turn.

This is basically the only one hard rule. We have to keep the master branch stable and safe to deploy or safe to create new branches off of it. When we got enough features to release, we merge them all from master to production branch and then make the new release of the app.

IMPORTANT: Nobody can push to master directly, if you have something that you'd like to push - open a pull request.

When you want to start work on anything, you have to choose a ticket and create a feature branch off of the stable master branch.

We use built-in GitHub Issue tracker to store all stories for the project. In this case, if somebody needs to get a new story, then he or she should go the Issue list, choose correct milestone and take some, that he/she thinks would be good for him or her.

If you need to file a bug or submit an improvement or add another story, you should think about the following:

• To report a new feature. Check another stories for current milestone, maybe it's already there. Check if that has already been described as a part of another story?
• Make sure you put right order for your new story (right priority)
• To report a bug make sure you put Steps to Reproduce (STRs), it's mandatory.
• To report an improvement, explane your point and provide pros and cons.

You have a ticket and you ready to go, now let's see how to create a feature branch based on our naming conventions:

Branch naming: g<issue_number>_<your_initials>__(double_underscore)_<feature_description>

Naming is very important

Example: git checkout -b g17_avd__github_helper

When you have something valuable that you'd like to add to the repository, you can add these changes and make a commit.

Each commit in git should have a message. The main purpose of the commit message is a description what this commit brings new to code and why. There are some rules how each developer should comment his commits:

• Each commit message should have a summary line which shows issue number and brief information in a format: Refs #12345 - New column added to Account (One line up to 60 characters long)
• Empty line
• Description: verbose information why commit changes are implemented (keep each line up to 72 characters). Don't forget to end sentences with dots.

It is important to wrap summary and description as it makes easy to read "git log [--oneline]" output in console and on github. Example:

Bad:

Refs #17 - Add helper and describe gtihub workflow and add ability to attach pull requests to exiting issue

Good:

Refs #17 - Added rake helper to deal with github pull requests

It is used to attach pull requests with all commits to the existing
issues on GitHub Issue tracker

When you need to get a code review or feedback from your team members, you send Pull Request to the team. Just push your local commits to the remote branch and click compare & review button(see image below) for creating PR.

Git Branching model

Git cheat sheet