⛵ What is a writing raft?

First proposed by Hrvoje Šimić, a writing raft is a club that forces you to write.

The rules are simple:

1. You must publish a blog post by the end of the month.
2. If you do not publish on time, you’re out of the club (for a month).
3. The club is limited to 5 members.

Željko Filipin conceived of our little Junto towards the end of 2020.

Today we have three members: Me, Željko, and Kosta Harlan. And as of December 2022, the three of us have managed to stay on our raft for one. full. year.

In honor of this milestone, we’re all posting about lessons we learned over the past 12 months.

🍎 Lessons from a year of writing

Blogs should be easy to read. In 1997, Jakob Nielsen succinctly summarized “How Users Read on the Web”: “They don’t.” I use short sentences and omit needless words. And I try to make my blogs look easy to read to keep readers moving.

Get to the point. Nobody has time for throat-clearing—start with your point. If you need more details, add them later.

Your unconscious mind is a better writer than you. Writing and publishing on the same day used to be my habit. Now, I let my rough drafts sit for a day. And I often wake up with a better idea, clearer point, or different direction—even if nobody gives me feedback. My unconscious mind was working on my writing the whole time.

The core question is not how you do math but how does the unconscious do it. How is it that it’s demonstrably better at it than you are?

– Cormac McCarthy, “Stella Maris”

Practice in public. It’s the fastest way to improve. Another deal I made with myself this year is that after I publish a post, I must link it somewhere online.

Internet strangers are a fickle crowd, which makes them a great litmus test for your writing. If a post generates nothing but silence—why not tweak it?

Figure out how to say it better and try again. And try to learn something for next time.

Peer pressure is a tool. The writing raft has shown me: I need someone to notice if I skip a month of writing. Writing the first draft is painful. Knowing I have a deadline keeps me moving through the pain.

And conclusions. I’m so bad at conclusions. But I’m working on it ¯\_(ツ)_/¯.

• Kosta’s post: A year of writing club
• Željko’s post: Two years of blog post writing club

Cheap temperature sensors

I have a handful of AcuRite sensors sprinkled throughout my house.

These sensors are $16 today, but I bought mine around 2017 for $12 each at Home Depot.

I know I could cobble together a cheaper temperature sensor:

So for like $10 + solder + a weekend fiddling, you could make a craptastic internet-equipped temperature/humidity sensor.

But I dreaded building it.

Tinkering with electronic doodads is a fun hobby. But I just wanted something cheapish that would work.

And the AcuRites work.

Plus, the AcuRites work forever on a couple AAAs because they eschew power-hungry wifi in favor of squawking data on 433 MHz.

433 MHz, the original IoT protocol

Even though 433.92 MHz sits squarely in the 70cm ham band, tons of electronic junk spews signals on that frequency.

And with a $25 USB dongle and free software, it’s easy to decode messages chirped out by your AcuRite temperature sensors.

So far, this project had been cheap and simple. But the next step, gathering the data into a time-series database, required more fiddling than I’d expected.

Home Assistant, MQTT, Prometheus, and Grafana.

It was a pain to get rtl_433 data into Home Assistant.

Maybe I’m missing something. But I ended up with a more complex system than I wanted:

1. a systemd unit running rtl_433 with syslog output over UDP: rtl_433 -F syslog:127.0.0.1:1433
2. a systemd unit relaying and filtering syslog output to MQTT (based on this upstream example)
3. a systemd timer to restart rtl_433 when it unexpectedly hangs (often)

After endless fiddling, the relay has an uptime measured in months—it’s stable.

From there, pushing data to Home Assistant, exposing it via the Prometheus plugin, and graphing it with Grafana was a breeze.

Given all this work I’m happy to confirm what I’d long suspected: some rooms in my house are hot while others are cold.

🧐 What are git notes?

A common use of git notes is tacking metadata onto commits.

Once a commit cements itself in git’s history—that’s it. It’s impossible to amend a commit message buried deep in a repo’s log¹.

But git notes enable you to amend new information about old commits in a special namespace. And they’re capable of so much more.

Notes stow metadata about anything tracked by git—any object: commits, blobs, and trees. All without futzing with the object itself.

You add notes to the latest commit in a repo like this:

git notes add -m 'Acked-by: <tyler@tylercipriani.com>'

And then it shows up in git log:

commit 1ef8b30ab7fc218ccc85c9a6411b1d2dd2925a16
Author: Tyler Cipriani <thcipriani@gmail.com>
Date:   Thu Nov 17 16:51:43 2022 -0700

    Initial commit

    Notes:
        Acked-by: <tyler@tylercipriani.com>

🥾 Git notes in the wild

The git project itself offers an example of git notes in the wild. They link each commit to its discussion on their mailing list.

For example:

commit 00f09d0e4b1826ee0519ea64e919515032966450
Author: <redacted>
Date:   Thu Jan 28 02:05:55 2010 +0100

    bash: support 'git notes' and its subcommands
    ...

Notes (amlog):
    Message-Id: <1264640755-22447-1-git-send-email-szeder@ira.uka.de>

This commit’s notes point intrepid users to the thread where this patch was discussed.

Other folks are using notes for things like:

• Tracking time spent per commit or branch
• Adding review and testing information to git log
• And even fully distributed code review

📦 Storing code reviews and test results in git notes

Here is a plea for all forges: make code review metadata available offline, inside git.

The reviewnotes plugin for Gerrit² is an example of how to do this well. It makes it easy to see who reviewed code in git log:

git fetch origin refs/notes/review:refs/notes/review
git log --show-notes=review

The command above shows me all the standard git log info alongside information about what tests ran and who reviewed the code. All without forcing me into my browser.

commit d1d17908d2a97f057887a4afbd99f6c40be56849
Author: User <user@example.com>
Date:   Sun Mar 27 18:10:51 2022 +0200

    Change the thing

Notes (review):
    Verified+1: SonarQube Bot
    Verified+2: jenkins-bot
    Code-Review+2: Reviewer Human <reviewerhuman@wikimedia.org>
    Submitted-by: jenkins-bot
    Submitted-at: Tue, 14 Jun 2022 21:59:58 +0000
    Reviewed-on: https://gerrit.wikimedia.org/r/c/mediawiki/core/+/774005
    Project: mediawiki/core
    Branch: refs/heads/master

💠 Distributed code review inside git notes

Motivated hackers can knead and extend git notes. Using them as distributed storage for any madcap idea.

Someone at Google cobbled together a full-on code review system teetering atop git notes called git-appraise.

Its authors have declared it a “fully distributed code review”—independent of GitHub, GitLab, or any other code forge.

This system lets you:

• Request review of a change
• Comment on a change
• Review and merge a change

And you can do all this from your local computer, even if GitHub is down.

Plus, it’s equipped with an affectedly unaesthetic web interface, if that’s your thing.

😭 No one uses git notes

Git notes are a pain to use.

And GitHub opted to stop displaying commit notes in 2014 without much explanation.

For commits, you can make viewing and adding notes easier using fancy options in your gitconfig³. But for storing notes about blobs or trees? Forget it. You’d need to be comfortable rooting around in git’s plumbing first.

So, for now: git notes are relegated to obscurity. Forever hamstrung by an obscure and clunky interface and limited adoption—I often forget they’re there.

🗽 Forge independence

Git is a distributed code review system. But much of the value of git repos ends up locked into forges, like GitHub.

Git notes are a path toward an alternative.

Git distributes the history of a piece of code. Git notes could make it possible to distribute the history of an entire project.

Managers are leaders with awkward power 😬

The transition from tech lead to manager is awkward.

You know the work of the team as well as anyone.

But moving to management grants you special powers—all new and unfamiliar:

• You’ll set team goals and vision for the future
• You get to make hiring decisions
• You hold a budget
• You organize special events (and maybe day-to-day events, depending on the support you have)
• You get to talk to the organization’s leadership more often than most on your team

These are superpowers. You should relish these opportunities—you’re empowered to contribute to the team like no one else can.

But your new powers may leave your team uneasy. And if you fail to reckon with this new power imbalance, you risk alienating people.

Never make folks worry about their livelihood 😟

The second you became their manager you forfeited the right to joke around in any capacity about their employment at the company.

– Stay SaaSy

You can hire, and you can fire. This Sword of Damocles now dangles over your relationships as a manager.

“Oh, what’s the worst that can happen? We all get fired?” has ceased to be light-hearted banter.

Folks might laugh, but it leaves lingering doubt. And doubts chip away at the trust teams need to do their job.

Contentless pings from managers are scary 😱

It may seem trivial, but asking your question before getting that initial salutatory reply also allows for asynchronous communication.

– no hello

Now that you’re a manager, your contentless pings have transformed from annoying to panic-inducing.

Sure, you should avoid saying nothing but “hi!” to someone in a direct message.

But you should never, ever say something like, “Do you have a minute to jump on a call?” without context.

“Do you have a minute to talk?” from your boss, out of nowhere, immediately sets people’s minds racing.

Is this about my project? Something with the budget? A policy change? A change to my benefits? Am I being fired?

Your manager powers will wreak havoc on people who tend to catastrophize.

You’re the decider ☑️

People expect you to be the decider. Even for small stuff.

Folks may even be unaware they have this expectation.

But it applies to everything from team vision to where we’re eating dinner at the offsite. You can and should delegate decisions, but you can’t abdicate.

Clarity is key 🔑

Clear is kind. Unclear is unkind.

– Brené Brown, Dare to Lead

When you leap from tech lead to manager, you have to learn about people.

And what people need most from you is clarity.

So instead of striving to be liked, or striving to be funny: you should strive to be clear.

The goals of my house lighting

I had the following goals for this project:

• Circadian lighting in all rooms – Bright, blue/white light during the day; dim, red/yellow light after sunset.
• Control by switches – I disdain fiddling with tablets/phones to turn lights on and off. I’d also hoped to avoid an always-on speaker listening to me.
• Automatic – Light should shift temperature and brightness automatically throughout the day.
• Ability to override – I should be able to override the automatic settings quickly with a switch. Sometimes it’s nice to be able to see what you’re doing late at night—circadian rhythm be damned.
• Platform independent – Because hue bulbs are expensive, I need to be able to add to the system over time. Everything from DIY light strips to hue bulbs to random smart bulbs from Alibaba.com should work together.
• Self-hosted – All software should live on my home network and work with only a local network.

The Results

The effects have been subtle but noticeable.

During the day, I’m sharp, and at night I’m ready to sleep.

In the evenings, after the sun sets, the lights dim, and it gets harder to read and work on projects—that’s a feature. It’s a signal that it’s time for bed.

The most significant benefit I’ve noticed is that I can get back to sleep after getting up in the middle of the night—now that I’m no longer blinded by harsh overhead light in the bathroom.

Home Assistant setup

Home Assistant made this possible.

The Circadian lighting component (available via Home Assistant Community Store (HACS)) computes solar noon based on my location and auto-adjusts the brightness of my lights and the color temperature based on the time of day.

I use Zigbee2MQTT to capture events from my switches and send them to Home Assistant over MQTT—I found this easier than adding a Zigbee gateway to Home Assistant directly.

I have automation that allows me to override circadian lighting when I need maximum brightness or when I want the nightlight.

The hardware setup

Lights:

• Hue bulbs – I have a lot of hue bulbs.
  • Some are full-color bulbs, while others do color temperature.
  • Three different form factors—A19 bulbs, GU10s for the Ikea Tidig in our kitchen, and the Edison bulb for our fancy dining room light.
  • These are good light bulbs.
• Taloya smart ceiling light – this is the bathroom light, integrated with Home Assistant via LocalTuya.

Buttons:

• Aqara mini switch – one each for me and my partner for controlling the bedroom lamps.
• MOES Zigbee 4-gang switch – bathroom lights—one button for on/off, one button for bright, one for dim, one for the red nightlight.

Other hardware:

• Conbee II Zigbee Gateway – Handles the incoming Zigbee signals.

TODO: finish lighting

House lighting is never done. I have ideas for my lights that I’m still pondering.

1. SAD office light – I’m lacking an extremely bright office light—this is especially noticeable when winter brings darkness at 4:30pm. I’m pondering building something that I can attach to this system.
2. Hyperion media lighting – Ambiant bias lighting for the TV via Hyperion. This is neat, but it’s a low priority since I don’t watch much TV (and my TV is from 2012, anyway. I’m not fancy).
3. Moar WLED – I added WLED strip lighting over the sink (which works perfectly with Home Assistant), but I need more to brighten up the whole space.