In leadership positions it can be important to protect a team, whether it’s from organisational noise, stress around change, or just focus. It’s easy to feel a burden of responsibility, especially if the team isn’t healthy or there are lots of external pressures you can’t control.

It’s certainly important to build and maintain psychological safety in any team, but when I’m thinking about safety I’m reminded of Cave Rescue training where it’s the other way around.

Self, team, casualty

I was surprised on my first casualty care course. One of the first things we covered was assessing the situation and making sure we weren’t putting ourselves in danger. Our instructor summed it up nicely:

If you rush in and get hurt, what use are you to the casualty? You’re another casualty, and that might make the rescue more dangerous for the rest of your team.

Fine, so you’re making sure you’re safe. Now the casualty is the priority. Nope. Your next responsibility is to the team’s safety. Pretty much for the same reasons. One person alone can’t haul a casualty out of a mine, so it’s all about working together safely as a team, watching out for each other.

So the casualty is last.

Last doesn’t mean unimportant

Even though the casualty sits at the bottom of the list, they’re the whole reason a group of volunteers set off to help in the first place. They get specialist medical attention and a personal stretcher carry. If they’re lucky maybe even a helicopter ride. Taking care of self and team enables that level of care.

But team leadership isn’t a rescue

Okay, you’ve got me there. It’s a bit outlandish to equate running an engineering team to rescue services. But there are lessons to take from it.

For yourself

If you’re not in a good place you can’t help your team. Take holiday. Finish on time. Say no. Different people need different things, so just make sure you’re looking after yourself.

I still really struggle with this one. It’s easy to fall into the trap of trying to “just push through”, and I’m a sucker for thinking things will be easier after this one last thing. Spoiler alert: that one last thing always unearthed something else. Quelle surprise.

For your team

Empowering your team to look after themselves is no easy task. Often even a supportive, safe team will have members who work through sickness or work late to get something over the line. In the UK I’ve found a cultural aversion to sickness absence, as if it’s a failure to be ill and need to rest. It doesn’t help that we often celebrate the unhealthy behaviour – staying late to meet a deadline, coming in on a day off to save the day. These things get praise in all-hands meetings, they get your name known, and they maybe even get you a promotion.

Back in 2016 Government Digital Service wrote “It’s okay to say what’s okay” and it holds up well today. It’s incredibly powerful to give individuals permission to say no, or not know everything. Even so, it’s often hard to advocate for ourselves so watch out for when your team is struggling to do it. It’s often easier as an outsider to see what’s happening.

Finally, one of the best things we can do is to lead by example. By taking time off when we’re ill, and demonstrating that self-care is important, we normalise it. Conversely, if we say taking mental health days is important but never take them ourselves, we’re modelling the unhealthy behaviour.

• Related: Will Larson has some interesting thoughts about company, team, self and motivation.

While working on a project with a long history, we wanted to introduce Rubocop to lint the codebase. Being a large project, enforcing linting on the entire codebase wasn’t feasible – thousands of offences and over a thousand that aren’t auto-correctable.

😱

Instead of spending a soul-crushing few days trawling through the offences or blocking pull requests until it’s all perfect, we can start by just improving the files we change. This is surprisingly high-value – the files we change regularly quickly become “standard” and the ones we never touch… well it doesn’t matter if they’re linted if we never look at them.

Linting only the files that have changed is fairly straightforward. First we need to find the files that have changed (e.g. for the main branch). We can do this with git diff and filter for Added, Modified, and Renamed files:

git diff --name-only --diff-filter=AMR main...

(thanks to this StackOverflow answer) for inspiration.

Depending on our linter, we’ll probably want to filter those files so we don’t confuse it. Rubocop will attempt to parse things like .erb, and it won’t have a good time. If we only want to process files that Rubocop thinks it can handle we can use:

rubocop --only-recognized-files --autocorrect -- file_a.rb file_b.rb

We can put this together to get a one-line command that runs Rubocop over any files that have been added, modified, or renamed:

rubocop -a --only-recognized-files $(git diff --diff-filter=AMR --name-only main...)

An early version of this approach used xargs to pass files, however this doesn’t always play nicely with Pry, rending the breakpoint non-interactive. I didn’t get to the bottom of that, let me know if you have any ideas on Mastodon.

Then all that’s left to do is commit the changes with a suitable emoji 😘.

Why not use an editor extension?

Once you’ve got a consistently linted codebase it makes a lot of sense to use editor extensions for EditorConfig, Rubocop, or your linter of choice. These will auto-lint or highlight offences in your editor, which prevents us from adding non-compliant code in the first place.

However they’re less helpful when you’re introducing linting because auto-linting a file you’ve touched groups changes to code with linting modifications. This increases the complexity and cognitive load for both reviewers and future developers spelunking the codebase, possibly mid-way through debugging a tricky error.

In this case it’s friendlier to separate the Rubocop linting from other changes. This might mean separate PRs for linter fixes, or a separate commit in the same request.

Continuous Integration is your friend

Once the team is able to lint the codebase locally and apply fixes, the next step is to add that linting to your CI service to validate that pull requests consistently improve the codebase.

Depending on your CI service, you may want to make those checks non-blocking to start with. Your teammates who make a one line change in that thousand line file will be thankful!

We need to make our CI script a little smarter than the one we’ve been running locally, because branches with no additions, modifications or removals will cause Rubocop to run over the entire codebase. There are a bunch of scenarios where this is true, for example removing legacy unused code or renaming a bunch of files.

To work around this we can check to see whether the list of changed files is empty before passing it to Rubocop:

CHANGED_FILES=$(git diff --diff-filter=AMR --name-only main...)

# -n checks whether the list of changed files is null, to prevent Rubocop from running over
# the _whole_ codebase if we've only removed files from the branch
[ -n "$CHANGED_FILES" ] && bundle exec rubocop --only-recognized-file-types $(echo $CHANGED_FILES)

I had this recently, joining a team where I just couldn’t get our RSpec feature tests to run on a fresh machine and checkout. Many tests failed with “Too many open files”:

Failure/Error: initialize_tcp host, port, local_host, local_port

          Errno::EMFILE:
            Failed to open TCP connection to 127.0.0.1:9526 (Too many open files - socket(2) for 127.0.0.1 port 9526)

This led me to a gotcha in Capybara/WebMock that was causing the error. I still have no idea why this affected my Ruby build on MacOS Ventura, but none of my colleagues 🤷‍♂️.

The error occurs because Net::HTTP has separate connect and request phases, but WebMock was designed with connect being part of the request step. Because there’s no information about the request in the connect step (just the destination address), WebMock can’t decide whether to stub or pass through the connection at that point, so they made the design decision to delay connect until a request is made. This is the approach of many HTTP libraries, but not Net::HTTP.

Fixing the error appeared to be as simple as setting net_http_connect_on_start: true to undo WebMock’s workaround for Net::HTTP, however this introduced a new SSL certificate error for a mocked request. This was curious, because the requests are supposed to be mocked, so we don’t expect any external connection to be made.

It turns out that setting net_http_connect_on_start: true works around the Capybara gotcha by enabling all Net::HTTP connections to be made¹, while still intercepting and mocking the requests appropriately. We happened to see an error because of an SSL certificate problem on a host we didn’t really want to connect to.

Scoping eager connections

Thankfully, net_http_connect_on_start is smarter than just accepting true or false. There are a bunch of tests showing net_http_connect_on_start accepts:

• Regular expression matching host
• Host
• Port
• Scheme (e.g. http, https)

For our test suite, we disallow all connections except the Capybara server, so the working solution for us was to scope net_http_connect_on_start to match the allowed host:

WebMock.disallow_net_connect!(
    allow_localhost: true, 
    allow: Capybara.server_host, 
    net_http_connect_on_start: Capybara.server_host
  )

For another gotcha: WebMock supports passing a list of hosts to allow, but this isn’t supported by net_http_connect_on_start, where you’ll need a regular expression instead if you have multiple disparate hosts.

Switching to Lima was straightforward, but I found myself scratching around trying to find how to get back to the Docker Desktop config.

For when I forget next time:

# list the contexts so you pick the right one
docker context ls

# switch to Lima
docker context use lima 

# switch back to Docker Desktop
docker context use default 

A few months a go I moved to Mastodon, and after settling in found a home on ruby.social. I kept my Twitter account, partly as a defence against it being taken by someone else (because @spikeheap is such a desirable username 🙄), but mostly because I wasn’t convinced things wouldn’t recover.

In the end, a couple of things pushed me to delete my account:

1. Gutting of the safety and moderation teams, alongside prominent right-wing hate-speech peddling accounts being reinstated. I’d love to say this was the clincher, but really it just fuelled my rants until…
2. Banning of journalists and users critical of Twitter’s new direction, particularly around the elonjet account. This coincided with a ban on accounts telling followers where they’re moving to (or where they also post content), and we saw accounts with Mastodon links suspended.

I don’t fancy spending my time on a platform that legitimises hate speech under the guise of “freedom”, and while I think Twitter will end up having to moderate these users to comply with the law in many countries, preventing people from exporting their followers in the meantime just feels petty.

So that’s a bit of a rant. It doesn’t bring anything new that hasn’t been said thousands of times in the past month or so, but I wanted to write it down so I can reprimand myself if I find myself reaching for it again.

What I will say is that Mastodon has the potential to be a much calmer, happier place. Just before the Twitter exodus there was a pleasant level of positivity, with negative and triggering things hidden behind content warnings so I could scroll past it.

The “local” and “federated” aspects of Mastodon have received a bit of criticism, but I’ve enjoyed having a local feed which mostly contains Ruby and content from Ruby people. It feels more like a community than following hashtags.

There’s a period of readjustment as a mass influx of new users come from Twitter, many hoping for it to be approximately the same. I’m hopeful we get past the “my outrage doesn’t need a content warning because it’s important”.

You can find me on ruby.social/@spikeheap.

My Sonder Camino Ti arrived in November 2020 with the FSA Non-Series off-road wheelset. After 9 months of mixed British riding, including a long, gritty winter in the Peak District, both wheels developed a bit of play and looked like they needed new bearings.

FSA/Vision have technical documents with lists of service parts for the wheels, but these use non-standard part names, and mapping these to the international standard was only possible once I stripped the wheels down and read them off the bearings themselves.

Front wheel

• Vision/FSA code: MR199
• Actual size: 15x26x7mm
• Quantity: 2
• Bearing code: 15267–2RS (2RS just means there are 2 rubber seals, which helps protect the bearing from grime)

These can be removed with a bearing puller, and refitted with a standard bearing press with 15x26x7mm drifts, such as this one.

Rear wheel

• Vision/FSA code: MR200
• Actual size: 17x28x7mm
• Quantity: 2
• Bearing code: 17287–2RS (2RS just means there are 2 rubber seals, which helps protect the bearing from grime)
• The freehub contains a couple of the same bearings, but I couldn’t remove them, and ended up ordering a full replacement freehub (EL298).

As these have different dimensions, they need a slightly different-sized bearing puller.

To fit/refit the bearings, you’ll need a press with over-axle drifts because the captive axle gets in the way of a standard press once you have the first bearing in. There’s also a cheaper alternative approach if you have a socket set — Youtube is your friend there.

I’ve found Henderson Bearings to ship quickly and last a decent time, though I don’t know enough to say whether their “Enduro” branding is just marketing or a lot better for bikes.

This post was originally published on Medium.

The bike came out of things pretty well, and just needed the mech hanger bending out, a new GRX shifter and some bar tape. The hardest part of getting that back on the road was sourcing the shifter, with both Shimano and SRAM components being in short supply this year. My clothing was another story…

Suprisingly enough, most road cycling clothing isn’t built to be bounced along the tarmac, and I managed to damage everything I was wearing except my shoes (thankfully my ready-to-be-replaced overshoes took the brunt of that damage). I’d picked a terrible time to do this, as a few things were really new. My 3-week-old Castelli bib tights had a big hole in them, and my month-old POC helmet had a big dent too. For some context on how pleased I was with Rapha, I’ve been comparing them with these two brands:

• POC ignored tweets and a couple of emails. They mention a crash replacement programme in North America, but not Europe, but I never got an answer about whether they do or not. The helmet was amazing, but the service less so.
• Castelli’s UK replacement policy is oddly complex, with extra discount if you’ve bought directly from Saddleback. This one was the most frustrating — the almost-new bib tights needed a replacement panel, and it felt very wasteful having them destroyed for 40% discount on a full-RRP set. In the end I picked up a brand new set from Sigma Sports with a reasonable discount (though not 40%), and am waiting for Alpkit’s repair stations to open up as lockdown lifts. Hopefully I’ll end up with a slightly scrappy pair for mountain biking 🤷‍♂️.

The thinnest, lightest thing I was wearing was my Rapha Brevet high-visibility jacket, which came off peppered with holes and a couple of tears. I love this jacket. It’s reflective stripes are perfect for winter riding when you end up in the dark more often, and it still packed down small and breathes really well. Maybe a little too well after the fall…

Here’s a few “before” photos

Of all the damaged clothing, this was the one I assumed was destined for the bin. It’s a couple of years old, and a very fine material.

I knew Rapha had a free repairs service, but couldn’t find anything on the internet other than a forum post that said they’d got a free replacement and it had taken 5 weeks. With nothing to lose, I took the photos above, sent them to Rapha and had it in the post the next day.

Three and a half weeks later a package turned up, and in a nice little “first aid” tote bag was my repaired jacket. Here are a few photos of their handiwork:

I’m more than satisfied with the repair. Sure, it’s no longer as-new, and the back panel adds a little more bulk to the jacket, but when there’s all the other expenses of replacing clothing and components I couldn’t be happier that I’ve not had to shell out (excuse the pun) on a new jacket.

Five stars, but I hope I don’t need to use the service again anytime soon!

This post was originally published on Medium.

Woodhead Reservoir, three quarters of the way up the biggest climb of the trip

It’s been a long time since my last multi-day adventure ride back in 2013. I’d almost forgotten what it was like to get into the trance. Spinning the pedals, taking in the scenery, thinking about the next milestone, and yet still feeling a long way from the end. This time I was riding along with audiobooks and music instead of friends and family (thanks jobs and pandemic 🙄), but as soon as I set off I felt that calm focus of knowing there was only one thing to do today, and it would take all day.

I should mention that I didn’t bivy or ride self-supported, which is a bit against the spirit of the Racing Collective events. With my dad just round the corner and eager for a road trip, we had a great excuse for a family adventure even though he can’t cycle. I was quite grateful for this in the end — not just because I get on well with my parents, but also it was nice to have someone to chat to. Riding solo suits many people, but I found myself itching for someone to share my highs and lows with as the trip unfolded.

The route

The Racing Collective’s EnglanDURO event is the first weekend of August. I had other commitments, so rode it a week or so early. The route starts at the Liverpool seafront, and snakes its way northeast to the sandy beaches of Scarborough. Despite passing through Liverpool, Warrington, Stockport, Wakefield, Castleford and York, the towpaths, bridleways and cycle routes never felt too built-up or busy.

Before leaving I was a bit nervous about the trails being busy with walkers. There’s a lot of distance to cover, but it’s not cool to shoot past people at 25km/h just because you’ve got a goal. Thankfully this wasn’t a problem at all. Other than a slow canal-side section in York where many were enjoying the sun, paths were often wide enough to ride at a reasonable speed, and elsewhere it was pretty quiet.

My parents live in Castleford, so it made a perfect break in the trip, breaking it into a longer 170km first day with 1500m height gain. That left day two with 130km and 500m less height gain (in theory).

We set off early to drive to Liverpool, and I was cycling along the waterfront by 8am, passing a steady stream of commuters, runners and dog walkers. The cycleway is wide, flat, and has great views to shipyards and the wrecks of old piers across the water. It felt great to build up some momentum right at the start, even though there wasn’t time to stop and look at the myriad statues and memorials along the front. I soon joined the Trans-Pennine Trail around Hale, which I’d be following for most of the day, and the first hike-a-bike section, carrying the bike up a switchback of stairs by Ditton Marsh. After the fast, open start, the slow trudge up the steps felt like a bit of a setback, but don’t fear: there are only a handful of these on the entire route.

The first 80 kilometres wind peacefully along the Mersey with the terrain and views changing frequently. I’d been expecting more “industrial heartland”, but the cycle route manages to hide it away behind trees and inclines. Blips of business like John Lennon Airport were short-lived and soon forgotten. Despite the gentle gradients, I wasn’t fooled. The climb over Woodhead Pass loomed in the distance, waiting to see if I had enough energy left for the last big push. Thankfully that climb ramps up slowly, at least until you cross the A628 when you wonder when you’ll need to push. The reward is continuously amazing views (e.g. the photo at the top of this page), and friendly exchanges with other cyclists and walkers. No-one is finding that climb easy!

Elevation profile for Liverpool to Castleford

With the biggest climb behind me, I had a big grin on my face down to Penistone. The official route turns off Windle Edge to touch Winscar Reservoir before descending off-road to Townhead. This path is now private land with no access, so I retraced my steps back to the main road. From Townhead the route jumps back off-road to follow the River Don down into Penistone, where the last significant climb of the day awaited.

The descent into Bretton Country Park

After spending so long climbing, the long undulating descent was a playground for the energy I somehow managed to conjour in my legs. The area around Bretton Country Park and Yorkshire Sculpture Park was absolutely beautiful, with fast, flowy, open trails. A short glance at the lake at Pugneys Park was next, before joining the canal towpath that I knew would take me all the way into Castleford. There was a tiny hitch joining the canal — the last 100m of the path that joins Pugneys to the canal was closed. A bit of back-tracking (and some helpful people who’d just come the other way) led me out, and then it was just glorious, flat towpath that led to food, stretching and sleep after eleven and a half hours on the bike.

The stretch of canal before Methley

A route of two halves

I’d been quite nervous about the second day, and cautious about how much my pace would drop with tired legs, so I set off before 7:30am. I don’t know where this fear came from — we didn’t have a deadline to arrive in Scarborough other than “before the fish & chip shops close”, but when you’ve not done the distance in a while it’s easy to assume you’ll be crawling along at a snails pace.

Castleford weir.

It was this photo on the Racing Collective site that made me realise the route passes so close to my parents’ house

Thankfully for said tired legs, I started with a gentle stretch along the towpath with cool, clear skies and a little dew on the ground. I had a crisis of confidence when the route turned off onto a walkers-only footpath through Fairburn Ings. Normally I’d figure out a cycle-friendly alternative, but being a bit tired and wanting to make progress, I decided there probably wouldn’t be anyone there so it’d be okay. My guess was correct, and I popped out the other side to start the first climb of the day over to Ledsham, which was a nice quiet path through the woods.

The following 30km on road and paved towpaths felt fast, and set the tone for the day. Where the first day had been 60% dirt, day two was 70% paved, which had the unexpected benefit of increasing my pace even though I was a bit more tired. Slowing down in York to carefully pass walkers and other cyclists enjoying the sun, I was reminded that today was supposed to be overcast with rain. Lucky!

The hills before Kirkham Priory

After York things returned to what I’d expect from a ride in Yorkshire. Hills. Up and down. Short, sharp efforts. And great views. Passing Kirkham Priory brought back childhood memories, and I was more than happy to wait for the trains to pass in the valley before the crossing reopened. There’s a significant climb that reaches 17%, which was a really convenient point to lose signal and have my audiobook cut out. Again, it’s hard to complain because the road was quiet, and the surface pretty good.

🥵 At least they let you know it’s coming

I’d studied the elevation profile for day two, so I knew that after this climb there was a good rest before the final significant hill of the day. The big one, albeit a lot smaller than Woodhead Pass of yesterday. I realised I could make it to Scarborough. One more big hill wouldn’t stop me, and my legs felt pretty good. I passed the Cayley Arms, crossing the main road to start the climb. Fortunately it’s closed on Tuesdays, otherwise I can’t say for sure that I wouldn’t have succumbed to the lure of a cold drink and a rest. At the base of a steep climb it would have been a bad call.

Near the summit in North Riding Forest Park

The climb up into North Riding Forest Park was actually pretty pleasant. The road had no traffic and only the occasional walker. It’s gruellingly steep in places, but gets its steepness out of the way in the first half before trading road for track and easing off the closer you get to the top. The last gentle climb followed tracks through fields. On any other day these would have been a joy to ride, but after several days of warm sun the track was rock hard and pitted with footsteps and hoofprints. This left a knobbly trail that juddered the gravel bike and shook me to my core as I tried to build up speed after the slow climb. Things just got better and better as field led to smooth, wide forest track, and I chased a motorbike as we both sprinted down the long straight trail with tall trees either side. What a feeling. This was the last big climb of the trip, and I knew Dad was parked up at the end of the trail with snacks and cool drinks. It was only when I met Dad that I heard the bad news…

🤬 I thought this track was blocked

They really don’t want anyone in there. I’d already used my “I’m normally good so it’s okay if I break the rules” card back at Fairburn Ings this morning. Fair cop. A quick look at the map showed this is the only track north. My only option seemed to be to head south to Ebberston and suck up a stretch on the busy A170 before turning north again to get back to the route. I was a bit demoralised at the thought of going in precisely the wrong direction, and doing a 15km round-trip to bypass 1km of closed path, and my mood didn’t improve as I realised the descent to Ebberston wiped out all my height gain. In Snainton I turned and re-climbed the hill, grumpy until I remembered how fortunate I was to be out there in the first place. Sure it was an unexpected hill, but it just meant I got to spend more time on the bike. I was still well on track to arrive in Scarborough in time for dinner. It was worth climbing back up for the stretch across Wykeham Forest and a steep descent on road towards Hackness.

Update: Thanks to North York Moors NP, it looks like I just missed a bridleway to the right of this photo.

The route left the road for one last hurrah, climbing up gently in woodland on established trails. Eager to drop into Scarborough, of course it was here that I met a walker who just needed someone to talk to. What started as a request for directions took a surprising turn into a life story about divorce, moving to Birmingham, and disdain for their neighbours. I felt quite uncomfortable when he started sharing his views about people on benefits, but chose escaping over setting him straight. They were so reluctant to let me go, striking up new lines of conversation. I hope they find someone to talk to.

Thankfully the last stretch into Scarborough was uneventful. A surge of “almost there” energy had me racing to the seafront, where a huge number of people were making the most of what had turned out to be a warm, sunny day.

The pier in Scarborough. The sea is such a great place to end a ride

The only thing left to do was hide the bike in the car, meet some friends on the beach, and fight off seagulls while we devoured fish and chips.

Would I recommend the route? Absolutely.

What’s a trip to the seaside without fish and chips?

Route alterations & roadblocks

If you’re riding EnglanDURO21, or just following the route sometime soon, here’s a summary of the alterations I had to make. You can see my full tracks on Strava for day one and day two.

1. Windle Edge/Pennine Sailing Club (Google maps). The track is now private land, so stay on Windle Edge (don’t turn into the sailing club) into Townhead to rejoin the route.
2. Pugneys Park near the end of the lake (Google maps) has fenced off the track, but if take the north fork at the point on the map (rather than north-east following the route) you can join it a little further on.
3. The Fairburn Ings entrance from the Aire & Calder Navigation towpath (Google maps) is footpath-only. If you’re early in the morning or late in the evening this is probably fine, but the path is quite narrow in places so best avoided when it’s busier. To avoid it completely, stay on the A656 and follow it into Allerton Bywater before turning right onto Newton Lane to rejoin the route (see diversion on OpenStreetMap). This diversion only adds a couple of hundred metres to the day.

Links

• Huge thanks to the Racing Collective for putting the route together: https://www.theracingcollective.com/englanduro.html
• Day one track: https://www.strava.com/activities/5691283829
• Day two track: https://www.strava.com/activities/5695664642
• #EnglanDURO21 Spotify playlist: https://open.spotify.com/playlist/0BgDygP557YMg5KMSsflAO?si=55af91d8c27044e6
• The Twilight of Democracy on Audible: https://www.audible.co.uk/pd/Twilight-of-Democracy-Audiobook/0241481821

This post was originally published on Medium.

Then one day, something happened to restore peace. Swanky editors with soft-wrap, style guides, and EditorConfig united developers around one principle: consistency. Consistency was hard to argue against, and as tooling made it easier to promote/enforce we started to realise that the actual choice didn’t matter that much really.

So our armies retreated to our caves, ushering in an age of peace and productivity. But with that peace came complacency, and murmurings started again, this time around code collaboration. The Git Flow Wars of the 2010s saw the resurgence of trunk-based development and a return of the endless debate, this time around whether git rebase was a silver bullet or a corrupting force of evil.

Now we’re well into the age of the Pull Request, and the questions are coming back. Who should merge them? How big should they be? What should they contain? How should we review them? Disciples of the many “One True Way”s are out in force, but we already know the answer: it probably doesn’t matter what you pick as long as you’re consistent. Consistency within a team or organisation is what we’re after, not consistency across a career.

As a technical lead, delivery manager, or just someone hoping for a quiet life, here’s a checklist of the subjective debates that risk bikeshedding and becoming a time-sink. When they crop up in reviews it’s a “smell”, a signal that the team has a diverging understanding of concepts that we need to be able to rally around. It’s tempting to set up a session to talk about how you should be doing things, but that’s a red herring. The first thing you need to do is get agreement on how you are doing things, and write that down. We can call it a Team Charter, a Ways of Working document, or anything meaningful to your team. The important thing is to document the decision. For an extra point capture a simple “why”.

Once we’ve captured our baseline, we can apply some agile goodness and iteratively improve the way we work. Retrospectives are a great place to reflect on how your ways of working help or hinder you, agree experiments to try, and evaluate their effectiveness.

The list

There’s nuance to many things on this list, and there may be objectively “better” options, but often they’re marginal gains rather than the only way to avoid catastrophe.

The list is grouped into three areas: commit etiquette, pull request scope, and how we merge.

Commit etiquette:

• Step-by-step commits.

• Merge main into the branch or rebase?

• The perfect commit history.

• All commits pass CI (e.g. enforced git precommit hooks)

• Commit messages. Is there a format? Do we use semantic commit messages? Should every message contain Gitmoji?

• Should lint fixes be a separate commit?

Pull request scope:

• “Scouting” and refactoring as a separate commit or different PR?

• Coverage & quality creep. Is it okay for a single PR to leave the codebase slightly worse?

• PR size. This is the big one! Should there be one PR per card/issue, or many tiny increments?

• Do you use/how do you use “draft” PRs? Are they for presenting ideas, or work in progress. What’s their lifespan?

• PR descriptions. Do you have a a standard template? What do you expect to see in a description?

• Do we use labels? If so, how?

• Are chained PRs allowed?

• “Fix in this PR” vs “I’ll add that in another PR”.

Merging:

• Squash, merge, or rebase into main?

• Request changes vs comment vs approve. What are the implications of each type of response?

• How do we request review (ask on Slack, auto-post, email notifications…)? Is a review open to all, or do you invite specific reviewers? What if you’re not invited but care?

• What’s the review process? What’s in scope? Do you value high level or low level comments, and when is each type appropriate?

• Minimum reviewers

• Does it need to be up-to-date with main before merge?

• Who decides if it can be merged? The author or the reviewer?

• Who merges the PR (again: author or reviewer)?

Record your ways of working

Now you’ve figured out how you work, you’ll want to write it down. Without wanting to open another can of worms, there are a couple of qualities common to team charters which are actually read, honoured and evolved by teams I’ve worked with:

1. They’re short and concise. It feels good to write 2000 words on the primacy of meaningful commit messages, but think about your reader. A new team member doesn’t want to lose two weeks trawling a book on how they should collaborate. Brevity is key. Short documents are easier to scan, and brief (1 paragraph) points are more easily pointed to. If you *really *need to write more to explain your decision, capture this elsewhere (Decision Records are great for this).

2. Each point is linkable. Being able to point at a specific rule in a pull request comment or chat makes conversations more concrete, and lowers the barrier to entry for reading and following. Most wikis and markdown renderers add IDs to headings so you can link to a point in the document, for example this rule in the Ruby Style Guide on GitHub.

Conclusion

Create a style guide for your ways of working, and encourage slow, thoughtful evolution over time. And don’t assume that what works well for your team is inherently the One True Way.

This post was originally published on Medium.

Planning the day

To get things moving we set up a Slack organisation, a GitHub repository with a static site using GitHub Pages, and bought the remotehack.space domain name. We wanted to keep organisation and attendance lightweight, so after starting with a GitHub PR approach like SusHack we opted to open signups for the remote-hack Slack group and use chat/signups to gauge interest. We shared details on local Slack groups (Digital Oxford, Sheffield Digital) and Twitter.

We already had access to a paid Zoom account (to work around the 40 minute limit on free accounts), so created a link and shared it in the Slack. The barrier of Slack signup worked well for preventing random Zoom trolls from finding the link on Google, and made sure we had a common place to come together, kick off the day, and talk.

That’s it. We were conscious that a smaller group would likely be more sociable and reduce the challenges for the organisers, so didn’t push too hard on social media.

On the day

The start of an in-person hack day often revolves around a whiteboard to collect ideas (and a load of free pastries and coffee). To make this work for a distributed event we used the GitHub issue tracker and asked people to add ideas in the lead-up to the event.

We opened up the Zoom call 30 minutes early, and as people trickled in we had a great, informal chat before getting into things, setting the scene and then going through the ideas on the issue tracker and picking groups.

People worked in different ways. Ben and Gabor were keen to try out Visual Studio Code’s remote collaboration feature , while Mike and I paired most of the day using Screen. Adam and Ed hacked alone. Most of us ducked out of the Zoom call, but continued to chat on Slack.

When we’ve run in-person hack days like Summer of Hacks (the domain is dead, but the yellow lives on) lunch has been a pretty big deal. We’ve been fortunate to have sponsors cover custom Mexican food for lunch and use that as a lever to get everyone back together to chat and be sociable.

We really love burritos:

Thanks so much to @HaybrookIT for a fantastic lunch today at #RTHack pic.twitter.com/wpwLOMp4Te

— JSOxford (@JSOxford) April 11, 2015

How do you translate that into a remote hack day? We had the great idea of doing a distributed lunch, and just all ordering our burritos (or whatever took our fancy) to be delivered at the same time.

Around 1pm we rejoined the Zoom call and hung out for half an hour, chatting away as Ben and Sarah ate burritos (I’d failed to make an order in time, so just had FOMO instead), before splitting back out into our groups and cracking on.

We’d planned to close up around 5pm, and came back together at 4:30 to show, tell and chat a bit more. Mike and I were so close to adding machine learning to the sentiment-bot (well, except for me having a .dev domain problem preventing any dependencies from downloading, and Mike not having ngrok set up). By 5:30 we’d been around the groups, chatted a bit more, and closed up to go our separate ways. I headed straight downstairs for a cocktail and a call with the family.

What worked?

• A communal group call worked well for a small number of people, but could quickly become unwieldy with larger numbers. We managed to avoid the webinar-style call with everyone except the presenter muted, and really wanted to highlight the social aspect of the event.

• Starting small. Running a day with 5–6 people I knew pretty well was a pleasure, and created a great atmosphere.

• Keeping the chat going on Slack. At work I find this quite distracting, but it was great to have light-hearted interruptions during the day. It probably helped that Mike and I were building a Slack sentiment analysis bot…

• Screen for remote multiplayer/pairing. It felt like the good old days of ScreenHero, and Mike and I took turns sharing screens.

• It didn’t feel like work. Even though we were coding, it felt fun, sociable, and there was no pressure to deliver anything.

What didn’t work so well?

• Distributed lunch orders. I forgot! It’s also quite nice to jump back into home life — I went to catch up with Nev and have a quick lunch, but felt I should be back to be part of the day. When you’re all on-site there isn’t that contention, but I’m not sure which way I’d want it to go.

What would I try next time?

• Shorten the round-table ideas session first thing. We ended up talking about each idea fairly extensively, so I’d like to try keeping it to a 1–2 sentence summary of the idea, and then flesh the idea out in breakout groups so we can get started sooner.

We’ll be running the next event on Saturday the 25th of April. You should join us: https://remotehack.space.

Originally posted on Medium.