GitHub Repository Structure

Each repository (repo) in the CIRN GitHub organization should follow a similar structure. There are a few kinds of branches that will be used in these repos:

• Master – This is the highest level branch in each repo. This branch contains the version of the code that is always “production ready”, especially if it is public-facing. All other branches will stem from this one.
• Development – The development branch will branch off the master branch. This branch is used to develop new software releases of the code that will implement new features, functionality, and bugfixes. Once these features, functionality, and bugfixes are finished, and the code is properly tested, a pull request can be submitted to merge development with master to introduce a new “release”.
• Hotfix – A Hotfix will also branch off master but should not be used unless absolutely necessary. Hotfixes are designed to get rid of critical bugs in production that need to be fixed immediately. Before creating a branch of this type consider, is there a workaround for this bug? If so, there shouldn’t be a need to pull this bug fix right away and the developer should wait for the next release in the development branch. If not, it would be wise to list the hotfix as a minor version change and make the developers aware that there’s no need to fetch the updated master branch for their local repository unless they are working on code that was affected. These branches should be labelled appropriately e.g., the branch will have the title “hotfix-xxxxx” where “xxxxx” describes the date of the hotfix’s issued pull request. The bug fix remedied by the hotfix should be descriptive.
• Feature – A Feature will branch off development. Their purpose is to develop new code that will eventually be added to the next software release that will introduce new features or functionality. The branch name should be descriptive. Once the feature has been fully developed and properly tested, a developer can initiate a pull request to merge the feature with development. When developing new features, the developers will be likely be writing code in a repository on their local machine. It is very important that developers take the following actions when doing this: ** Before working on code shared by multiple developers, each developer should fetch any updates from the remote GitHub repository to their local machine so that they can have up-to-date versions of the code. If necessary, developers should stash their code or create a backup to avoid conflicts when fetching code from the remote repo. ** After they’re done working on code for the day, the developer should push their changes from their local repository to the remote repository. This way, other developers can keep up with changes and not duplicate work that may have already been done.
• Bugfix – Similar to a feature, a bug fix will branch off development. The purpose of this branch, as the title implies, is to fix a bug in the code. Once the bug is fixed and the code is verified, the developer can initiate a pull request to merge the bugfix into development for the next version release. The branch should be descriptively named if possible.
• Subfeature – A subfeature (or feature-of-a-feature) branches off an existing feature branch. Sometimes a feature may be big enough that developers might be delegated to breakdown the feature into smaller parts which requires their own branches. Once a subfeature is properly tested, the developer can initiate a pull request to merge it into its parent feature branch.

Following this hierarchy of branches is important for keeping an organized repo and will make merges into branches easy-to-read. Below is a diagram of what an example repository structure might look like—keep in mind this only has one feature branch but other features could be added that also branch off development.

In addition to following this workflow, proper branch clean-up will also help keep a repo organized. When a branch is no longer needed, the branch can be close. This is usually safe to do when a feature/fix has been properly tested and merged into the master branch in a release rollout.