As Dogecoin Core 1.14.6 is about to come out, you may have noticed a flurry of activity for the 1.14.6 milestone, including PR 3035, PR 3043, PR 3044, PR 3046, PR 3047.
“Of course release notes are good,” you may say. “Just… of course!”
Why are they good? Several reasons.
What to Upgrade When You’re Upgrading
The most obvious reason is that you, a noble shibe who runs a node to keep the network healthy, want to know why you should download the new software, back up any wallet, and run the new software. Are you getting shiny new features? Will things run faster and look better? Are costs going down? Is security going up? Is your native language supported more fully in the UI? (Yes to many of these!)
Building and maintaining a community-managed project with full transparency and communication means that everyone who participates should have access to full information. “Upgrade because it’s new” isn’t a good explanation. Even if you can’t or don’t want to read the code to find out what’s changed, you should be able to consent to the changes and understand the differences between the previous version and this version.
Insert Credit to Continue
The latter section of these release notes always includes something really subtle but incredibly important: a list of names/monikers of people who contributed to this release, whether writing code, improving documentation, translating or reviewing translations, et cetera. Without these people, this release wouldn’t have happened now with these improvements at this level of quality.
News is What We Say Is News
In a world where whatever goofy thing some crypto billionaire says on Twitter becomes the subject of a hundred goofy thinkpieces on a thousand crypto blogs, putting out concrete, factual information is essential. I for one am proud that the 1.14.6 release includes features we haven’t seen before in any of the Bitcoin forks in our constellation (Bitcoin, Litecoin, Luckycoin, etc). I’m looking forward to the day one of the related projects cherry-picks one of these features because it’s just too good to ignore.
For that to happen, we have to make a little bit of noise about what we’ve done.
From a selfish perspective, this joins with the previous point: the more we can show off we’re building something interesting and useful, and the more we can brag about all the wonderful contributions from all the wonderful contributors, the more we can encourage those contributors to continue and to attract more contributors.
My (volunteer) job here gets easier the more people participate.
The Future is Where We’ll Spend the Rest of our Lives
Throughout my career, I’ve spent a lot of time asking the questions “What changed, when, and why?”
Sometimes that means skimming through git output (or Subversion or CVS
or…). Oftentimes it’s easier to run perldoc perlhist or look at release
notes.
Some of the best projects I’ve worked on had a mature process where major changes required an update to release notes or changelogs before they could get approval to merge, and that’s something I’d like to consider for subsequent releases. It’s like requiring tests all pass before release versus requiring tests pass for all meaningful changes.
At some point in the future, I expect one of us will look back on these 1.14.x release notes to figure out exactly when we did something, so we can figure out why we did that. Leaving breadcrumbs for ourselves makes that easier.
Okay, but Why Did You Test These Release Note PRs?
“That all makes sense,” you may say. “I read the PRs though and noticed your approval messages said that you tested the code. Did you actually check out the PR locally, rebuild the core, and run all of the tests?”
Yes.
“What?! It’s just text. Why did you do that?”
Back in the day, sometime in the early 2000s, I worked on a compiler/interpreter/programming language project. We spent a lot of time making sure that the program could bootstrap itself. For example, we wrote a lot of documentation in a structured format that we expected tools written in the language to be able to process.
That sounds a little bit weird unless you’ve worked on a system like this, where you can use the system itself to prove that it’s working.
Long story short: I made a change to a small piece of text in a README file.
It seemed innocuous, so I didn’t spent the 10 minutes or so running the entire
test suite to prove things, because why would a one-sentence change in a text
file break things?
It broke things.
It broke things badly.
Now I’m confident that changes to the release notes aren’t used in the same way as internal documentation for the other system, but I’m not confident that I always remember what depends on what.
In other words, if I always run the tests even if I think the change is innocuous, I never have to think hard about whether a change is worth running the tests or not, and I’ll never get it wrong. My default behavior (I sound like a robot writing this!) doesn’t let me get away with the kind of bad laziness that’s bitten me before.
I should write more in the future about the good kind of laziness that helps me not have to think about these things, but that’s a point for a different day.
Okay, but Why Do Other Shibes Care about Process?
Given all of this, the reason we collate these release notes well before a release is, yes, to achieve the outcomes I’ve already described here, but also to give the community a chance to help us make our work better.
Even if you don’t want to or cannot write code or run tests, you can review the release notes before the release and ask questions. “Why do I care about $X?” is a good comment. So is “What does $Y mean?” is another. I particularly like “Why are there two Mishas?”
The answer, of course, is that Misha contains multitudes.
If there’s a theme hidden in all of this discussion about a single text file, it should be this: getting all of this communication is difficult and time consuming. It represents a lot of work, and it has a lot of value. Contributions help a lot, and we’re trying to make it really easy for lots of shibes to see what’s going on, review it, and ask questions and make suggestions for improvements.
With all of the PRs already merged, you can see what the process is trying to accomplish, and how this release is better for all of the collaboration and cooperation.
If I can communicate anything with these blog posts, it’s that: no one of us could do this on our own. Together, we’re building something better.
