Skip to content

Contribution Process

Jump to bottom
Nicholas Hubbard edited this page Mar 5, 2018 · 3 revisions

Following the dramatic situation at the 2018 Southfield District Event, I have decided to begin enforcement of a new policy regarding code changes. Starting immediately, the following controls will be implemented:

Git Flow

Git Flow is a workflow design that was first published by and made popular by Vincent Driessen at nvie.

Git Flow is an ideal solution for this repository due to its model of branching for changes. This workflow does not add any new concepts or commands beyond what's required for the Feature Branch Workflow. Instead, it assigns very specific roles to different branches and defines how and when they should interact. In addition to feature branching, it uses individual branches for preparing, maintaining and recording releases.

How to use it?

Instead of maintaining a single master branch, this workflow uses two branches to record the history of the project. The master branch stores the official release history exclusively, while the develop branch serves as an integration branch for new features. It is also a convenient way to keep track of releases, as it simplifies tagging releases to each major commit on the master branch.

Our repository has already been initialized with Git Flow support. From hereon, all new commits should be pointed at the develop branch.

Should you accidentally (or purposely, for the point of this guide) push to master, you will be greeted with the following message:

remote: error: GH006: Protected branch update failed for refs/heads/master.
remote: error: at least 1 approving review is required by reviewers with write access.
To https://github.com/Robocubs/2018RobotCode
 ! [remote rejected] master -> master (protected branch hook declined)
error: failed to push some refs to 'https://github.com/Robocubs/2018RobotCode'

What about new features?

When developing entirely new features, a new branch should be created with the prefix feature/.

For example, when we want to start a new a feature for adding LED support with the LightDrive, we would do the following:

git checkout develop # Checkout from `develop`.
git checkout -b feature/lightdrive # Create a new feature branch.

When a feature is ready to be merged into the develop branch, we go to GitHub, create a pull request, and complete code review.

And releases... what about that?

Once develop has acquired enough commits to warrant a release (or a competition is approaching and you want to mark a stable version), you make a pull request to the master branch.

When this is warranted,

@nhubbard

will make a pull request, which will subsequently be reviewed, approved, merged and tagged with a new release.

What about hotfixes?

Good question! Hotfixes are used to quickly fix something without going through the whole feature -> develop -> master process. They are only to be used when a fix is critically necessary.

To do this, follow the same process as making a new feature, except slightly modified. Please, for the love of God, don't name a branch hotfix/prevent-fires as the example below shows. Both Mr. Guenther and I will have miniature heart attacks.

git checkout master # Check out from `master`.
git checkout -b hotfix/prevent-fires # Create a branch from there for your hotfix.

After a hotfix is completed, the person responsible should do the following set of commands:

git checkout develop # Go to `develop` branch.
git merge hotfix/prevent-fires # Merge the hotfix into the `develop` branch.
git branch -D hotfix_branch # Delete the hotfix branch.

Code Review

Above, I mentioned a process called code review. How do we do it?

Well, using the Git Flow process, this is easy. When we want to merge a commit to the develop branch, we go to GitHub, create a pull request, and use the comment tools provided to address grievances. I don't want to go into too much detail, because the tools are continually improving. In the Table of Contents above, I have included three links to GitHub's help pages which show how to make code reviews in pull requests.

Protected master Branch

You may remember the error message shown above as a preface to the Git Flow category. I have implemented the following controls on the master branch:

  • Required pull request reviews before merging. You must use a pull request to contribute to the master branch.
  • Required branches to be up to date before merging. You must use a fresh copy of the master branch as your base before commiting.
  • Required pushes to master to be from Mr. Guenther or Nicholas. We are the only people authorized to push pull requests to master.
  • All administrators are covered as well. You are not exempt from this policy if you are an administrator.

Any disallowed actions will be refused, and you will be told what went wrong.

Thank you for reading. This is officially codified as repository policy as of Unix epoch 1520294399 (03/05/2018 11:59:59PM EST).

Clone this wiki locally