Skip to content

Breaking ABI on an existing release line by bumping NODE_MODULE_VERSION #49875

Description

@joyeecheung

According to

### Update `NODE_MODULE_VERSION`
bumping NODE_MODULE_VERSION outside of a major release is possible, but AFAICT we've never done it in practice

It is current TSC policy to bump major version when ABI changes. If you
see a need to bump NODE_MODULE_VERSION outside of a major release then
you should consult the TSC. Commits may need to be reverted or a major
version bump may need to happen.

Now the time comes when we may need to break the ABI in order to backport to v20.x a series of memory issue fixes that are blocking people (in particular jest users) from upgrading away from v16.x: #49874 .

EDIT: turns out that we found a way to avoid the ABI breakage.

This issue is used to figure out

  1. How the packages that distribute prebuilt native addons are using these versions, if they make assumptions about the relationship between NODE_MODULE_VERSION and Node.js/V8 versions or only rely on NODE_MODULE_VERSION alone (in the former case, bumping NODE_MODULE_VERSION on an existing release line can cause breakage. In the latter case there should be no problem).
  2. What else we need to do besides bumping NODE_MODULE_VERSION
  3. Ultimately if breaking ABI outside of a major release is feasible or not, and update the release guide based on information we get

Activity

  1. joyeecheung commented on Sep 26, 2023

    @joyeecheung
    MemberAuthor

    cc @nodejs/tsc

  2. mcollina commented on Sep 26, 2023

    @mcollina
    SponsorMember

    Given that v16 is out of support, I'm +1 with the ABI breakage before v20 hits LTS.
    I don't think we should backport this to v18.

  3. mhdawson commented on Sep 26, 2023

    @mhdawson
    Member

    I do believe this is going to break prebuilt native addons if they are not using Node-API. I don't think we should be doing this unless we have something that is really really important enough to override respecting SemVer.

    In terms of v20, developers to have worked in advance to create their prebuilt addons for 20.x are likely to be unimpressed if we break then just a few weeks before the LTS switch.

  4. mcollina commented on Sep 26, 2023

    @mcollina
    SponsorMember

    @joyeecheung have you got a tracking issue for the breaking of Jest? What % of users are affected?

  5. joyeecheung commented on Sep 26, 2023

    @joyeecheung
    MemberAuthor

    So I just realized that since we can "add whatever we want to the v8 fork on v20.x", basically, we can use some Node.js-only extensions to the V8 API there to avoid the ABI breakages completely. Not sure if we should still keep the issue open though, as ABI breakages might still come up again, maybe we need to update the doc about whether this is feasible or not..

  6. github-actions commented on May 28, 2026

    @github-actions
    Contributor

    This issue has been marked as stale due to 210 days of inactivity.
    It will be automatically closed in 30 days if no further activity occurs. If this is still relevant, please leave a comment or update it to keep it open.

  7. added
    staleIssues and PRs marked stale due to inactivity and scheduled for automatic closure.
    on May 28, 2026
  8. github-actions commented on Jun 28, 2026

    @github-actions
    Contributor

    This issue has been automatically closed after 30 days of inactivity following its stale status (no activity for a total of 240 days).
    If this is still relevant, feel free to reopen it or leave a comment with additional details so we can continue the discussion.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    staleIssues and PRs marked stale due to inactivity and scheduled for automatic closure.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions