Git Workflow

Adding Changes

Staging

Having added or changed things in the Unity Project we will now discuss how to Push these changes to the branch. This is similar to saving, but should only be done if the project will build, or if you are finishing for the night.

Open up SourceTree and go to File Status, this will show all the files that have changed. Check what has changed, you can click on code to see specific lines that have changed, art assets are not so easy. If something has changed that you didn’t plan to change, or you have decided no longer needs to change, right click and click discard. If you have added files that are no longer needed, please delete these by clicking remove instead (i.e. different versions of art assets).

Important Files

Every file and folder in Unity has a .meta file, these are required for Unity to work. Do Not remove/discard these.

Finally click stage all this tells SourceTree that you wish to commit these files to Source Control. Staging files separately allows finer control of what gets committed, allowing certain changes to be added at a later date, or changes to be ignored. However, most of the time this is not needed unless you wish to only commit part of your changes as you have not finished, this can get tricky so generally just stage all.

Commit Message

All Commits need a description telling everyone else what has changed. For this project the first line should be the title, a short brief description of what has changed; "clamped input values", "fix ui animation", "fixed scene scaling", etc. the next few lines should add any extra detail needed for anyone else reading to have a rough idea of what has changed at a glance. If you know the project doesn’t build, or there is a new bug you have added, add this in the description. If you are just committing before you change computer or finish for the night, please add [WIP] to the front of the title just to show it is a work in progress.

Click commit to add this commit, this is now saved locally on your computer. For this to be saved in the cloud you need to Push this to gitlab.com simply do this by clicking Push after you have committed.

Updating from develop

Note

This can be tricky. Ask for help or jump to Completing a Feature. This section is mainly for programmers.

So far you have been working on your own branch. Now you want to add your changes to the develop branch. Before you can do this you must get all changes that have happened in develop and add them to your branch. This can also be handy if you just want to add changes that have happened in develop, bug fixes, extra features etc.

First Commit and Push all the changes on your current branch like before. Then change branch to develop, just double click on it. Press fetch to see how far behind you are. Press pull to get all of these changes, this will update your local copy of the develop branch.

Move back to your feature branch by double clicking on it, click the merge button. This opens a new window of what branch you want to merge into your current branch, select the line highlighted with the origin/develop tag.

If everything goes smoothly file status will show no changes and push will have a number beside it. In this case double check, it still builds and runs in Unity the way you expect. If everything is fine you can just push the changes.

Sadly, the more likely outcome is that a Merge Conflict resolution is required which can be very tricky. If you click show full output, you will get an error message similar to the image below.

Exit your way back to the File Status window it will be similar to the one below.

Most of the time it is a simple task of picking which file should be kept. Go through the files seeing what has changed, you can open 'Before' and 'After' files allowing you to see the differences if you are unsure. Right click on all Unstaged files or files with warning symbols beside them and decide whether to keep 'mine' or 'theirs'. 'mine' is the file in your current branch. 'theirs' is the file in the branch you are trying to merge into yours.

When it comes to code you have a lot more control over changes within the file. However, this requires you to go into the code and select which lines you wish to keep. You can still choose to just keep theirs if you haven’t edited it yourself.

<<<<<<< HEAD
... changes on the current branch
=======
... changes on the incoming branch
>>>>>>> develop (or the name of whatever your incoming branch is)

Once all of these conflicts have been checked and resolved, make sure Unity still runs in the way you suspect, and try to resolve any problems that arise. Now that everything is running again Commit and then Push.

If you wish to abandon a branch merge this can be done by resetting the branch. Go to log/history right click your branch tag and click reset current branch. There is separate modes available hard is usually best for resetting after a failed merge.

Completing a Feature

You have finished a feature and want to add it to the rest of the game. Hopefully you have updated from develop, don't worry if you haven’t a programmer can do that if needs be. All that is left is merging this into develop. The act of merging is as it sounds; taking 2 branches and combining them into one.

Develop however is a protected branch this means it can't be directly merged into, deleted or pushed to. SourceTree will throw an error if you try.

Therefore, when you wish to complete a feature you must do a merge request that has to be approved by the programming team, reducing greatly the chance of merges breaking the game, hopefully. Go to GitLab.com -> Team19 -> Project tab -> Branches tab within the project, and then click on merge request beside the feature branch you wish to finish, this will completely merge the branch into develop.

This brings up the merge request page that will combine your changes with develop.

Note

Merge request titles should be: merge feature/name_of_your_feature into develop

Please add [WIP] if you didn't update from develop, just to help the reviewer.

Give it a brief description of what you have changed or added. Assign it to one of the coders. Check the source branch is the branch you are merging in and target is set to develop. Then press submit merge request.

That's it done now you can start a new feature from develop, or conquer the world, whilst the person assigned will check everything. They may have questions for you please respond to these on slack or in the merge request. If you have done anything that you are unsure of just contact one of us, or leave a comment on the merge request.

Workflow Overview

This is an example layout of the project each separate feature branch will be merged together with other people’s work in the develop branch. As a general rule we will focus on the feature branches of the Git Flow. However, the programmers will be working in the background keeping everything working doing hotfixes and handling the merges into develop and releases into master.

Master

Most stable branch no one can; merge into it, push to it or, delete this branch ensuring no accidental mistakes. This is also the branch used for Unity Cloud Build giving access to a stable install file; .apk, .exe, mac osx file.

Hotfixes

Done by the programmers to fix minor problems that made it into the master branch though these should be kept to a minimum if the Git Flow is followed.

Releases

Each time a milestone is reached, or when we have a suitable number of new features to release, a release branch will be created. This is to ensure everything meets coding standards and runs stable on decided devices helping us catch any last minute bugs. This will be handled by the assigned programmers. No new features will be merged into the release whilst this is undergone it will be completed by the assigned deadline.

Develop

This branch is where all features will be added, this branch is likely to break at times. It will be available on Unity Cloud build as well, but it will be prone to crashing and unexpected results. Please don’t use these builds for showing the game off.

Features

This is where game art and mechanics will be added, you'll spend most of your team in these types of branches. You create your branch, do your changes, then tell a programmer to merge it into develop.