Repository: node
Issue: proposal: new release blog
Labels: discuss,meta

## 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`:

![image](https://user-images.githubusercontent.com/924465/61977890-860ce480-afa4-11e9-91cb-6072e6c78faa.png)

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](https://github.com/nodejs/release) 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](https://nodejs.org/en/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](https://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](https://github.com/nodejs/node/pull/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:
```js
// 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`:
```json
{
  "exports": {
    "./map": "./lib/operators/map.js"
  }
}
```
Then a consumer could instead write:
```js
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:
```json
{
  "exports": {
    "./operators/": "./lib/operators/"
  }
}
```
The above works a bit like [import maps](https://github.com/WICG/import-maps#packages-via-trailing-slashes**), where a consumer can now write:
```js
// 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](https://github.com/jkrems/proposal-pkg-exports/).


[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?]