OpenStudio Application's GitHub Workflow for Internal Developers

Wiki ▸ OpenStudio Application's GitHub Workflow for Internal Developers

Contents

• Branching from develop
• Cloning the Repository to Your Local Computer
• Creating A Branch
• Committing Your Changes
• Reintegrating a Branch into Develop
• Pushing All of Your Local Commits to GitHub
• Synchronizing Your Fork with NREL/OpenStudioApplication

Branching from develop

All work should be completed in feature branches created from the develop branch. Biweekly iterations will be branched from develop to iteration, and releases will be branched from iteration to master. No commits or development work should be made to iteration or master unless you are authorized to modify that iteration or release.

Modified from http://nvie.com/posts/a-successful-git-branching-model/

Cloning the Repository to Your Local Computer

If you want to download the latest stable release, select the master branch. Otherwise, if you want to work with the latest development code, use the develop branch:

git clone -b develop git@github.com:NREL/OpenStudioApplication.git .

The final dot is required if you want to clone into your current directory. Without the dot, this command will create a directory called OpenStudioApplication and clone into that. This clone operation will download ~87MB of files and reconstruct the full develop branch within that directory (which will then total ~337MB). This command also makes all branches available locally.

Creating a Branch

To create a new local branch and switch to it:

git checkout -b mynewbranch

To make this branch available to everyone, push the branch to GitHub:

git push origin mynewbranch

Alternatively, you can do both these steps by typing the new branch name into the branch filter on GitHub and click Create branch:

Committing Your Changes

To track new files, and to stage modified files for commits:

git add mynewfile
    or
git add mymodifiedfile

After creating your branch and making changes, commit all your staged changes and modified/deleted files. The first line of your commit message should be a very brief description of the commit, followed by more details:

git commit -m "#3 Bug number & brief commit summary go here (~65 chars)
> More details can go on the additional lines [delivers #12345678]"

Adding a -a flag to your commit command will automatically commit all modified files, even if you haven't explicitly used git add on them.

Reintegrating a Branch into Develop

If a code review is necessary and your changes are complete, click the Compare button in your branch and follow GitHub's instructions for submitting a pull request. After creating the pull request, you can assign it to the bug or ticket owner for review.

However, if your branch does not require a code review, then it can be merged immediately:

git checkout develop
git merge --no-ff mybranch

The no-fast-forward --no-ff flag is important for merging to maintain branch history, and it stays consistent with GitHub's automatic merge settings:

Credit: nvie

Pushing All of Your Local Commits to GitHub

When you're ready to share your changes and commits from any branch with the rest of the team:

git push origin

Synchronizing Your Fork with NREL/OpenStudioApplication

If you want to update your fork with the latest changes from OpenStudio Application's main repository, you will first have to add an upstream remote, and then merge the latest changes to your fork:

# set the upstream remote once
git remote add upstream git@github.com:NREL/OpenStudioApplication.git

# grab the upstream remote's branches
git fetch upstream

# merge NREL/OpenStudio's develop branch into your fork's develop branch
git checkout develop
git merge upstream/develop

If you have made commits to your fork but want to reset it:

git fetch upstream
git checkout develop
git reset --hard upstream/develop
git push origin develop --force