Breaking changes: scoping the npm package and dropping Node.js 8 support (RFC for BCD 2.0)

[ddbeck]

Summary

BCD should make a couple of breaking changes:

• move the package into the @mdn scope on npm (i.e., rename mdn-browser-compat-data to @mdn/browser-compat-data)
• drop support for Node.js 8

To ease this change, I want to provide a brief transition period, when both packages are published concurrently.

This issue proposes a process for making these changes in a way that makes upgrading as least disruptive as possible. I've tried to be comprehensive in my approach, but I'm sure I've overlooked some things. I invite you to give feedback on this process, so that we can make sure the process goes as smoothly as possible. Thank you!

Background

To better manage MDN's packages on npm, the MDN dev team has decided to create an MDN organization on npm and move MDN's packages into the @mdn scope. This means that, in the future, releases of BCD would need to be under the name @mdn/browser-compat-data instead of mdn-browser-compat-data.

I support this decision, but I want to minimize disruption to MDN's consumers as a consequence of breaking changes, which this is. Below, I've written up a process to start releasing BCD under a new package name and to deprecate the old name.

Since renaming the package is a breaking change, I intend to roll up #5931—dropping support for Node.js 8, itself a breaking change—into this process as well. If we must break things, I think we should combine those hassles into one upgrade process.

Consequences

These things will change as a consequence of this process:

• If you're already consuming BCD, then you'll need to modify your package.json file and require calls. In other words, you'll need to run npm install @mdn/browser-compat-data and change replace require("mdn-browser-compat-data") with require("@mdn/browser-compat-data"). Upgrade documentation will be provided.
• @mdn/browser-compat-data will become the canonical package name (see timeline, below).
• mdn-browser-compat-data will become deprecated (see timeline, below).
• BCD will drop support for Node.js v8. If you have not already upgraded to Node.js 10 or later, then you'll need to upgrade to continue getting BCD data updates.

Lots of other things will not change as a consequence of this process: the repo name or location, the schema, project governance, ownership, data guidelines, license, etc.

Procedure

Starting on the day of the next release of BCD:

1. Link to this issue in the next two releases of BCD, allowing for at least two weeks for comment on this process. BCD releases will continue as usual (though work may begin on later steps in this process).

2. Start releasing @mdn/browser-compat-data and mdn-browser-compat-data concurrently.

   The first production release of @mdn/browser-compat-data will be version 2.0.0 (continuing the version history from the mdn- package) and include the breaking change in support for old Node.js versions.

   The release notes will mention this issue (and, when applicable, any deprecation notices to expect in future releases). Documentation (such as the README) will be updated to direct readers to the new package name.

3. Release mdn-browser-compat-data version 1.1.0 with deprecation warnings for the package name change and dropping support for Node 8. We'd use both require-time console warnings and npm deprecate metadata to alert users of the change.

4. Continue to release @mdn/browser-compat-data and mdn-browser-compat-data concurrently for some weeks.

5. Issue a final mdn-browser-compat-data release and mark all previous versions as deprecated.

6. Continue development on BCD via @mdn/browser-compat-data only.

Timeline

This is a proposed timeline, subject to change (both as a product of the comment period and or any unforeseen delays).

Week	Description	Release mdn-	Release @mdn/
1	Comment period begins and development for deprecation notices begins	✅	❌
2		✅	❌
3	Concurrent releases begin (can be extended for additional comment)	✅	✅
4	Release mdn-browser-compat-data 1.1.0 with deprecation notices	✅	✅
5		✅	✅
6	Final concurrent release; all previous releases of mdn- are deprecated	✅	✅
7+	Only @mdn package is released	❌	✅

Tasks

Some things we'll definitely have to do to satisfy this project. There's probably more!

• Respond to feedback on this process
• Branch for @mdn package scope
• Develop deprecation code
• Write upgrade docs
• Deprecate previous versions

Closing notes

If you've read this far, thank you! I understand this is disruptive and I'm grateful for your help on making it better and making it work.

[ddbeck]

@Elchi3 @Fyrd @vinyldarkscratch @foolip @sideshowbarker @jpmedley I'd love to have your feedback and for you to reach out to anyone else you think might be significantly affected by this. Thank you!

[sideshowbarker]

There’s nothing I personally have deployed or maintain which would be affected by this — but I can thing which comes to mind that I can imagine might be affected is @connorshea’s https://github.com/connorshea/mdn-compat-data-explorer

[foolip]

I depend on the existing package in a few places, but could easily migrate, even without a transition period. So no special requirements on my side.

Warning: Randomizing question/suggestion ahead.

On #5931, I wonder what we consider the public API of the npm package to be? When one does require('mdn-browser-compat-data'), index.js will run some code and return an object.

If that returned object is the entire public API that needs to be kept stable, I wonder if we could simplify the requirements on consumers by having a build step where the published package is just a big JSON file, and the few lines of JS to load them?

[ddbeck]

@foolip wrote:

If that returned object is the entire public API that needs to be kept stable, I wonder if we could simplify the requirements on consumers by having a build step where the published package is just a big JSON file, and the few lines of JS to load them?

Yes, I have considered this, though not in the context of this project. There's some distinct benefits of doing it that way. For instance, right now, you can't use BCD in the browser (with webpack or something) because it "requires" the file system (I ran into this problem just yesterday). If we built the full data tree into a JS module, then we could make support for BCD a bit more broad. I think this is an idea with some appeal.

(I've also pitched the idea of exposing a more interesting API to consumers in #4106, though I don't think anything above precludes that.)

Unfortunately, that might not actually help with the Node engine dependency thing. We tried to upgrade the Node version in the past to upgrade some our dev dependencies. npm complains when we try to install dev dependencies with a higher Node version than our supported version. As far as I know, there's no way to specify different Node versions for usage and development. So if we want to upgrade our dev dependencies (e.g., Prettier), we're going to have to make a breaking change at some point and it may as well be now.

[connorshea]

I haven't been maintaining the browser-compat-data-explorer and will probably drop support for it regardless of this change, so no worries from me.

[queengooborg]

I'm in full support of this decision, and I think combining the NodeJS v8 deprecation in the same steps is perfect, since we're already doing a big migration.

[Elchi3]

(I already said this, but now publicly). I support this plan, too!
I think this proposed update to BCD 2.0 comes with minimal work for all the data consumers, but it comes with some work, so it is a great exercise for the maintainers of this repo and all consumers to establish a process that works for everyone involved. In BCD 3.0 and following, we can then imagine to work on larger breaking changes, such as changes to the public API etc. and take into account the feedback from the 2.0 release communication and so on.

That said, I think these people would also welcome a ping about the changes:

• VS Code and WebHint maintainers (happy to reach out there and find out who exactly is responsible).
• The Firefox addons team (opening an issue on https://github.com/mozilla/addons-linter should work nicely)
• The Firefox devtools team (Honza seems to be a good person, see https://bugzilla.mozilla.org/show_bug.cgi?id=1662653)

[Fyrd]

Sounds good to me too, thanks for notifying me!

[ddbeck]

That said, I think these people would also welcome a ping about the changes:

• VS Code and WebHint maintainers (happy to reach out there and find out who exactly is responsible).

@Elchi3 If you wouldn't mind reaching out, I'd appreciate it. I don't know who to talk to on those projects, unfortunately.

• The Firefox addons team (opening an issue on https://github.com/mozilla/addons-linter should work nicely)

Done!

• The Firefox devtools team (Honza seems to be a good person, see https://bugzilla.mozilla.org/show_bug.cgi?id=1662653)

Done!

[queengooborg]

Hey @codexp and @shinepd -- wanted to ping you about this issue and our upcoming plans to drop Node v8 support soon (I remember you had issues when 1.0.13 was released), and see if you had any feedback?

[connorshea]

@ddbeck for VS Code I think it'd be @octref

[octref]

I have left Microsoft. /cc @aeschli

[aeschli]

I can do the migration for VSCode once the move happend. Thanks for the heads-up!

[ExE-Boss]

This will also need to happen with mdn‑data.

[queengooborg]

@ExE-Boss, can you open an issue there?

[ExE-Boss]

@vinyldarkscratch
Done: mdn/data#427

[ddbeck]

The first @mdn/browser-compat-data release (@2.0.0) is now available. https://github.com/mdn/browser-compat-data/releases/tag/v2.0.0 (alongside v1.0.39). In the next week, I plan to write upgrade docs and prep deprecation notices for the terminal v1.x releases.

[ddbeck]

Today, I released mdn-browser-compat-data v1.1.0, which includes deprecation warnings and links to upgrade instructions.

If you haven't already, I encourage you to upgrade to @mdn/browser-compat-data (v2.0.2, as of today) as I expect to cease publishing the old package in a few weeks. Thank you!

[ddbeck]

There have not been been any issues raised related to the package scoping since we've started releasing under both names and issuing deprecation notices under the old name. With this in mind, I intend to:

1. Issue a final mdn- release with a short README directing users to the scoped package.
2. Mark all releases of mdn- as deprecated.
3. Merge master-scoped-package into master and continue development of BCD under the scoped package name exclusively.

Unless there are any late-breaking problems or objections, I plan to do this on Thursday, October 29.

[ddbeck]

I have now merged #7155, completing the process of renaming the package to @mdn/browser-compat-data and I've marked the old name as deprecated on npm. We're done! I'm excited to turn my attention to more interesting improvements to our process, tools, and, of course, data. 🎉

Thank you to everyone who supported this effort. I'm grateful for your input, reviews, and—most of all—patience for this process.

[queengooborg]

As a little follow-up, I scanned through NPM packages that listed BCD as a data and created issues on their GitHub repos to let their developers know about the package change and new version!