ECR Branching and Merging Guide

Git makes it easy to support multiple Remote repositories. In fact, Bitbucket is just a remote repository itself.  A remote is just a reference to a server, or file system location. When a project is cloned from Bitbucket, git automatically creates a remote called origin that points back to where the project was cloned from, in Bitbucket. New remotes can be added very easily, and then code can be pushed to remotes to keep everything in sync.  The ECR is just another remote.

GitFlow (lite)

GitFlow is a branching strategy created by Vincent Driessen.  Some of the ideas of GitFlow are very basic to how Git works naturally. Most of the GitFlow ideas are about creating parallel development environment and making sure that changes are isolated from finished work – until they are ready to be merged.  The ECR makes use of some of the basic ideas of GitFlow, and only requires the addition of a single extra branch which can live in the ECR remote, or in all your remotes.

Simple GitFlow

Do work on a branch, other than master, and only move code to master after Peer Review.  A good name for this extra branch is develop.  Do your work on develop, and then when you are ready to make a release, merge the code into master.  A good practice is to tag releases in master so that you can capture point in time details. The develop branch should be the default branch in Bitbucket.

Taking it one step further

Features or new development should  be tied to Jira Tickets, and worked on separate branches, rather than directly on develop. Not all feature branches are merged back to develop - they may not be suitable for production or they might represent experiments, or changes in direction etc.

Tie into ECR

In order to keep the original project repo clean, we create a single new branch called community, and push that to ECR.  Note: the community branch only needs to exist on the ECR – it can exist in the project repo too, but that is up to you.  For example, if the original project is delivered to a customer, then you may not want to deliver the community branch, in this case, just don't push that branch back to your original repository.

The additional community branch ensures that the project develop branch and ECR develop branch can be kept in sync.  In other words, if you allow changes to be made directly to the develop branch in ECR, then pushing new updates to ECR may not work, as the branches will be out of sync.

Keeping things in Sync

Merging is done using “git pull”.  A merge pulls changes from one branch into another.  Git also has a concept of pushing, but that is for pushing new committed changes to a branch. You can merge (sync) your code into ECR Bitbucket on your own schedule / frequency.  

When would I sync? – It depends on your use case.

• You push code to ECR and never update
• You push code to ECR and periodically update
• You push code to ECR and accept changes from the community back to your project (GitHub model)

Each of these use cases is discussed below.

Push and Forget

If this is a one-time thing, then you would simply push your code to ECR Bitbucket, create a community branch, set that as the default branch in the Bitbucket UI, and then walk away.  This approach can easily be converted to a periodically synchronized project.

Push and Sync

This model is used when you want to make periodic updates to your code, and share those updates with the community.  When you do this, you will push your branches (master, develop etc.) and then you will create a Pull Request (PR) to merge the changes from the develop branch into the community branch.  You could just pull your changes into community, but the PR allows everyone to see what changes are coming, and to even give a thumbs up/down vote on accepting the changes.

Setting up this type of project is basically the same as the Push and Forget model. You will push your code to ECR Bitbucket, create the community branch and then set it as the default branch.  The only thing remaining is to occasionally push updated code to ECR.

Push and Pull

The final use case is when you not only want to share code in ECR, but you are expecting that other developers in Leidos will want to share changes back with you.  Setup is the same as Push and Sync, however, when updates are made to the community branch, developers will create PRs that you will moderate (accept, reject), and then you will - when you want, pull those changes back to your original repo.  This is the GitHub model.

Fork or Clone

This last use case, was not listed in the group of use cases above, because its not a "sharing" model per se.  The Fork or Clone model is simply one where you are not sharing code, but rather you are reusing code shared by someone else.  In this case, you will clone the existing repository to your local disk and then make use of the code in your own project.  You can also fork the code.  Git does not really have an underlying fork command.  Forking code in Bitbucket will result in you getting a new repository created that you can manage from Bitbucket.  You can create PRs from your Forked code, back to ECR. This is also the GitHub model, but in this case, you adopt the code, maintain it, and if there is something that you want to share back, you do that using PRs.

Things to keep in mind

• The ECR repository and the Original repository are physically separate, but share the same commit history
• If the repos do not share the same commit histories, then they can use “git patch” to keep things synchronized.
• The project team has permissions to update the corresponding ECR Repo
• The ”Community” cannot update the original Project Repo – this is safe and protected.
• The Community branch is moderated either by the original project team, or by a community owner(s)
• The Community develop/master branch should always be a reflection of the original project branches
• The Community branch is allowed to diverge from the original project code by using a GitFlow model on the community branch
• The Community branch should be the default branch on the ECR
• All PRs (both project and ECR based), should go through appropriate peer review prior to merging
• Forking requires that you have a Bitbucket account, with permission to create a repository