Git workflows

Create a new branch for your work

• sync up your branch with upstream
  • git fetch upstream
• create branch from upstream
  • git checkout -b {feature} upstream/{branch}
• set up tracking of <feature> on origin repo

  • git push origin {feature}

  • git branch --set-upstream {feature} origin/{feature}

• From now you can push changes to {feature} with just git push

Daily development

• Sync up to the upstream branch frequently
  • Staying in sync with upstream now prevents painful merges later
  • sync up your branch with upstream
    • git fetch upstream
  • Merge in changes from upstream
    • git merge upstream/{branch}
• Make changes and commit frequently
  • git commit -a -m'added x to feature'
• Repeat

Getting your work into upstream

• Make sure your branch is synced to upstream/{branch}
• Make sure your formatting, comments and naming follows the standards
• Go to github and issue a pull request for your change
• Revise your code if requested
• Optional: At this point you can delete your {feature} branch if you want. It won't be needed anymore
  • Delete locally
    • git branch -d {feature}
  • Delete in github
    • git push origin :{feature}

Is your history too verbose for pushing upstream?

If you usually create a lot WIP commits, you might want to review the commit history that your pull request will send upstream

• Examine history of {feature} branch
  • git log upstream/{branch}..{feature}
• If the history is too verbose, you can squash all commits into a single commit
  • Create a new branch off upstream that will be your pull request target
    • git fetch upstream
    • git checkout -b {feature}_pull upstream/{branch}
  • Merge {feature} and squash all commits
    • git merge --squash {feature}
  • Now all changes are staged on {feature}_pull to be committed as a single commit
    • git commit -a -m'{commit message for upstream history about feature}'
  • Push branch to github so you can issue a pull request against it
    • git push origin {feature}_pull
  • Issue a pull request like usual

Refreshing {branch} to match upstream

WARNING: This should only be done if you have committed changes to your copy of {branch} that will not make it into upstream/{branch} and you want your copy of {branch} to mirror upstream once again. This will wipe out all changes in your copy of {branch} that do not exist in the upstream!!!

Your {branch} should always stay as close to the upstream version as possible, and only drift for changes you are planning on pushing soon. For this reason, you should merge often refresh if your changes didn't make it into upstream verbatim.

• sync up your branch with upstream
  • git fetch upstream
• get a temp copy of the upstream branch
  • git checkout -b temp upstream/{branch}
• merge our version of the branch into the upstream with ours strategy
  • git merge --strategy=ours master
• commit if necessary (i.e. auto-commit or fast forward didn't happen)
  • git commit ...
• checkout our version of the branch
  • git checkout {branch}
• merge temp (which will be a fast forward)
  • git merge temp
• push the changes to our origin repo
  • git push
• get rid of the temp branch
  • git branch -D temp

Diffing two branches

Checkout a branch you want diff against (see instructions above for that)

• To diff two local branches do (where master and 2.2 are branch names)
  • git diff master..2.2

Recovering from a bad merge

Sometimes a merge may pull in changes you didn't expect and since merge automatically commits you may find yourself with a whole bunch of unwanted commits.

• Discard all commits and reset to
  • git reset --hard HEAD

Setup

• Add MSBuild.exe to path
• Export MindTouchKey to point to mindtouch.snk location for official builds

Create new production branch

• Branch master into whatever Major.Minor is in master:mindtouch.build.xml 
  • git checkout -b 2.3
• Run build tool to update versioning information
  • MSBuild.exe -t:UpdateVersion
  • This will increment the Revision to 1, i.e. 2.3.1.0
  • Production branches always start at point release 1, so that they are always higher than the master version
  • Mindtouch.build.xml, all AssemblyInfo.cs and App.Config files will be updated
    • GitRevision will be set to HEAD. We never check in the revision of the actual build binaries since the act of checking in would just create a new revision again, thus not serving any purpose anyhow
• Check in updated versioning information
  • git commit -a -m'created new production branch'
  • git push
• Check out master
  • git checkout master
• Update master version to 2.4.0
  • MSBuild.exe -t:UpdateVersion -p:Version=2.4.0.0
• Commit new revision number
  • git commit -a -m'updating version'
  • git push

Build new binaries

When we build new binaries, it is either for a release of a release candidate. More often it is the latter. I.e. let's say we need to get new DReAM changes for the stable branch of MindTouch, we will build binaries that become the release candidate for the next version of DReAM.

• Run build script
  • MSBuild.exe
  • This will update all AssemblyInfo.cs and App.Config files, put the build files in dist/ and revert the changes thereafter, since we never commit the build information

For a release candidate, we just copy the contents of dist/ to its destination and we are done.

For the actual release (either because it's a part of a release of MindTouch or we have an out-of-band release of DReAM), we have some extra steps

• zip up the dist/ directory as mindtouch.dream.2.3.1.zip
• upload the zip to Github
• tag the version and push the tag to github
  • git tag -m'Official 2.3.1 release' 2.3.1
  • git push --tags
• update version, since the first RC for the next release needs to be a new release version
  • MSBuild.exe -t:UpdateVersion
  • This will increment the release to 2, i.e. 2.3.2.0
• Commit new version information
  • git commit -a -m'incremented release'
  • git push