Version Control Source Code

Git Strategy

Branching

This project leverages the popular Git-Flow as a general rule. If you're not currently using it, consider learning more about git flow.

tl;dr all work is done in feature branches, these merge to develop which branches a release which is then merged back into both develop and master. Hotfixes are based on master and closed on merge to master and develop.

Commit messages

Commit messages should reference the story/issue addressed, and must include a brief summary of the change proposed (this should be about 72 characters in length). The summary should be followed by a paragraph description of the change, intent, and explanation of any decisions made as part of the commit. This helps frame the story and lead to more meaningful code review feedback.

In this vein, a PR should consist of several small commits instead of one large one. Incremental progress is easier to follow and review and a more natural workflow.

Pull Requests

All PRs

• should follow the style guidelines
• must maintain or increase test coverage
• reference the story/issue they address
• call out any new dependencies added by the PR
• check PR build results and resolve any issues
• be made against the develop branch, or explain special circumstances why they are made against another

Installing Git Flow

Mac

Like most things, this is made extremely easy by the homebrew package manager. Just run brew install git-flow. While you're at it, run brew install git as well to get a more recent copy of the git program than Apple installs.

Unix

Depends on your distribution, but if you're using Linux for development, first off hats off to you, second, you probably don't need my install notes, but finally, you can install through your favorite package manager. On CentOS run yum install gitflow, on Debian it's a little tricky but explained here pretty well.

Windows

I'm sorry that I'm not more familiar with this workflow. I don't develop on the windows platform. I'd recommend considering running a virtual Linux box for doing development or using Docker so these are non-issues, however, you can also reference this article for a pretty good explaination about the hoops to make it work natively on windows.

Advantages

This method ensures that:

• the master branch has a tag for each commit layer, which matches production releases exactly
• the develop branch holds the latest features ready for testing and quality assurance
• each new feature is broken into a features/[description] branch for direct tracing of activities
• new release candidates are built in a release/[semanticVersion] branch to do last minute changes before releasing to production
  • version increments
  • dependency lockdown/updates
• hotfixes are supported

With its convenient plugin for Mac and Windows development platforms, even with simple understanding of the CLI concepts, the convention is easy to follow.

Using Git Flow

To start, run git flow init -d to initialize git basics in your repository.

Then to work on a feature run git flow feature start [myFeatureName]. Then make your related commits, and finally run git flow feature finish [myFeatureName], which will collapse the feature branch back into develop. To simplify your workflow, please pull the organization's develop branch before finishing your feature and pushing your updated develop branch to your fork; then, raise your pull request from your completed feature set to the organization's develop branch.

Merging

An ongoing debate continues in many open source communities around how this is best accomplished. For this organization, all merges should be conducted as rebase actions.

If you're new to rebase-ing or have unanswered questions this introduction blog post is excellent. This practice maintains the overall revision tree.

The workflow is slightly more complex, but the long-term benefits make it worth it to learn. Check out the workflow here.

Release Conventions

This project follows Semantic Versioning as a release schema. Release candidates will be announced via Issues, so please watch the project to get the latest updates and all completed features will be included in a release.