Git-organized and a CE status update.

It was Just two months ago that Torque 3D was released under the MIT license. Since that time I've been accepted as part of the Torque 3D Open Source Steering Committee, and have been encouraged to blog about some of the things I am working on as part of the Steering Committee -- this is not that blog. This is more of an account at my first fumblings with Github, and what impact the new open source direction has upon my choice of Torque.

GitHub

Github was a new experience for me and in a lot of ways I still prefer a subversion type repository. However...

Quote: from Daniel Buckmaster:
I think my real 'hump' moment with Git was when I finally got that push/pull are not like SVN's commit/update... they're actually synchronising history between separate repositories. Erk.

I spent some time spent learning the ins and outs of the git process and have come to feel that it does a really good job at making it easy to share changes among a large user community working with a complex codebase. After a fair bit of experimentation -- and mucking things up -- I found that the key to making Github code drops and pull requests clean for everyone is good organization and planning of your repository branches.

After trying out several different Git clients I chose to use the command line for everything dealing with Github. The GitHub For Windows application that seems to be the favored git app is an atrocious piece of crap that is far too dumbed down in my opinion. I suggest learning the command line commands and exercising your typing fingers! Although if you want to cheat and use a GUI based client, the Git-GUI of Git for Windows (from mysysgit) isn't a bad alternative. Something else that did not incur an abundance of disfavor with me was Git Extensions which integrates with Visual Studio. TortoiseGit caused issues with my existing TortoiseSVN client, so be wary of it.

I manage my own fork such that the master and development branches only contain updates from the remote GarageGames repo, keeping them in a mirrored status. So whenever code gets pushed to the GarageGames repo, I look to the remote upstream to fetch and merge into my fork's master and development branches.

# Get all the commits applied to the GarageGames repo, but do nothing with them
git fetch upstream

# Get on the master branch
git checkout master

# Merge in changes from upstream
git merge upstream/master

# Do the same for development branch
git checkout development
git merge upstream/development

There are other methods of handling this (pull for example), and even some additional options (--ff-only), but I think this is about the simplest way of demonstrating how to update your fork from the GarageGames Github repository

I've seen that some people have wondered why their submitted pull request also contained cumalative changes outside of the request's purpose. "So how do I share changes that I make without forcing a merge of the other changes in my codebase&amp", you ask? The answer lies in how branches can be a useful organizational tool when using Git.

For example, the branch where I do all of my work is myworkingbranch which for this description is based upon the development branch. I then update this branch with merges from my repository's development branch, the origin -- which has already been updated from the GarageGames development branch, the remote.

Once someone makes commit X into the GarageGames development branch, I pull commit X into my local development branch, which is then merged into myworkingbranch creating commit Y. commit Y now contains the contents of all commits since I last merged development into myworkingbranch.

When I want to make some changes myself, I always always branch from the current dev head. I make lots of little changes against development as individual topic branches, and merge them all into myworkingbranch. The process looks something like this:

# Currently on branch myworkingbranch

# Checkout development
git checkout development

# Create topic branch
git checkout -b new-feature

# make changes to files

# Push changes to Github
git push origin new-feature

# Go back to myworkingbranch
git checkout myworkingbranch

# Merge in changes
git merge new-feature

# Push to Github
git push

This results in a commit history that looks something like this, assuming that myworkingbranch was up-to-date with development when I branched:

Where B, C, and D are my commits in the new-feature branch, and E is just the merge commit. This might seem cumbersome, but what it means, aside from having lots of neat little topic branches, is that I can pull-request from new-feature to the GarageGames development branch very cleanly.

I hope that wasn't too confusing! I also hope I'm not getting the Git process completely wrong, but the above works for me, and is a summary of a discussion that occurred between Daniel Buckmaster and myself.

Recap:

• Keep your master and development branches free of your own commits and up-to-date with GarageGames.
• To implement a change, create a topic branch from development.
• Maintain a branch for you (for example, ceport) and merge all your topic branches into it, as well as changes to development from upstream. Don't commit directly to this branch! (Unless you aren't going to pull-request stuff.)

Community Edition

Once the Torque 3D Github repository was opened to the public I proceeded to port the Community Edition -- the SVN repository remains locked to T3D 1.2 licensees -- in order to make it compatible with the MIT license. The Community Edition has always been for the Community. Alfio and I both stand by that. The community members who are in the group have all had a chance in participation and helping to decide on it's course of action. The CE to MIT version port, once it's done, will allow the full community access to the fixes and improvements that the CE group has had a hand in, on GitGub. This will also make it much easier to get things shared with the greater community and ready for the eventual inclusion of some aspects of the CE into the Torque 3D development branch.

Unfortunately I have to admit to some fair amount of laziness in the past month, and the porting of the CE is hanging in limbo at the 37% complete mark. You all have my assurance that as time permits the port of the CE to Mit on Github will be completed. If you wish to delve into what has already been ported you can find it here T3D CE on Github. Anyone from the existing CE community who wants to help in the remainder of the port can send me message and I'll make you part of the CE Group which will give you write access to the repository. Alternatively, anyone can submit a pull request.

Since my admittance to the Steering Committee I have decided that I can longer be the voice of the CE. I would like, and hope to see, the CE initiative continue as it still retains a lot of potential. I know that Alfio has strong feelings about it's continuance and he has other ideas and services he would like to implement and offer. I should also point out that I have no hand, or say, in the rumored Mac port and OpenGL work that was promised to the CE group. Due to a lack of communication I can make no statement about the progress or estimate a time for completion.

Kaboom

Also, in the spirit of the new open source direction of Torque 3D, I also decided to lower the price for the Kaboom! Destroyable Objects content pack to $10. It's last update was just a few months ago in which I provided the pack in a format more easily dropped into Torque 3D without you having to port the older TGE/TGEA packages.