proposal: new release blog

[boneskull]

TL;DR

To increase visibility around new features & fixes, I propose a creating a user-focused, human-readable blog which aims to answer not just what was released, but also “who might find this important?” and “how do I use this?”

Problem

Node.js’ official “blog” is an HTML conversion of CHANGELOG.md:

As you can see, the text is terse and details are usually scant.

For example, what is response.writableFinished for? Who would want to use this feature? And for those who do, how do they use this feature?

The entries above are tagged notable-change—implying notability—which is why they appear at the beginning of the post. This is a useful way to separate the changes that a user might care about from the changes that a user likely won’t care about. However, the mere presence of the label is insufficient; it does not and cannot contain context nor rationale. In practice, the list above is a mishmash of changes, and it’s difficult for a casual observer (or any observer, really) to sift out what’s personally relevant.

As a result, changes often get missed by Node.js users. Proliferation of new feature adoption, for instance, relies mainly on word-of-mouth and community blog posts.

Node.js could better serve its userbase by highlighting new features, breaking changes, and fixes, and doing so in an “official” capacity.

A Proposed Solution

At present time, while we may be able to automate providing “more” information to users (via expanded commit message requirements, metadata, etc.), we should not go this route. Crucially, a script will lack information about the relative importance of two different changes. This impacts how an editor chooses to organize a post—for example, by presenting change A before change B; or grouping related changes across unrelated subsystems.

Given sufficient writing skills, a human editor will produce more well-organized, relevant, cohesive and relatable articles than a script.

Instead, producing a post must be a joint effort between collaborators and the editor(s).
Much/most/less-than-none of the necessary information already exists around the PR and its referenced issue(s). But in the spirit of efficiency, we need to consolidate it.

Of collaborators, I’d like to ask this:

Because the editor of the post cannot possibly know every detail of every change...

When tagging a PR notable-change—whether or not you are the author—please update the PR description (this could also happen when creating the PR) with this information (if it does not already exist):

• Which users might care about this. Do they deploy Node.js? Do they build tools? Do they compile native modules? Are they SREs? Do they perform post-mortem debugging? Anything here is better than nothing, even if incomplete.
  If you’re unable to answer this question, it might be that the change is not notable.
• Motivation. …but why?
• Example code (if appropriate). If example usage can be easily derived from a test, please link to it with line numbers—don’t make the editor search for it.
• Dependency Upgrade? If this is an upgrade of an upstream package, provide a link to the release in that package’s release notes or CHANGELOG. If there’s a specific fix or feature Node.js is looking to pull in, mention it.
• Breaking Changes! Provide workarounds or migration path—anything that might help those affected.
• Who are you? Add your GitHub username indicating that you’ve added this information, so we know who to talk to if we have questions about what you’ve written.

In lieu of any of the above, a link to the relevant information is acceptable, but if it’s not a wall of text, please copy/paste so editors don't have to hunt around so much.

We can also provide a template for this information. Maybe put it in a GitHub PR template? Might be easier to knock all this stuff out at creation time, depending on how much the PR changes before merging.

Don’t worry! You don’t have to be Shakespeare. Nobody is expecting perfect spelling, grammar, or even complete sentences. You aren’t writing for a huge audience—you’re writing for the editors of the blog post. Focus on getting your point across, and editors can ask questions if needed.

Of editor(s):

• Make sure you understand what’s going in to the next release. If there are notable changes missing information, ask for it (nicely).
• You will edit, distill, and likely just rewrite what collaborators have written. It’s your responsibility to put the pieces together in a way that makes sense.
• Be prepared for a crash course about Node.js’ many subsystems that you may be unfamiliar with.
• Ask questions if you don’t understand. If you don’t understand, it’s highly likely somebody else doesn’t understand.
• Collaborate with the release team if the need arises. I’m not sure why it would, necessarily, but they might have more information than the obvious about what’s going into the next release.
• Decide with other editors (if there are any) on the formatting and structure of the posts.
• You may choose whether or not to omit a change from the post if you are unconvinced it’s “notable.” Use your judgement, but explain your reasoning to the collaborator(s).
• Field any followup questions/comments on the post; if you don’t know the answers, you can choose to point them to someone who can help the commenter, or offer to “find out” and get back to the commenter at a later time.
• Work with [somebody] to ensure the blog post makes the rounds on social media.
• Settle on a cadence. Within a few days after a minor release? A week? What of patch releases and security fixes? How much time do we have before the final change targets a release before that release is cut?
• You aren’t Shakespeare either, but you are confident in your written English.
• Get somebody to review the posts before publishing—unless nobody wants to help you, then just publish out of spite.

Where do we post these articles?

We could:

1. Use the existing blog, or
2. Create a new blog somewhere on nodejs.org, or
3. Not use nodejs.org at all

I’d say go with option 1 until somebody complains that we’re polluting their feed of Node.js release notes with our dreck.

At minimum, we should syndicate these posts to dev.to. That’s where the “engagement” is going to happen, unless we set up a “proper” blogging platform elsewhere (and that takes more time/energy, and this is already a big ask).

Who writes them?

I’ll start, but I could absolutely use help, because it’s probably going to be a lot of work. And probably more work than I think it’s going to be.

I will need an “official” Node.js account on dev.to (if one does not already exist), or be added to a team, or however that works.

Example Post Content

I’m not going to write out an entire post right now, but here’s how I, as a user, would want to learn about #28568 (note that I'm skipping some use cases, and apologies to @guybedford if I get this wrong):

---

New Feature: Package Exports (EXPERIMENTAL)

Summary

An exports property can be added to package.json in which a package author can provide aliases to internal modules.

Who’s it’s For

Primarily library authors

Description

Some packages have a larger-than-average API surface. For these, like rxjs or lodash, a consumer may want to “reach in” to a package and pull out only what they need; or this may be the recommended way (e.g., rxjs/operators). For example:

// everything exported via some-package's "main" module gets loaded 
const {map} = require('some-package').operators;
// but all we wanted was map(), so we can do this instead
const map = require('some-package/lib/operators/map.js');

You may have noticed that the second form requires the consumer to understand the internal directory structure of some-package. Package Exports aims to provide an abstraction to hide these implementation details from the consumer. If some-package had the following in its package.json:

{
  "exports": {
    "./map": "./lib/operators/map.js"
  }
}

Then a consumer could instead write:

const map = require('some-package/map');

Before this change, libraries like rxjs would provide this behavior by creating “stub” module aliases; for example, when you require('rxjs/operators'), you are actually loading node_modules/rxjs/operators/index.js, which manually re-exports every module within node_modules/rxjs/internal/operators/.
rxjs could choose to eliminate its operators folder entirely using Package Exports.

Use with ESM

When used with ES modules, an exports entry can point to a directory:

{
  "exports": {
    "./operators/": "./lib/operators/"
  }
}

The above works a bit like import maps, where a consumer can now write:

// node_modules/some-package/lib/operators/map.js
import map from 'some-package/operators';

For more information, check out the full text of the proposal.

[Trivial edit by @Trott to fix a broken link. Hey, now that GitHub keeps edit history, maybe we should remove the requirement for these comments?]

[addaleax]

This is somewhat related (but feel free to say “it’s not relevant”), but I suggested to include addaleax@b16ed10 in the 12.0.0 changelog, i.e. calling out “big” notable changes as a separate category. Do you feel we should also do something like that? (I’m still a fan of it.)

[Trott]

I'm 💯 on this. Making it happen and keeping it going consistently will be the challenge. But if there are people willing to step up and do the work, then we absolutely should require this.

It has pros and cons, but maybe each notable change in the changelog can have a link to a wiki* page or something that has all the information. That has the advantage of people being able to come along and improve it over time. So I might write one up. And a user reading it gets stuck on something because I left out a crucial piece of information. That user can add it to help out the next person.

* Non-GitHub wiki perhaps, unless our ability to monitor and moderate the wiki is better than it used to be. I think previous challenges there were both technical and social.

[boneskull]

@addaleax

This is somewhat related (but feel free to say “it’s not relevant”), but I suggested to include addaleax/node@b16ed10 in the 12.0.0 changelog, i.e. calling out “big” notable changes as a separate category. Do you feel we should also do something like that? (I’m still a fan of it.)

Something that seems reasonable to help automate the organization of the release notes, but doesn't necessarily impact this proposal, other than to maybe say that these "notable notable" changes must have all of the requested information.

@Trott

A wiki sounds like a better way to organize stuff than "update the description", given that the wiki tracks revision history (oh wait, apparently it does that in comments now too? still, may be better organized). We may be able to automate the creation of those pages and pre-fill it with boilerplate as well...

I don't see a reason not to use the GH wiki--if we lock it down to collaborators and use it only for this purpose.

[boneskull]

cc @nodejs/collaborators, since this will impact you (yes, you)

[jkrems]

I really like the idea and I think the style of the example post is great! :)

P.S.: And your write-up on exports was also very valuable as a "paraphrasing exercise" to uncover where we need to be better at communication how exports works. ^^ I'd love to take your post as the basis for a future write-up on exports once it's closer to shipping if that's okay with you.

[antsmartian]

Definitely +1. I like the idea!

[boneskull]

@jkrems

P.S.: And your write-up on exports was also very valuable as a "paraphrasing exercise" to uncover where we need to be better at communication how exports works. ^^ I'd love to take your post as the basis for a future write-up on exports once it's closer to shipping if that's okay with you.

That's very generous of you 😄

While that sort of detail--as found in the project proposal page--is absolutely necessary, part of the job of the editor(s) must be to distill any change into what an average Node.js developer (not a "collaborator") is going to understand and want to read.

[ryzokuken]

@BridgeAR has a lot of amazing opinions on this.

[jkrems]

While that sort of detail--as found in the project proposal page--is absolutely necessary, part of the job of the editor(s) must be to distill any change into what an average Node.js developer (not a "collaborator") is going to understand and want to read.

Just to clarify - I wasn't talking about adding all the fine details. More a general proof-reading. E.g. in the example above there are some misleading and/or misunderstood bits that we should clean up before it would be published. Totally agreed that we shouldn't publish a spec text for consumption by the general public. :)

[boneskull]

@jkrems this is also why I can’t write these without help from the PR authors; I’m bound to get something wrong if I have to do it all myself—then I’d need to send the text for review ...

[jkrems]

@boneskull I wasn't criticizing your write-up, it was a great example of how such a post could look like. I was volunteering (as the PR author) to write or help write one of these if we want to cover exports.

[boneskull]

Update:

Thanks to Rachel Romoff, we have an official organization on dev.to with which I can post.

I'm going to want to automate something to ask authors for more information. "Please fill out this template..."

The "nagbot" itself can be implemented via GH action in response to a label being added to a PR. It'd be good to get this info sooner rather than later, so prefer this instead of a post-commit action.

[mhdawson]

I think the information will be very useful, as @Trott mentions only challenge might be making sure we have people to support it but it is great to try and see if we can make that happen.