Advent of Ruby Changelog: Week 1

A diary of preparing Ruby 3.3's annotated changelog.

Every year since 2018, I write the annotated Ruby Changelog.

The work on the changelog, for me, includes:

• Writing (and investigating) a detailed explanation of each feature's reasons, quirks, and details of usage;

• Trying this feature on the most recent Ruby versions to better understand the details (sometimes, finding the bugs);

• Checking the feature docs to see if it is covered properly and fixing them, if necessary.

The process of preparation for the new version also includes:

• Checking docs inconsistencies and lacks gathered through the year, and fixing them.

• Checking the status of feature requests gathered through the year, and understanding where we are standing on the Ruby Evolution.

TBH, most of this activity (keeping an eye on docs, tracking new features and discussions) could be more efficiently done as a constant activity, and a couple of years ago, I planned to switch to this mode, but then you-know-what happened, and only now I’ve found some time for my Ruby activities, so *shrugs noncommittally*.

I already covered what I am doing and thinking when working on the changelog from the bird-eye view in a series of articles: three in Jan 2022 (“What you can learn by merely writing a programming language changelog”, “Following the programming language evolution, and taking it personally”, “Programming language evolution: with all that, we are still flying”) and a Feb 2023 addendum “Participating in programming language’s evolution during interesting times”.

This year, though, I want to cover it in a day-by-day diary (which would also incentivize me to do it in day-by-day small chunks, not leave for the last moment and then be criminally late after the release).

At the moment of writing this paragraph, I am not sure whether I’ll publish the diary as a whole in the end or in several weekly installations (or there wouldn’t be a thing to publish at all). We’ll see.

…And at the moment of writing this paragraph (a week later), I decided to, indeed, publish parts of the diary every week. It also turned out that there are a lot of things to say about the process—so many, in fact, that while each day’s entry is quite short, seven of them are longer than a decent blog post (or Substack email size limit).

So, I’ll try to do a weekly round-up post with links to more detailed entries for those who are interested.

Here are diary entries for the first week:

• Day 1, where I explain my usual process and start by looking into this year’s NEWS.md file in Ruby repo. From first sight, it looks like this year’s release has very few changes, and even less so to analyze and describe in detail, so it might not be the best year to showcase “what it takes.” (Spoiler alert: this was a false feeling!)

• Day 2, where I go into more details about converting terse official NEWS.md into my wordy changelog sections, and a lot of uncertainties to think of in the process.

• Day 3, where I do an initial pass through all the new/changed feature docs and uncover many small enhancement possibilities to put in my December TODO.

• Day 4, where I start to look into the features that I need to understand better before explaining them, and, in particular, Module#set_temporary_name.

• Day 5, where I look into a few more new features: a new WeakKeyMap class, and Thread::Queue#freeze method, and demonstrate how I reflect upon uncertainties in my own understanding and possible documentation problems I’d like to fix.

• Day 6 & day 7, where I am diving head-first into enhancing docs for a new class ObjectSpace::WeakKeyMap and its older cousin ObjectSpace::WeakMap, and end with submitting a PR to Ruby core and finally writing some drafty texts for the changelog.

To be continued…

Subscribe to my Substack, or follow me on Twitter.

A weekly postcard from Ukraine

Please read this too. This is your weekly mid-text reminder that I am a living person from Ukraine, and a bit of useful related information.

One news item. The body of a 15-year-old Ukrainian girl, who had been missing for 1,5 years following the Russian invasion, was discovered in Belarus.

One piece of context. December 6 was the Day of the Armed Forces of Ukraine. There were many excellent materials published for the day, but I ask you to read this short graphic story/conversation with a wonderful woman from my home city Kharkiv, an LGBT activist and combat medic since summer 2022.

One fundraiser. Please help this international fundraiser held by Ukrainian combat veteran for desperately needed drones.

One plea. Please read this, and consider helping us by contacting your representative.