Valuable and consistent commit messages

In order to provide valuable and consistent commit messages we:

Follow the “imperative present tense” style for commit messages

Write commit message as "Fix bug" and not "Fixed bug" or "Fixes bug" This convention matches commit messages generated by commands like git merge and git revert.

http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

In order to track the effects of changes onto the public API, explicitly classify *every* commit into exactly one of three categories:

Category
Description
Marker
Neutral Only touches things “under the hood” and has no effect on the public API. =
Extending Extends the API by adding things. In rare cases this might break code due to things like identifier shadowing but is generally considered a “safe” change. +
Breaking Changes or removes public API elements. Will definitely break user code relying on these parts of the API surface. !

While working on a feature, you may then end up having many commits, such as:

+ component: add new foo field to the bar object
= test: tidy fixtures
= component: refactor code
+ component: add new foo field to the baz object
= component: update fixture

Merging these directly into master from a branch would be noisy, so from one branch and one PR, we should squash commits into one. Also, given we manage our issues in Jira and there is currently no link with Github, I propose we add the current ticket number into a major commit too. So the single commit in a PR would become:

+ PROJECT-999: add foo to the bar and baz JSON objects 

All commits in the “Extending” and especially in the “Breaking” category should contain a dedicated paragraph (in addition to the summary line) explaining in what way the change breaks the API and why this is necessary/beneficial.

HOWTO: Work on a feature for 'Project X'

...or How I Learned To Stop Worrying And Love The Rebase.

During the inception of our new project I've been working on a proposal for how people can work on features within the organisation. This proposal takes into account branch staleness and preparing a pull request to be merged back into master.

NB: We use Github flow so create short-lived feature branches which are merged into master.

NB: This document is not exhaustive and a working knowledge of git is assumed.

Stage 0: I want to do something!

Our issue tracking is done through JIRA so every item of work in the repo is linked to a JIRA ticket and must be added to master through a branch and a pull request. We don't commit directly to master, ever.

Stage 1: I have a ticket, I want to do work!

First you need a copy of the code.

> git clone <repository url>

Next you'll be needing a branch. Our branches are named with the JIRA ticket number, so if the feature you're working on has the ID PROJECT-01 then your branch should be called PROJECT-01. This can be created using:

> git checkout -b PROJECT-01

...then to add it to remote (to Github etc) use:

> git push -u origin PROJECT-1

If you don't have a ticket, then you shouldn't be working on a feature. :) Now you're in your branch, you can code away! Each commit to git should follow our standard commit message format and make sure the tests pass (and that you /have/ tests).

Stage 2: I want to keep my branch fresh!

We follow continuous integration principles so it's important for us all to make sure we're integrating often and early. By performing regular integrations with what's happening on master, we not only benefit from new features that may be available but we also deal with conflicts as they happen (and they will happen) rather than right at the end when we're trying to merge the feature back in.

Merging into master (when a feature is peer-reviewed and signed-off) should be an 'easy' task of just performing a non fast-forward merge (when we perform a merge that creates another commit on master of "Merge feature X". If it's not easy it's probably because the branch got all crufty and stale...

As often as possible (at least once per day is our team approach) we should be running 'git up' which is a custom command to update  master (and then your branch). To do this add into your ~/.gitconfig file:

[alias]
up = !git pull --rebase --prune $@ && git submodule update --init --recursive

This command pulls and rebases from origin and also uses prune which removes branches in your local repo which have been removed from remote (for example if the branch was deleted in Github after being merged).

So with this custom command, you can do:

> git checkout master
> git up
> git rebase master PROJECT-01

(or obviously whatever your branch is called) You may get conflicts, in which case you can resolve them and push these to origin.

This looks more confusing than just pulling from master, but this approach has the effect that a branch is wound forward in time to appear that it was created from a later commit, rather than having 'merge commits' from master in the branch which at some point would require a merge back into master, which is confusing and can make rebasing your branch much more problematic.

Stage 3: I'm finished so I want to submit my branch for review

Woah, that was quick! :)

You'll need to create a pull request (PR) on Github then ask at least two of the team to review this PR. You may have to go through some cycles of updates before it is signed off, but you'll need at least two separate members of the team to sign off a feature; they will do this by awarding a :shipit: squirrel to the PR. 

If your PR has more than one commit, you will be asked to squash these commits using rebase. The process is quite straight-forward in most cases.

Firstly, determine the 'merge base' of your branch by running:

> git merge-base <yourbranch> master

...(where <yourbranch> is the name of your branch). This will return a hash such as:

b0dea256444af445676e00dd362e3aab9862bc25

Use this hash to 'rebase' your commits by using:

> git rebase –i <thehashyougotpreviously>

This should open an editor showing something like:

pick b0dea25 = PROJECT-01: add library for foo feature
pick 248cd4f + PROJECT-01: add feature to do foo
pick 7dae0c4 = PROJECT-01: add extra fixture for foo

For this branch we have three commits, two having no effect on the public API and one having an effect. We don't want all of the feature commits in master as they may not be appropriate in that context so we're going to squash our commits into one. Edit the file to look something like:

pick b0dea25 = PROJECT-01: add library for foo feature
squash 248cd4f + PROJECT-01: add feature to do foo
squash 7dae0c4 = PROJECT-01: add extra fixture for foo

Exiting your editor will run the rebase then present you with a load of stuff to use as the commit message. Delete all of this stuff and replace it with something like:

+ PROJECT-01: add new foo feature

..then you'll need to push these changes up to Github using

> git push -f

You should now see your PR with one lovely commit which describes the feature. Note that if you have any commits containing either an additive (+) or breaking (!) change, your single commit should reflect this by having this as its prefix.

So our commit would now look something like:

commit 3c48d7a844dd1e504eef12bbab57d5585b615979
Author: Beth Anderson <beth.anderson@example.com>
Date: Thu May 21 17:48:41 2015 +0100
+ PROJECT-01: add foo feature

Stage 4: My branch is reviewed, I want to merge into master

Once you have at least two :shipit: squirrels (we call this the Meatloaf Protocol) then the PR can be merged in Github, although if it can't be merged automatically then you may have to go through another round of sync-ing, which could mean code changes, which could mean re-review...hey, nobody said working in teams was easy! ;) As we follow the Github Flow process, when the PR has been merged successfully, the branch should be deleted as it's now done its job and come to the end of its life.

You've done it! Now time to bask in the warm glory of submitting a feature. A hearty "boat drinks" to you! :)


Midem 2015

After applying to be part of the hacking team a few weeks ago I heard that my application had been successful and along with 25 other hackers I made my way to Cannes for the 2015 Midem hack-day held in the Palais on the front. When we arrived, our view was pretty rad!

After the intro session in the Innovation Factory we all headed upstairs to get hacking although due to my flight being at 6am, meaning I had to check in at 4am, meaning I had to get the train by 3:30am, meaning I had to leave the house by 2:20am, meaning I had to get up around 1:30am, meaning I had about 40 minutes sleep... The first day was a haze of Mars bars, heat, coffee and hacking. It was great! :)

The next day, after a good amount of sleep, we all headed back to the hack-space for our proper full day of hacking. 

We had a great space with a view over the Croisette, which looked stunning at night!

Breaking for dinner (and some went to tech-drinks) we had a couple of hours off to grab some food and drinks before heading back to the hackspace for a late-evening session. It was about 2am by the time I left to head back to the hotel; we had to be back there to finish off and present the sessions in the morning, which are all in this Midem Hack Day 2015 - All the Hacks Unveiled film!

After the presentation we all headed for the VIP lounge for a drink to take the edge off a headache from the amount of coding over the last 48 hours, and to vote for our favourite hack which was Becky's Festival Bag! :)

That evening we all headed out to party and got to dance all evening to Juan Atkins (the father of techno) playing in Les Marches club which was incredible! It was great to cut loose and have a good dance after all the hard work!

It was a really great hack-day and although it was (as they all are) really hard work, we were all so well looked after and all loved being part of Midem!

Au revoir, Midem! Je vous remercie d'avoir organisé! À 2016! :)


Social media links: 



Unit Testing: A Kōan

Early one morning, a programmer asked the great master:

“I am ready to write some unit tests. What code coverage should I aim for?”

The great master replied:

“Don’t worry about coverage, just write some good tests.”

The programmer smiled, bowed, and left.

...

Later that day, a second programmer asked the same question.

The great master pointed at a pot of boiling water and said:

“How many grains of rice should put in that pot?”

The programmer, looking puzzled, replied:

“How can I possibly tell you? It depends on how many people you need to feed, how hungry they are, what other food you are serving, how much rice you have available, and so on.”

“Exactly,” said the great master.

The second programmer smiled, bowed, and left.

...

Toward the end of the day, a third programmer came and asked the same question about code coverage.

“Eighty percent and no less!” Replied the master in a stern voice, pounding his fist on the table.

The third programmer smiled, bowed, and left.

...

After this last reply, a young apprentice approached the great master:

“Great master, today I overheard you answer the same question about code coverage with three different answers. Why?”

The great master stood up from his chair:

“Come get some fresh tea with me and let’s talk.”

After they filled their cups with steaming hot green tea, the great master began to answer:

“The first programmer is new and just getting started with testing. Right now he has a lot of code and no tests. He has a long way to go; focusing on code coverage at this time would be depressing and quite useless. He’s better off just getting used to writing and running some tests. He can worry about coverage later.”

“The second programmer, on the other hand, is quite experienced both at programming and testing. When I replied by asking her how many grains of rice I should put in a pot, I helped her realize that the amount of testing necessary depends on a number of factors, and she knows those factors better than I do – it’s her code after all. There is no single, simple, answer, and she’s smart enough to handle the truth and work with that.”

“I see,” said the young apprentice, “but if there is no single simple answer, then why did you answer the third programmer ‘Eighty percent and no less’?”

The great master laughed...

“The third programmer wants only simple answers – even when there are no simple answers … and then does not follow them anyway.”

The young apprentice and the grizzled great master finished drinking their tea in contemplative silence.


by Alberto Savoia

The History of BBC Radio

In 2009 I joined the BBC and have been part of the Future Media Radio and Music team since then. The BBC has always embraced the Internet and WWW and we've worked on many projects over the years with so many people being involved in bringing the BBCs content to the audience—so I thought I'd look through the Internet archive for past incarnations of bbc.co.uk/radio (or 'slash radio' as we call it) and annotate some of the major milestones in the history of iPlayer Radio with the UK number one from that day...

The earliest archive I can find is this BBC Online site from 1998

Current UK Number 1: All Saints  "Never Ever"

1999 brought a simple re-design, focused around schedules

Current UK Number 1: Britney Spears "Baby One More Time"

Maybe the millenium bug struck in 2000, because this is all the archive has for that year

Current UK Number 1: All Saints "Pure Shores"

2001 started with a bang, with this bold orange and blue site

Current UK Number 1: Bob the Builder  "Mambo No. 5"

By November 2001 the site had a new BBCi look and featured teasers for upcoming stations 'Network X' and 'Network Y'; guess which they are! ;)

Current UK Number 1: Kylie Minogue  "Can't Get You out of My Head"

This design remained until 2003 when 'BBC Radio Player' arrived on the site and the new stations revealed

Current UK Number 1: Room 5 featuring Oliver Cheatham "Make Luv"

2004 saw a small re-design and the—at the time ubiquitous—'make this my homepage' link

Current UK Number 1: Michael Andrews and Gary Jules "Mad World"

2005 saw some more content in the footer and the BBC blocks turned into bbc.co.uk

Current UK Number 1: Elvis Presley  "Jailhouse Rock"

The site was given a new look in 2006 with beveled buttons, more links to audio and the BBC blocks returned

Current UK Number 1: Gnarls Barkley "Crazy"

This design remained for 2007 although the network logos had a re-design to give them a common feel

Current UK Number 1: Timbaland featuring Keri Hilson and D.O.E. "The Way I Are"

2008 kept the same design

Current UK Number 1: Katie Melua and Eva Cassidy "What A Wonderful World"

Although in 2009, the year I joined the BBC, the site had another re-design

Current UK Number 1: JLS  "Everybody in Love"

This remained into 2010 and this year saw the introduction of the 'Barlesque' top navigation menu

Current UK Number 1: Roll Deep  "Good Times"

Which was then moved to the right later in 2010

Current UK Number 1: Rihanna  "Only Girl (In the World)"

The same design remained into 2011

Current UK Number 1: The Wanted "Glad You Came"


Throughout 2011 we were developing the first 'radio product' so in 2012 we proudly released the first version, running on the BBC's new Forge platform.

Current UK Number 1: Maroon 5 featuring Wiz Khalifa "Payphone"


Which then had a darker makeover

Current UK Number 1: Rita Ora "How We Do (Party)"

Later again in 2012 the the 'radio product' officially became iPlayer Radio and we released a new 'landing page' which provided a jumping-off point for visitors and a banner ad for the new native apps for iOS and Android

Current UK Number 1: Robbie Williams  "Candy"

The banner started to be used as cross-network advertising in 2013

Current UK Number 1: Justin Timberlake  "Mirrors"

Then BBC Playlister arrived so the landing page was given a Playlister theme

Current UK Number 1: Katy Perry "Roar"

In 2014 the landing page became the 'dashboard' and displayed a snapshot of what was happening now. So we could display content from all of the Stations we cycle through them, providing a 'pause' button to stop the cycling for accessibility reasons. The site also had the 'radio nav' lower navigation for quick access to stations, categories etc and featured a Playlister link.

Current UK Number 1: Pharrell Williams  "Happy"

The logo got a boost in point size and the a-z button arrived

Current UK Number 1: Meghan Trainor "All About That Bass"

Later in 2014 we decided to change the 'pause' button to a 'stop cycling' button as it was causing confusion.

Current UK Number 1: Gareth Malone's All Star Choir "Wake Me Up"

Playlister then left the radio nav to develop its own identity

Current UK Number 1: Ben Haenow "Something I Need"

Which brings us to the current site in the early part of 2015

Current UK Number 1: Mark Ronson featuring Bruno Mars "Uptown Funk"

We've been working on 'iPlayer Radio v2.0' on our new cloud platform for around a year now so 2015 will see another step-change in the BBC radio website from its humble beginnings as a simple BBC Online website.