Git Information

PDF of an email from John Liss with Git Instructions. This should give the general steps to get things setup. IT is a little dated, but most concepts still apply even if the screens have changed some.

Git instructions.. step by step

Tools

Git libraries.

Git SCM

TortoiseGit is the primary repository integration tool many of us use. This allows you to make commits, view history, etc. without having to use the command line tools in Git itself.

TortoiseGit

TortoiseGit Manuals

Visual studio also has support within it for Git and there are also many other plugins that provide integrations as well. You are welcome to use whatever you like and are comfortable with.

Branching practices

The general idea is that the master branch is, tracking the development for the next version. It’s stuff that’s going into the product, and will be included in the next version unless something is found to have an issue in testing.

(a) You should not commit stuff to your master branch. You should keep it up to date with the real master and make branches off of it for any new work your do. When you first decide to do work on Vixen, you would fork the master at Vixen Source to your own copy of it. You should be able to build and get a running version of Vixen from that is current. Then you can easily make branches from that to work on. Tools like TortoiseGit make it easier to manage changing branches and committing work.

As a maintainer, even I do not commit any work directly to the master branch. All commits on the master branch are actually merges of work from other branches.

(b) All work should be done based off of a ticket in the JIRA Bug Tracker. When you take on work for a particular item, you should create a branch off of the current master and name it the same as the ticket you are working on. I.E. VIX-1024. This provides a clear reference back to the description of the problem or feature. In addition to this, each commit should start with the ticket number as well. This will allow those commits to be linked to the ticket as well when they are eventually merged into the master.

(c) If the item you are working on will span some time and the current master gets updated with new features from other developers, you can keep your branch in sync by rebasing your changes onto the current version of the master. You would sync your copy of the master from the master branch tree first. Then you can rebase your branch onto that. This will replay your commits onto the tail of the master giving you a up to date branch. Try to avoid merging the changes in the master into your own branch as this creates a messy commit history. More information on how to rebase can be found here.

(d) If you are collaborating with another developer, then you may want to share work on a branch. Here you can both work on the same branch shared publicly or you can merge changes between yourself. This is not very common in our development structure so ask questions if it comes up and we can help guide you through it.

(e) If you want to have a play with someone else’s branch (to test, or add features to it), as long as they have pushed ac copy of it out to their public repository, then you can always make your own branch at that point, and go from there. For example, Jeff might take a look at Jon’s “VersionControl” branch, and make a new one for himself, called “Jeffs_VC_additions” or something. He can do some more work to do with the version control, maybe updating stuff, adding a new feature, etc. Then, if Jon likes it, he can merge from Jeff’s VC branch back into his own VC branch. (since it’s all separate to ‘master’, he can do what he likes with it.) Once all the work is done between the two developers, the version with all the changes compiled together can be merged into the master.

(f) When work is complete on a branch, That branch should be pushed to your public repository. Then the ticket tracking it should be moved into the ready for merge status. This is my cue to go review it and either provide feedback or merge the changes. You should provide the information on the location of your GitHub repository so I can connect to it and pull the branch. If you made the branch name the same as the ticket it is easy for me to find it once I establish the path of your repository.