Nock: 11.x release plan

[paulmelnikow]

About 12 hours ago, Node 6 reached EOL! 🍾

Should we plan to release 11.x?

I've been testing the betas in all my projects and so far haven't run into problems. At one point I reached out to some of the projects that wrap nock and asked them to test on the betas. There are a lot of people using this library, though. Getting some more feedback might result in a smoother release.

Would it be helpful to ship 11.0.0-rc.1 and announce widely that we want folks to test it?

---

Pending issues:

• [x] ~#1428 (PR needs work)~ #1588
• [x] #1042 (no change was needed)
• [x] #1564 ~(ready to merge)~
• [x] Decide whether to proceed with #1596 (merged)
• [x] Writing the release notes / upgrade guide
• [ ] Do we want to schedule a window we publish 11.0.0 as next and ask people to test it?

[gr2m]

Yeah why not. In my experience not many people test with RCs, but some do. And if 11 has bugs, we can at least say we did all the things to let people find these bugs.

I think what I’d to though is just release v11.0.0 with @next and give that a week for people to test

[paulmelnikow]

That sounds good to me.

[paulmelnikow]

Let's hold on shipping 11.0.0 momentarily, until we resolve the discussion at https://github.com/nock/nock/pull/1521#discussion_r280273915. It might trigger a breaking change, albeit an obscure one.

[gr2m]

roger that 👍

[mgcrea]

Would be awesome if we could add support for async replies since we're bumping a major. Eg:

nock(API_ENDPOINT)
  .get('/users')
  .query(true)
  .reply(
    200,
    async (uri, requestBody) => {
      const buffer = await readFile(`${FIXTURES_PATH}/fixture_${dynamicFixtureId}.json`);
      return JSON.parse(buffer.toString('utf8'));
    },
    {'Content-Type': 'application/json'}
  );

I guess a simple Promise.resolve() would be good enough.

EDIT: had a look at the source code and it does not look trivial :(

[paulmelnikow]

Replies as promises sounds awesome, though I _think_ it can be done without a breaking change. Could you open a new issue? Extra plus if you want to dig into it. 😉

[paulmelnikow]

Hey all, a couple big Nock-related things on my mind:

1. I've been swamped lately with deadlines from some paid work though I really want to get my sponsorship set up!
2. It would be great to get 11.x shipped soon! I could set aside some time the weekend of June 22–23 to try to do that. The pending issues are:
   
   
   
   • (moved to top post)
   
   

[mastermatt]

To clarify, #1557 (promise based reply functions) probably won't have breaking changes. So it's not a blocker for 11.0?

[paulmelnikow]

Yup, makes sense!

[mastermatt]

Of course, this changes if we decide to go the route of https://github.com/nock/nock/pull/1596.

[paulmelnikow]

Ah, yes. I've added it to the list of pending issues (which I've moved to the top post).

[jsumners]

Is there an ETA on this? I have found that 10.x does not work with Node 12 whereas nock@beta does.

[gr2m]

No need to wait, you can use nock@beta today, it’s very stable. And it’s very helpful for us to have as many people as possible use it before the stable release

[paulmelnikow]

@jsumners Please do update and let us know if you run into issues! We don't have a summary yet of the breaking changes, however when APIs have changed, the readme on the beta branch documents the new APIs.

[jsumners]

I get that, and we may end up doing so, but it's generally not great to use clearly marked "beta" releases in "production" projects. I really don't even like using non-LTS Node, but we are close enough to LTS on that front for it to be acceptable.

[paulmelnikow]

Upgrading early is a (hopefully relatively) small thing you can do to help the project. Getting feedback from a wider audience helps us get the release out.

It's up to you though! Understand where you're coming from. Unfortunately it's not quite ready yet.

[gr2m]

It usually it’s only used for testing, not in production, so I don’t think there is much risk to it.

[jsumners]

Upgrading early is a (hopefully relatively) small thing you can do to help the project. Getting feedback from a wider audience helps us get the release out.

Yep, I understand. Not trying to demand anything here. Just prodding for a bit of info.

It usually it’s only used for testing, not in production, so I don’t think there is much risk to it.

Testing begets production releases.

[paulmelnikow]

I was thinking of starting on the upgrade guide. Is there anything conventional-changelog can do to make this easier, or is the easiest way to comb through the commits?

Added: Should the upgrade guide mention all the changes in functionality, or should it focus on breaking changes and fixes that are likely to require code changes?

If the upgrade guide focuses on the things that will need changing, I think it would also be good to copy edit the full changelog so there's a single list of all the things that have changed. I think the auto-generated list would be a good start, though I think it could be useful to copy-edit it so it's easy to skim through.

[gr2m]

Once we fill good code-wise, we can publish 11.0.0 to the @next dist-tag channel. It will create a pre-release on GitHub based on the commits. Then we can edit the release notes and add a migration path. Once that’s all ready, we release to @latest.

Publishing to @next should be as simple as merging beta to the next branch, semantic-release should take care of it. Publishing to @latest should be as simple as merging into master. This is still a beta feature of semantic-release so maybe it’s better if I do that and look out for problems

[paulmelnikow]

I think we’re in good shape code-wise. Seems like we may as well get that process started!

One question, will we be able to publish a new 11.0.0 when it’s time to release to latest, or will it end up being eg 11.0.2?

Added: I kinda spaced; there are a couple open PRs, one of which is a breaking change that we should definitely wrap up first.

[gr2m]

One question, will we be able to publish a new 11.0.0 when it’s time to release to latest, or will it end up being eg 11.0.2?

It’s gonna be the same version, next branch will just publish to to the @next dist-tag, but without any special version name such as beta does.

@mastermatt any objections against release 11.0.0 to @next?

[mastermatt]

@gr2m if you can give me a day or two, I'd like to get #1596 into beta because it has a breaking change.

[gr2m]

Sure, there is no rush! I also run into some failed test with Octokit and I want to make sure these are intentional breaking changes and not bugs that we missed.

[mastermatt]

At this point I think v11 is feature complete and ready to cut. @gr2m @paulmelnikow ?

[gr2m]

Sorry my laptop broke shortly after my last message, I still don't have it back. I couldn't finish my investigation on v11 with Octokit.

We can merge it into a next branch, so it will release v11.0.0, but using the @next dist-tag. That will make it simple enough for folks to install and signal it's stable enough to use now. I can do that tomorrow

[paulmelnikow]

I started working on the upgrade guide, though it's not finished, and it sounds like it's fine to add that after the initial v11.0.0 release is shipped.

Besides reaching out to channels asking people to try the new release, I think it would be a good idea to publicize a target date for the @latest release. Maybe a month would be good?

Lastly, I wonder about opening PRs ourselves on a couple popular projects to make sure we have a good base of coverage. If we each do two projects that'd be 6-8 which should give us a wide surface. This is less about finding bugs, and more about having people test the upgrade guide before everyone is suddenly hit with thousands of Dependabot and Greenkeeper PRs.

[gr2m]

Sounds good to me 👍 I'll update Octokit & nock myself.

I'll get the @next release going then

[gr2m]

There we go: https://github.com/nock/nock/releases/tag/v11.0.0%40next

nock creates a v11.0.0@next tag/release. When merged to master, it will create another tag/release without the @next suffix. It's currently being discussed at semantic-release if the suffix is necessary but that's what we have today :)

[mastermatt]

@paulmelnikow do you have thoughts on which projects it might be good for us to open PRs on?
I looked into a couple of the more popular projects that use Nock, eg supertest, bower, etc. but the ones I looked at had trivial use cases.

[paulmelnikow]

Hmm, no I guess I'd have to look at them a bit. I know @RichardLitt assembled a list at one point – wonder if we can pick some good ones out of that?

I pushed a branch with my WIP on release notes: https://github.com/nock/nock/compare/release-notes If anyone wants to jump in and work on that, would be great. I'll be able to work on it a bit on Thursday.

[RichardLitt]

Hmm, no I guess I'd have to look at them a bit. I know @RichardLitt assembled a list at one point – wonder if we can pick some good ones out of that?

Hmm. I don't remember doing that 😅. Would probably be worth doing again.

[paulmelnikow]

Ha! I thought you wrote some software that looked on GitHub and made a list of companies. Maybe I'm misremembering!

[RichardLitt]

Currently working on a tool to do that. I'll report back.

[mastermatt]

I've opened a PR against google-api-nodejs-client and I'm currently working on one for node-newrelic.

[mastermatt]

I've added to the release notes as well. Should that branch just be opened as a PR, so comments can be made against it?

[paulmelnikow]

I made a round of copy edits (some of them deep) and opened #1671.

@mastermatt did you get the rest of the way through the API changes?

If everything is there I think the only other thing I'd like to do is add a few sentences of summary about the release, and update the order so we're putting the most important stuff first.

[paulmelnikow]

Re popular projects, I've picked a few higher-starred projects from https://github.com/nock/nock/network/dependents and done the upgrade. Either the tests passed without changes, or I was unable to fully verify the update because the tests weren't passing locally beforehand.

Those projects were:

• apollo-server
• netlify/cli
• sentry-testkit

I did not open any PRs.

We tend to spend a lot of time working on corner cases of Nock. It's helpful to remember that a lot of uses of the library are very straightforward. (This is what @mastermatt was saying in https://github.com/nock/nock/issues/1516#issuecomment-520651272.)

[gr2m]

I've updated octokit/rest.js and there were no problems:
https://github.com/octokit/rest.js/pull/1444

[gr2m]

fyi @nock was enabled for Actions v2 :)

[paulmelnikow]

… update the order so we're putting the most important stuff first.

This is done.

@mastermatt did you get the rest of the way through the API changes?

@mastermatt Can you clarify?

[mastermatt]

My changes to the release notes included a pass from May 9, where @paulmelnikow left off, to current. I focused heavily on breaking changes, might be nice to also include new features toward the end.

[paulmelnikow]

add a few sentences of summary about the release

This is done.

So, all that's left is to possibly add some information about new features!

[paulmelnikow]

I've updated #1671 with a summary of the new features.

@mastermatt @gr2m @RichardLitt would you be up for giving it a last set of eyes?

[paulmelnikow]

A couple housekeeping bits: let's post an announcement in #1268. Was also thinking I'd open an issue with an announcement and pin it. It'd be a good place for any discussion related to the upgrade guide.

[mastermatt]

Should this issue be closed?

[gr2m]

I think the announcement in #1268 is still outstanding? Good idea on the pinned issue, too 👍

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. We try to do our best, but nock is maintained by volunteers and there is only so much we can do at a time. Thank you for your contributions.