Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
5 tasks done
ddbeck opened this issue Sep 3, 2020 · 21 comments
Closed
5 tasks done
Labels
infra Infrastructure issues (npm, GitHub Actions, releases) of this project question Issues where a question or problem is stated and a discussion is held to gather opinions.

Comments

@ddbeck
Copy link
Collaborator

ddbeck commented Sep 3, 2020

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 ddbeck added question Issues where a question or problem is stated and a discussion is held to gather opinions. infra Infrastructure issues (npm, GitHub Actions, releases) of this project labels Sep 3, 2020
@ddbeck
Copy link
Collaborator Author

ddbeck commented Sep 3, 2020

@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!

@ddbeck ddbeck pinned this issue Sep 3, 2020
@sideshowbarker
Copy link
Contributor

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
Copy link
Contributor

foolip commented Sep 3, 2020

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
Copy link
Collaborator Author

ddbeck commented Sep 3, 2020

@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
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Member

Elchi3 commented Sep 3, 2020

(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:

@Fyrd
Copy link
Contributor

Fyrd commented Sep 4, 2020

Sounds good to me too, thanks for notifying me!

@ddbeck
Copy link
Collaborator Author

ddbeck commented Sep 7, 2020

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.

Done!

Done!

@queengooborg
Copy link
Contributor

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
Copy link
Contributor

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

@octref
Copy link

octref commented Sep 17, 2020

I have left Microsoft. /cc @aeschli

@aeschli
Copy link

aeschli commented Sep 17, 2020

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

@ExE-Boss
Copy link
Contributor

This will also need to happen with mdn‑data.

@queengooborg
Copy link
Contributor

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

@ExE-Boss
Copy link
Contributor

@vinyldarkscratch
Done: mdn/data#427

@ddbeck
Copy link
Collaborator Author

ddbeck commented Sep 24, 2020

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
Copy link
Collaborator Author

ddbeck commented Oct 8, 2020

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
Copy link
Collaborator Author

ddbeck commented Oct 26, 2020

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
Copy link
Collaborator Author

ddbeck commented Oct 29, 2020

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.

@ddbeck ddbeck closed this as completed Oct 29, 2020
@ddbeck ddbeck unpinned this issue Oct 29, 2020
@queengooborg
Copy link
Contributor

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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
infra Infrastructure issues (npm, GitHub Actions, releases) of this project question Issues where a question or problem is stated and a discussion is held to gather opinions.
Projects
None yet
Development

No branches or pull requests

10 participants