Tyler Cipriani: blog

Writing raft

2022-12-24T02:34:00Z

✏️⚡🔪
The club that’s write or die.

If you want to be a writer, you must do two things above all others: read a lot and write a lot.

– Stephen King, “On Writing”

In 2022, I made a Ulysses pact to force myself to write—either write or feel the white-hot shame of (temporary) banishment.

And it worked.

I wrote more blog posts in 2022 than in any previous year—more than the last three years combined.

I eked out two blog posts a month, every month, for the whole of last year. And I owe much of my success to my write-or-die crew—the writing raft.

⛵ 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:

You must publish a blog post by the end of the month.
If you do not publish on time, you’re out of the club (for a month).
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

Home temperature monitoring on the cheap

2022-12-01T03:26:08Z

One accurate measurement is worth a thousand expert opinions

– Grace Hopper

As I meandered around our new house, it was apparent some rooms were sweltering, others were freezing, and the thermostat was lying about everything.

I could feel it.

But I felt compelled to measure it. I was struck by the need to know:

The temperature of each room
How it changed throughout the day
And how to monitor changes over time

And I fulfilled my weird compulsion with a few simple tools:

Cheap temperature and humidity sensors from Home Depot
Home Assistant
The original internet of things protocol: radio.

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:

SHT30 temperature/humidity sensor	$1
WeMos esp8266	$5
D1Mini OLED screen	$2
Shipping	~$2
A month of waiting for shipping	priceless

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:

a systemd unit running rtl_433 with syslog output over UDP: rtl_433 -F syslog:127.0.0.1:1433
a systemd unit relaying and filtering syslog output to MQTT (based on this upstream example)
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.

Git Notes: git's coolest, most unloved feature

2022-11-27T20:11:22Z

the short of it is: they’re cool for appending notes from automated systems (like ticket or build systems) but not really for having interactive conversations with other developers (at least not yet)

– Scott Chacon, GitHub.blog, Aug. 2010

Git notes are almost a secret.

They’re buried by their own distressing usability.

But git notes are continually rediscovered by engineers trying to stash metadata inside git.

Git notes are powerful tools. And they could solve so many problems—if only they were better known and easier to use.

🧐 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.

Without having to endure the perils of a force push, anyway.↩︎
The code review system used for a couple of bigish projects.↩︎

Noteably by automagically fetching notes and displaying them in git log via:

$ git config --add \
remote.origin.fetch \
'+refs/notes/*:refs/notes/*'
$ git config \
notes.displayRef \
'refs/notes/*'

↩︎

A tech lead guide to manager powers 🧙

2022-11-01T04:14:29Z

It took me two years as a manager to reach the “leadership is lonely” phase.

– Will Larson, An Elegant Puzzle

When you jump from tech lead to manager: things change.

Your deep understanding of the system evaporates and becomes shallow. You’ll stop writing all the critical code. Your focus will shift.

But for me the weirdest change was everyone treating me like a manager all the time.

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.

f.lux, but for your house

2022-10-18T21:35:21Z

Artificial lighting is omnipresent in contemporary society with disruptive consequences for human sleep

– Sarah L Chellappa, https://doi.org/10.1093/sleep/zsaa214

Light messes with my sleep, mood, and alertness.

My house lights should auto-adjust themselves—like f.lux or redshift on my laptop:

🌞 White/Blue, bright light during the day
🌛 Red/Yellow, dim light at night

I was worried that getting this to work for my whole house meant endless fiddling with “smart” devices.

But Home Assistant papered over the vendor and hardware woes and made setup simple.

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.

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.
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).
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.