Working on prototypes, a lot can change quickly. It’s good to have a record of previous iterations so you can revisit the changes and decisions you made in the past.
I like to keep a running log for each round of research, recording what hypothesis we set out to test, how it worked, and what changes we will make for next time. Following Gemma and the Service Manual team’s example, I’ve started archiving the prototypes so we can go back and see how it has developed over time.
This is useful to compare different iterations of a design side-by-side and to track progression over time.
A super-easy guide to archiving
Using a combination of git, GitHub and Heroku, making an archive is easy. The trick is to use tags.
Tags in git are like bookmarks or pointers to a specific point in history. You could do this with branches, but they can have commits added to them and change over time, whereas tags are immutable and can’t change. This makes them perfect for versioning. (Also I don’t like having a lot of branches messing up my repositories!)
Once you have tagged your iteration you can then create a Heroku app to host it. Heroku lets you have up to 5 apps on a free account, but you can verify your account by adding a credit card for 100 apps (no money is charged to the credit card).
I’ve created an example to demonstrate how to archive prototype iterations. This blog post will walk through the steps I took:
1: Create a tag
I have one main Heroku app (username: iteration / password: prototype) which always has the latest version of the prototype, and I list all the previous versions in the index file.
The first iteration of the example prototype shows a simple form. My commit history looks like this so far:
$ git log --oneline 0abc6fe Create index page 9f2a306 Add confirmation page 3189f09 Add summary page c600139 Add question page dda25b5 Initial commit
All the code shown is from the Terminal. You only need to type the code in bold, the other code is what the computer outputs. The
$ symbol means the computer is expecting input.
Once your prototype is ready for testing, it's time to create a version. To do this, create a tag with the following command:
$ git tag version-1
You can leave a message with your tag, similar to commits. This is known as an annotated tag.
$ git tag -a version-1 -m "First iteration of form for research"
It’s probably easiest to use lowercase letters and hyphens instead of spaces in the name of your tags.
2: Push the tag to Github
Then push the tag to Github:
$ git push --tags origin master
You should be able to see that git has pushed your tag to the remote
To firstname.lastname@example.org:alextea/iteration-prototype.git 9f2a306..0abc6fe master -> master * [new tag] version-1 -> version-1
I also deploy the prototype to the main Heroku app:
$ git push heroku master
3: Create a new Heroku app
Each version of the prototype will be hosted on a separate Heroku app. To do this, you can create Heroku apps on the command line using the Heroku Toolbelt.
$ heroku apps:create iteration-prototype-v1 -r heroku-v1
This also adds a remote to your repository called
4: Deploy the version on Heroku
Now push to deploy the prototype version to the new Heroku app
$ git push heroku-v1 master
You can view this iteration of the prototype at http://iteration-prototype-v1.herokuapp.com (username: iteration / password: prototype)
Rinse, and repeat
Later on, when I’ve added some more commits, and we are ready for the next round of research. The commit history now looks like this:
$ git log --oneline bc44d11 Add link to previous version to index 3eedb3e Set service name in config d7dec39 Use “one thing per page” 0abc6fe Create index page 9f2a306 Add confirmation page 3189f09 Add summary page c600139 Add question page dda25b5 Initial commit
You may have noticed that the last commit is to add a link to the previous version to the index page. This makes it easy to revisit previous iterations of the prototype to see how it has evolved. We can now create the
version-2 tag, and push the tags and code to Github and our main Heroku app.
$ git tag -a version-2 -m "Prototype with one thing per page" $ git push --tags origin master $ git push heroku master
Once again we create a new Heroku app, add it as a remote and push to it:
$ heroku apps:create iteration-prototype-v2 -r heroku-v2 $ git push heroku-v2 master
Version 2 of the prototype is at http://iteration-prototype-v2.herokuapp.com (username: iteration / password: prototype)
Finally, I made the prototype save and display user input:
$ git log --oneline 76d0f4b Update index with link to previous version aa42f73 Show the name of the month 212336f Display data on summary page 63c092e Update forms to save data to session cb0a66e Create dynamic form route 6cc14af Install express-session to save session data bc44d11 Add link to previous version to index 3eedb3e Set service name in config d7dec39 Use “one thing per page” 0abc6fe Create index page 9f2a306 Add confirmation page 3189f09 Add summary page c600139 Add question page dda25b5 Initial commit
I created another new Heroku app and deployed my code to it. You can see version 3 of the prototype at http://iteration-prototype-v3.herokuapp.com (username: iteration / password: prototype) and I have the main Heroku app which lists all the previous versions at http://iteration-prototype.herokuapp.com (username: iteration / password: prototype).
You can list the tags like so:
$ git tag -n version-1 First iteration of form for research version-2 Prototype with one thing per page version-3 Prototype now saves and plays back data
You can view your tags on Github by clicking the releases tab. You can compare changes between tags using the compare view, by either typing in the URL in this format:
github.com/username/repo/compare/tag1...tag2 or by choosing a branch, clicking the compare button, then typing the tag name into branch selector.
Tagging previous commits
If you need to tag a commit you made in the past you need to checkout the commit and add the tag.
$ git checkout cb0a66e $ git tag version-1.2
If you want to push an older tag to Heroku the easiest way to do it is to checkout the tag then create a temporary branch.
$ git checkout version-1.2 $ git checkout -b old-tag
You can then push the branch to the Heroku remote.
$ git push heroku old-tag:master
More information and documentation on tagging is available on the git website.