Wingman is an interface and workflow for managing your source in ways which map directly to creating software. We talk in terms of features, bugs, release candidates, releases and hotfixes.


Under the hood, we use Git and GitHub to actually achieve this, abstracting away complexity, making sure you can just get on and ship software. Less...

REQUIREMENTS

  • Mac OS X 10.7+
  • GitHub Account
  • 47MB Disk Space
Download Trial Now

Introduction

The goal of Wingman is to make software version control as natural as writing software itself; no endless amounts of command line flags, no lengthy commands, and no cheat sheets – just bugs, features, release candidates, hotfixes and releases. Wingman lets you make the changes you need to make with zero confusion, then get back to your work, stress free.

Wingman is fully integrated with GitHub, giving you the best possible experience with keeping your projects synchronized between team members, in addition to the benefit of having all of your work backed up 24/7.

Here's a quick overview of the conventions used by Wingman:

  • The 'master' branch always reflects the current publicly released version of your project.
    You should never work directly on the 'master' branch.
  • The 'develop' branch reflects the latest state of development for completed features.
    You should never work directly on the 'develop' branch.
  • Feature branches are named using the following format:
    'feature/feature-name/GitHub-Issue-Number'
  • Bug branches are named using the following format:
    'bug/bug-name/GitHub-Issue-Number'
  • Release Candidate branches are named using the following format:
    'releasecandidate/release-candidate-name'
  • Hotfix branches are named using the following format:
    'hotfix/hotfix-name/GitHub-Issue-Number'
  • Releases are tags off the master branch, and are named using the following format:
    'release/release-name'
  • Branches or tags which don't match these conventions can coexist, but are simply ignored by Wingman.

If you ever want to see exactly what was done to your repository, you can: ~/Library/Logs/Wingman.log

Command-Return for the hotkey? Are you insane?

We know some people won't like that hotkey combo, so although there is no UI exposed for changing that, you can change it on the command line, using 'defaults'.

  • First ensure Wingman is closed.
  • Open up a terminal session.
  • To set the modifier keys, set an array of keys. Eg:
    defaults write com.polarbearfarm.wingman 'hotkeyModifiers' -array "command" "shift"
    Valid modifiers are "command" "control" "option" and "shift"
  • To set the hot key, enter a decimal integer (not hex) relating to the keys virtual keycode (not ASCII). Eg:
    defaults write com.polarbearfarm.wingman 'hotkey' -integer 44
  • Open Wingman, and your new hotkey should be active. (In this example command-shift-/)

Creating New Projects

At its highest level, Wingman is a collection of projects. Each project contains its own unique set of tasks, release candidates, and releases, and is representative of all changes, past and present, to your software.

Creating a new project in Wingman is done through the 'New Project' menu option on the account you wish to work with. Wingman lets you use your personal accounts and any organization accounts you may be a member of, right out of the box. Creating a new project will handle all of the heavy lifting for you, including creating a private repository on GitHub, setting up the Git branch structure, and creating any useful files like .gitignore.

IMPLEMENTATION

mkdir new-project-name
cd new-project-name
git init
touch readme.md
git add readme.md
git commit -m "Initial commit"
git push -u origin master
git checkout -b develop
git push -u origin develop

Loading Existing Projects

If you have existing projects which you would like to work on with Wingman, you simply select 'Load Project' from the menu of the desired project. Wingman will download your project from GitHub, store it locally, and get it ready for you to use.

Sometimes, you may have existing projects which you don't wish to work on in Wingman. For this, Wingman offers the Hide Project feature, available in the task menu of any project on your account. Revealing a project again can be done through the Preferences window.

IMPLEMENTATION

git clone Project-Name
if 'develop' branch exists
    git checkout develop
else
git branch -b develop
git push -u origin develop

Creating Tasks

To create a task, select 'Work On A New Feature' or 'Work On A New Bug' from your project's task menu. From here, you simply give Wingman a name, and optionally select an issue to link your task with. Wingman is designed to work with GitHub Issues, meaning that when you want to work on a new task, you can select a pre-existing issue or simply create a new one. Operating this way allows you to add comments and notes to a given task, and manage your project much more efficiently.

IMPLEMENTATION

Ensure current working directory is clean.
git checkout -b develop Task-Branch-Name
git push -u origin Task-Branch-Name

Completing Tasks

Once you've completed a task, all that is left to do is select 'Complete Task' from its action menu. Wingman lets you write software without having to worry about all of the housecleaning that would normally come with it. It merges with all the appropriate branches depending on the task type, to automatically keep your workflow consistent.

IMPLEMENTATION

Ensure current working directory is clean.
git merge origin/develop
Resolve conflicts & ensure working directory is clean.
git checkout develop
git pull
Resolve conflicts & ensure working directory is clean.
git merge Task-Branch-Name
Resolve conflicts & ensure working directory is clean.
git pull
git push
Resolve conflicts & ensure working directory is clean.
If task is hotfix
    for each release candidate
        git checkout RC-Branch-Name
        git pull
        git merge Task-Branch-Name
        Resolve conflicts & ensure working directory is clean.
        git push
    End
End
Close GitHub issue
git branch -D Task-Branch-Name
git push origin --delete Task-Branch-Name

Getting Latest Developments Into Tasks

As others on your team complete their tasks, your tasks will lag behind the latest developments. You want to incorporate other's completed tasks into your own tasks in progress, to make sure things remain functional. "Get Latest Developments" on the task menu allows you to merge in all changes on the develop branch into your task branch.

IMPLEMENTATION

Ensure current working directory is clean.
git merge origin/develop

Creating Release Candidates

Once your software is stable and almost ready to be sent out the door, you can create a release candidate. Release candidates are the place to update version numbers and double check that there aren't any last minute bugs left to fix.

Creating a release candidate is done from the task menu of your current project.

Feature or Bug fixes made after release candidates have been created will not be applied to Release Candidates. Only Hotfixes are applied, meaning once a release candidate has been created, the rest of your team are free to work on features for your next major version.

IMPLEMENTATION

Ensure current working directory is clean.
git checkout -b develop RC-Branch-Name
git push -u origin RC-Branch-Name

Hotfixing Release Candidates/Releases

Software isn't always perfect. Before you're about to ship a product (or even after you already have), you may run into a few issues – this is where hotfixes come in. Wingman lets you quickly create a place to make quick fixes to a product without getting in the way of any of your other tasks.

Creating a hotfix can be done through the task menu on your release or release candidate. You will be asked to provide a hotfix name, and, when you've finished with it, applying it can be done just as you would any other task.

IMPLEMENTATION

Under the hood, hotfixes work identically to other task branches. They come with their own branch prefix, (creatively named hotfix) and can be completed the same way as their siblings. The only additional function is that changes are applied to all Release Candidates when a hotfix is completed.

Releasing

Wingman lets you keep track of each previous release of your software, giving you the ability to easily go back to any previous versions at will.

Begin by choosing the release candidate you wish to release, then selecting 'Release' from its task menu; this will ask you for a version number.

Wingman then makes sure all changes in the release candidate are present in the develop branch, before merging the release candidate into the master branch, and tagging the release on master.

IMPLEMENTATION

Ensure current working directory is clean.
git pull
Resolve conflicts & ensure working directory is clean.
git push
git checkout develop
git pull
Resolve conflicts & ensure working directory is clean.
git push
git merge RC-Branch-Name
Resolve conflicts & ensure working directory is clean.
git pull
Resolve conflicts & ensure working directory is clean.
git push
git checkout master
git pull
Resolve conflicts & ensure working directory is clean.
git merge RC-Branch-Name
Resolve conflicts & ensure working directory is clean.
git push
git tag Release-Tag-Name head-commit-hash
git push origin --tags
git checkout develop
git branch -D RC-Branch-Name
git push origin --delete

Ignoring Files

Sometimes, you might have files in the same folder as your project which you never actually want to include with the project itself. For this, Wingman provides the ability to ignore select files. The Global Ignore table, found in the the Git Settings tab of the Preferences window, manages any ignored files, allowing you to modify the list as you see fit.

Note that you can use certain characters to help with ignoring files, including * – as an example, ignoring *.class will ignore any file that ends with .class.

IMPLEMENTATION

Wingman creates a .wingmanglobalignore file in your Home directory and instructs Git to use that one as its global ignore file. This file is what is reflected in the Preferences window; anything you add or remove from the window is automatically added or removed from the ignore file at the same time.