Guidance on Using Git Version Control with EFDC+

The aim of this guide is to give a clear description of how we should be utilizing git for version control and how best to sync up development between EEMS and EE for releases.

Receiving Notifications from Bitbucket

Bitbucket provides a convenient way to get updates on a repo. I suggest you subscribe to the repo so you will get email updates when changes are made. To do this go to:

https://bitbucket.org/dsintl/efdc/src/master/

and select click the button highlighted in the top right and select “Manage notifications”

Open

Select at least the following:

Open

This will keep you up to date on what others are doing to the repository.

Versioning and Synchronization with EE Development

First, we should clarify how we want to do versioning. We have largely been doing this but would like to clarify and make sure it is written down. Assuming a structure like:

X.Y.Z

Where X is a major release, e.g. Version 10 of EFDC+/EE

Y major feature introduction, one which requires coordination between EE and EFDC+. For instance, changing an input file or changing the output.

Z minor changes and features that will not require any changes to EE. This could be speed ups in run time, addition of a subroutine to clean up some code, fixing a specific bug.

We will begin each Y,Z starting at 0. For example, if we just made a big change from 10.1.5 and need to sync up with EE we should not be at 10.2.0

The big take away here is that every time we make a big change and we need to sync up with EE we should increment the Y value and correspond with the EE developers. At that point EE should make the necessary changes and increment their Y value. Note, the X values do not have and should not correspond exactly between EE and EFDC+. I think this will allow for flexibility in development style while still managing to keep the synchronization better.

Using Git

I think for now, considering the size of the team, we should aim for a straightforward approach to keeping track of feature development for EFDC+ and syncing up with EE.

This article provides some practical tips for using git with smaller teams https://blog.hartleybrody.com/git-small-teams/

I propose the branches should have the following structure:

master - contains code that is ready to be released in conjunction with EE. To differentiate between versions we will use the “git tags” feature. Changes to this branch will be updated with “pull requests” so that someone has a chance to review some of the changes before it goes into production.

develop - this will contain the most up to date features and changes to the code but might not be ready for a release into the master

feature branches - basically all other branches will be feature branches of some sort.

bug fixes - if you want to fix a specific bug I think it would be great to make a bug fix that aligns with a Jira bug report. I think this is a goal for us to get to.

Here is a visual representation of the workflow.

Workflow Overview Using the Command Line

**In progress**

Guided Workflow Using Visual Studio

This section will provide a step by step instruction set for using git with Visual Studio’s built in extension. I would recommend installing the Bitbucket specific extension. This will enable you to do pull requests from Visual Studio. https://marketplace.visualstudio.com/items?itemName=MistyK.VisualStudioBitbucketExtension

Open the Team Explorer window in Visual Studio

If you are not on the development branch go ahead and find it under remotes/origin. Double click to switch to this branch. Note, if at this point you have unstaged changes to your current branch git will complain and ask you to commit whatever changes you have.

Now, create a feature branch signifying the feature you want to add to the code. Click the “New Branch” button and type in a branch name in the field

This will create a new branch called “test_feature_branch” with all of the code and history from the “develop” branch. Make sure the box next to Checkout branch is checked. This will automatically create the branch and switch to it.

After clicking Create Branch you should see a screen like:

Now you should begin working on your branch. Making frequent commits to the code with meaningful descriptions. When you want to make a record of the changes you have made click on the Team Explorer tab and click Changes

You will see a list of the files that have been changed. Select the files you want to update and click the + symbol in the top right.

You will now see the file is under the “Staged Changes” area. You could have files that are modified but might not be ready to be added to this commit message.

Now enter a description of what you changed. For a good discussion of making helpful git commits I borrowed the following from https://blog.hartleybrody.com/git-small-teams/

You should be committing code whenever you have made a single logical change. This allows you to write concise but descriptive commit messages, which offers great context for others who might be reading through your code.

Committing small things, frequently make it much easier to handle bugs or other bad situations:

When did we push this bug? Oh I see the commit… but a bunch of other things changed too. What was being worked on here?

I need to roll back that commit but what else might break if I do that?

Here are some code smells or signs that usually mean you’re not committing frequently enough:

• A 100+ line file is being committed for the first time

• You’re changing more than 20 lines of a file in one commit

• You’re only committing when you take breaks (i.e. lunch, end of day, etc)

• You have trouble succinctly describing what has changed (see below section)

Every commit message should describe why the code was changed – or what a change accomplished – at an appropriate level of detail.

You shouldn’t just use words to describe what parts of the code have changed – anyone can see that from reading the diff.

If someone wonders why a line of code was created or edited, the commit message should make it clear.

Here are some code smells or signs that you’ve writing a bad commit message:

• The message is less than 3 words

• The message is more than 10 words

• Your message is too high-level (it’s hard to be too low level)

• You don’t know what changes are being committed (see above section)

Pro tip: (for command line users)
Did you just make a commit with a bad message like “refactor” or “business logic”?

It happens to the best of us. Just use:

which gives you a vim editor to change the last commit’s message.

Now you should see:

At this point you can keep going and make additional changes to the code. However, if you are done with the feature you should merge this change back into the development branch. Right click on the development branch and select Merge From…

At the next screen select the branch you want to pull from, in this case select the feature branch you just made. and click merge.

At this point you have merged your local copy of the development branch with the local copy of the feature branch. To make sure other can see it and so there is a backup on a remote server you have to push these changes up.

To do this go back to the Team Explorer and click sync

From there you will see the changes that were made to that repo. You should select Push

If you no longer need that feature branch you can delete it. If you pushed it to a remote branch you will need to delete it from there as well.

Deleting local

Deleting remote

Now lets say we want to update the version. We can keep track of that with git tags

To make a tag simply click “New Tag” and create a relevant version number. When you create a tag, it will point to the most recent commit for the branch you are on.

Then click right click the tag you made and click “Push”

Pull Requests for Syncing with the Master

Not sure how this is done through the Visual Studio tool, will have to look at that. Worst case I can do it when the time comes. Pushing code to the master should only happen when we need to coordinate with EEMS so it should not be super frequent.