GitHub Strategy

We have options when it comes to deploying a GitHub strategy and branches. Ultimately our end goal is to be able to make the contents of our repository public and protect the main branch.

Proposed Solution

We are going to enable branch protection for the main branch that prohibits anyone from directly pushing changes to the main branch. Any changes to the main branch will require a pull request to be submitted, reviewed, and approved by our team administrators.

Enabling Branch protection

Go to the GitHub repository hosted at github.com and select Settings on the right side of the navbar at the top of the page. Once in Settings on the left side select Branches under Code and automation. By default there is no protection on any branches. Click on the box to Add branch protection rule. This will bring up a checklist for the different rules that can be applied to different branches. To start enter the branch name that should be protected in the Branch name pattern * textbox, in most cases this will be the main branch but additional branches can always be added and protected. To start select the box next to Require a pull request before merging, this will then open another box that’s automatically selected to Require approvals. This is to setup the code review to approve pull requests and the approval number is set to 1 by default, but can be set to whatever makes sense. The only other option that needs to be selected is Do not allow bypassing the above settings. Click on the create button at the bottom and the main branch of the GitHub repository is now protected from having direct pushes made to it, and will only allows approved pull requests to be merged.

Note

If you want to be able to push to the main branch of your repository, but don’t want anyone else to, leave the Do not allow bypassing the above settings box unchecked.

GitFlow Development

With branch protection now enabled, in order to make changes to the main branch, development needs to be done in different branches.

Development Branch

For now updates can be pushed and tested to the development branch in our code repository. When everything is confirmed to be working as expected a pull request can be made to merge the changes to the main branch. Please be descriptive in the changes made as part of your pull request. Once the pull request has been submitted an email will go out to the team that is ready to be reviewed. Once all the changes have been reviewed and confirmed the pull request will be approved and the changes will be merged in to the main branch.

Additional Branches

Additional branches can be created for a variety of different reasons but they should now be created off the development branch and integrated back in to that branch before being merged to the main branch. As we expand this practice we will outline what branches we typically use.

Example Workflow

To start, clone the repository

git clone https://github.com/NCAR/cisl-cloud.git

Change from the main branch to the development branch

git checkout -b dev

Make your changes in the development branch, test, and push the code

git push

With the changes pushed the branches will now be out of sync. There are a few different ways to create a pull request to merge the changes. The easiest is to utilize the UI found at the repository on GitHub. On the top navigation bar there is a tab for Pull requests. From here you can chose branches to compare, confirm the changes you want to try and merge, add in a description for the changes, and ultimately submit the pull request. Once the PR is made an email will go out to approvers to review the request. Once it get’s one review and approval the PR can be selected to Merge in to the main branch. As long as there are no conflicts the merge should proceed with no issues. If there are conflicts they should be handled via the code review, updated accordingly, agreed upon, and confirmed with another team member.