Skip to content

Version Control

Jump to bottom Edit New page
Joshua edited this page Jun 22, 2015 · 2 revisions

Contents

Workflow Overview

The workflow is based on Gitflow, although not all elements may be necessary for this project.

Diagram of Gitflow branch structure

The Git repository is composed of:

Master branch
  • Reserved for stable releases (alpha, beta, etc.) with all relevant features completed
  • Commits should never be made directly to master - new versions are created by merging from develop
Develop branch
  • Reflects stable versions with all new features included as they are completed.
  • Commits should never be made directly to develop - changes should be merged from feature branches.
Feature branches
  • For working on a new feature/bugfix in isolation from the develop branch
  • New feature branches should be based on develop, not master
  • Naming convention is feature/some-cool-new-feature
Playground branches
  • For testing out new ideas
  • Naming convention is playground/testing-out-a-great-idea
  • They can be pushed to GitHub for the purposes of collaboration, so playground is a signal to other team members that the code on the branch may be incomplete/buggy/untested etc.
Fix branches.
  • When someone notices a bug in live production code, a fix branch is created for taking immediate action
  • Naming convention is fix/bug-or-issue
Currently unused elements from Gitflow
  • Release branches. Once all features for a release have been completed, release branches are created for release-related tasks (e.g. documentation), thus freeing up the develop branch for other team members to work on features for the next release. It is unlikely that this will be required in this project, so currently it is not being used.

Issues & Milestones

Read GitHub's Mastering Issues guide to understand how they work.

Milestones should be created for each release we intend to create (e.g. alpha, beta, etc.).

Issues should be created for each task to be carried out (e.g. features, bugfixes). They should also be:

  • Assigned to a relevant milestone
  • Labelled appropriately. Use two-dimensional labelling, i.e. two labels:
    • Severity - blocking, critical, high priority, low priority
    • Component - which aspect of the project the issue relates to, such as debugger, navigation

Commit Messages

Commit messages should take the following format:

Short summary of changes #issue-number

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Further paragraphs come after blank lines.

 - Bullet points are okay, too

 - Typically a hyphen or asterisk is used for the bullet, preceded by a
   single space, with blank lines in between, but conventions vary here

Notes:

  • #issue-number is the GitHub issue number that this commit addresses
  • The summary should be written using past tense (i.e. "Added talking behaviour to helper robots" instead of "Add talking behaviour ..."). Justification
  • If applicable, answer the following questions in the more detailed explanatory text:
    • Why is this change necessary?
    • How does it address the issue?
    • What side effects does this change have?
  • Where possible, use fixes #49 in commit messages to automatically close GitHub issues. See Closing issues via commit messages for syntax
  • Pair programming - if you have collaborated with someone on a single machine, add both members' usernames at the end of the commit message:
[message] <@username1 | @username2>

Pull Requests

Read GitHub's guide on Pull Requests to understand how they work.

Pull requests should be used in two cases:

  • You are working on a feature branch and would like some feedback
  • You have finished work on your feature branch and it is ready to be reviewed for merging into develop

Ensure that pull requests compare the develop branch (not master) with your feature branch.

Keeping up to date

When working on a feature branch, it is important to regularly pull everyone else's work from develop. Assuming you are working on feature/your-feature-branch, use the following steps taken from this StackOverflow answer.

First check if there are even any changes on develop to pull from GitHub.

git fetch origin

If there are changes, switch to develop and fast forward to the latest.

git checkout develop
git merge --ff origin/develop

--ff means fast-forward merge. In theory you shouldn't have made any commits to develop since you last left it, so you should be able to just fast forward it to the latest commit you've pulled down. If this fails, you might have accidentally committed to develop at some stage. If not, it means someone rebased the remote develop branch (which is bad...)

Now go back to your feature branch.

git checkout feature/your-feature-branch

The following steps depend on whether your changes are local or have been pushed to GitHub.

[Option 1] If you haven't yet pushed your changes to GitHub

You can simply rebase from develop, replaying your changes on top of the changes you just pulled from GitHub

git rebase develop

[Option 2] If you have already pushed your changes to GitHub

Do not rebase, this rewrites the history of the branch, and will cause problems when you try and push back to GitHub. Instead, merge the updates back into your feature branch.

git merge develop
git push origin feature/your-feature-branch

Collaborating on a feature

Feature branches will need to be pushed to GitHub for:

  • Collaboration on a feature
  • Code review before merging back into develop
Push your local feature branch to GitHub for the first time

If you have created a local feature branch called feature/cool-feature, push using:

git push -u origin feature/cool-feature

The -u argument is not essential, it just tells Git to set up a tracking reference for the remote branch. It means you can do something like git fetch origin; git status; and it will let you know if you are behind the remote branch. Subsequent pushes do not require the -u argument.

Clone someone else's remote feature branch
git fetch
git checkout -b feature/cool-feature origin/feature/cool-feature

This creates a new local branch called feature/cool-feature that is based on the remote branch called origin/feature/cool-feature that you just fetched.

Push updated code on a feature branch

If you want to push further commits back to GitHub, use the same push command as before, but without -u:

git push origin feature/cool-feature
Pull updates on a feature branch

While on feature/cool-feature:

git pull --rebase origin feature/cool-feature

Example Flow

Get started

Perform the following to clone the repository's develop branch:

git clone https://github.com/jennafin/SE306-Android.git

Start work on a new feature

To work on a new feature you need to create a new feature branch for your changes.

git checkout -b feature/your-feature-branch develop

You can omit develop if you are already on the develop branch

Do some work

While on your feature branch, make your changes and commit them as usual.

Finished with your feature

  • Ensure you are up to date with the latest version from develop (see Keeping up to date)
  • Write unit tests for any code you have added
  • Push your feature branch to GitHub (see Collaborating on a feature)
  • Create a pull request that compares develop with your branch's changes

Code Review completed

Once a team member has reviewed your code and everything is okay, one of you should either:

  • Use GitHub to automatically merge the pull request's changes into develop or
  • Manually perform the merge (assuming you have already pulled the most recent changes):
git checkout develop
git merge --no-ff feature/your-feature-branch
git push origin develop

Why use --no-ff?

If necessary, close any relevant issues using fixes #49 in the Pull Request description. See Closing issues via commit messages for syntax.

This page was made for a previous assignment and had collaboration from other students outside of the project

Add a custom footer

Clone this wiki locally