chore: backport docs update by johnmtll · Pull Request #5101 · mongodb/node-mongodb-native

johnmtll · 2026-11-03T20:10:08Z

Description

Summary of Changes

Updates the backport docs to make the steps to achieve a backport a little more-clear, and includes context for handling CI failures.

Notes for Reviewers

What is the motivation for this change?

For bug fixes

Current (incorrect) behavior:

Expected behavior:

How to reproduce:

Affected versions:

Release Highlight

Release notes highlight

Double check the following

Lint is passing (npm run check:lint)
Self-review completed using the steps outlined here
PR title follows the correct format: type(NODE-xxxx)[!]: description
- Example: feat(NODE-1234)!: rewriting everything in coffeescript
Changes are covered by tests
New TODOs have a related JIRA ticket

Copilot

🟡 Changes recommended

The release sync instructions name nonexistent publish.yml instead of the required npm-publish.yml, so following them would miss the publishing workflow.

1 open issue

List the correct npm-publish workflow file · New

What changed in this PR

This documentation-only PR clarifies the MongoDB Node.js driver’s backport process, including how to handle CI failures on release branches.

Changes:

Splits backport work into separate CI-fix, code-backport, and release-tooling PRs.
Adds guidance on reusing CI fixes and synchronizing release workflows from main.

File	Description
`etc/notes/releasing.md`	Reorganizes backport instructions and expands CI and release-tooling guidance.

_{Review effort: Balanced}

#5101 (comment) Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

PavelSafronov

Changes look good! I've got a few notes, but nothing major.

PavelSafronov · 2026-11-05T20:11:14Z

-First, create a copy of our current release action (release.yml). Then, change any references to `main` to the target branch. Also, add the branch to the list of CodeQL target branches (codeql.yml). Double check that there isn't any release tooling on `main` that doesn't exist on the target branch. If there is, make sure this is backported too. After opening the PR, check the CI to make sure everything works as expected: add backports of CI fixes as needed.
+1. **CI fix PR(s).** Apply the CI fixes needed for CI to go green on the release branch (for example changes to `.evergreen/`, lint and test configs, dependency pins). Some of these can be taken from `main`. Open further PRs as needed until CI is green.
+2. **Backport PR(s).** The code changes being backported. You can replay a cherry picked commit from step 1 onto this PR branch so your code can be tested against a sane base.
+3. **Release tooling sync PR.** Copy the release workflows from `main` (`npm-publish.yml`, `release.yml`, etc.). In `release.yml`, change any references to `main` to the target branch. Also add the branch to the list of CodeQL target branches (`codeql.yml`). Backport any other release tooling from `main` that the target branch is missing.


Another thing to include in these steps is to update the tag value in release.yml on the release branch.

The change is around line 107 and goes from

node ./.github/scripts/dispatch-and-wait.mjs npm-publish.yml \ tag=latest \ # <--- here version="$(node -p "require('./package.json').version")" \ ref="${{ github.sha }}"

to

node ./.github/scripts/dispatch-and-wait.mjs npm-publish.yml \ tag=6x \ # <--- here version="$(node -p "require('./package.json').version")" \ ref="${{ github.sha }}"

This way we won't publish a latest version from that branch.

Here's one attempt at this wording:

In release.yml, change any references to main to the target branch, and change the tag=latest argument of the npm-publish dispatch to a dist-tag for the backport line (convention: <major>x, e.g. 6x). Never publish a backport as latest, or it becomes the default npm install version. The tag must not be a valid semver range (6.x and 7.1.x are rejected by npm).

PavelSafronov · 2026-11-05T20:17:38Z

-First, create a copy of our current release action (release.yml). Then, change any references to `main` to the target branch. Also, add the branch to the list of CodeQL target branches (codeql.yml). Double check that there isn't any release tooling on `main` that doesn't exist on the target branch. If there is, make sure this is backported too. After opening the PR, check the CI to make sure everything works as expected: add backports of CI fixes as needed.
+1. **CI fix PR(s).** Apply the CI fixes needed for CI to go green on the release branch (for example changes to `.evergreen/`, lint and test configs, dependency pins). Some of these can be taken from `main`. Open further PRs as needed until CI is green.
+2. **Backport PR(s).** The code changes being backported. You can replay a cherry picked commit from step 1 onto this PR branch so your code can be tested against a sane base.
+3. **Release tooling sync PR.** Copy the release workflows from `main` (`npm-publish.yml`, `release.yml`, etc.). In `release.yml`, change any references to `main` to the target branch. Also add the branch to the list of CodeQL target branches (`codeql.yml`). Backport any other release tooling from `main` that the target branch is missing.


We should remove the etc. here, it doesn't help. We can list out the impacted files: .github/workflows/release.yml, .github/workflows/build.yml, and .github/scripts/dispatch-and-wait.mjs

The release flow may be dependent on multiple scripts/workflows. The sync should be a main-favoured clobber of existing files and import of missing files. The 'missing files' is what 'etc.' accounts for.

PavelSafronov · 2026-11-05T20:22:13Z

-First, create a copy of our current release action (release.yml). Then, change any references to `main` to the target branch. Also, add the branch to the list of CodeQL target branches (codeql.yml). Double check that there isn't any release tooling on `main` that doesn't exist on the target branch. If there is, make sure this is backported too. After opening the PR, check the CI to make sure everything works as expected: add backports of CI fixes as needed.
+1. **CI fix PR(s).** Apply the CI fixes needed for CI to go green on the release branch (for example changes to `.evergreen/`, lint and test configs, dependency pins). Some of these can be taken from `main`. Open further PRs as needed until CI is green.
+2. **Backport PR(s).** The code changes being backported. You can replay a cherry picked commit from step 1 onto this PR branch so your code can be tested against a sane base.
+3. **Release tooling sync PR.** Copy the release workflows from `main` (`npm-publish.yml`, `release.yml`, etc.). In `release.yml`, change any references to `main` to the target branch. Also add the branch to the list of CodeQL target branches (`codeql.yml`). Backport any other release tooling from `main` that the target branch is missing.


Order of operations: I think the CodeQL change should be moved to step 1, since that step is the "CI fixes".

PavelSafronov · 2026-11-05T20:22:42Z

 release-please automatically tags release commits with a tag in the format v<major>.<minor>.<patch>.  When backporting, first determine the target minor version and create a release branch for it by branching off of the release tag.  The release branch should follow the format `v<major>.<minor>.x`.  For example, to create a backport of bson's 6.5 release, create a release branch from the v6.5.0 tag with the name v6.5.x.  

-Then, backport the release action to the target release branch. This should be done as the first PR on the release branch. Use the following instructions to create it.
+A backport is split across several PRs, each opened against the `v<major>.<minor>.x` release branch.


Let's be explicit here: the below PRs should be opened, reviewed, and merged in this specific order.

PavelSafronov · 2026-11-05T20:35:49Z

  - [Packages](#packages)

 > [!NOTE]
 > _Last updated: Oct 1, 2025_


Update this text.

johnmtll added 3 commits November 3, 2026 15:09

chore: backport docs update

4150506

docs: fix desync

c1448b7

docs: reorder

77f899d

johnmtll marked this pull request as ready for review November 4, 2026 16:20

johnmtll requested a review from a team as a code owner November 4, 2026 16:20

Copilot AI balanced review requested due to automatic review settings November 4, 2026 16:20

Copilot started reviewing on behalf of johnmtll November 4, 2026 16:21

View session

Copilot AI reviewed Nov 4, 2026

View reviewed changes

Comment thread etc/notes/releasing.md Resolved

chore: address comment

e1bdc16

#5101 (comment) Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

PavelSafronov reviewed Nov 5, 2026

View reviewed changes

PavelSafronov self-assigned this Nov 10, 2026

PavelSafronov added the Primary Review In Review with primary reviewer, not yet ready for team's eyes label Nov 10, 2026

Navigation Menu

Repository navigation

chore: backport docs update - #5101

chore: backport docs update#5101
johnmtll wants to merge 4 commits into
mainfrom
johnmtll/backport-docs

johnmtll commented Nov 3, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

PavelSafronov left a comment

Uh oh!

PavelSafronov Nov 5, 2026

Uh oh!

PavelSafronov Nov 5, 2026

Uh oh!

johnmtll Nov 13, 2026

Uh oh!

PavelSafronov Nov 5, 2026

Uh oh!

PavelSafronov Nov 5, 2026

Uh oh!

PavelSafronov Nov 5, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

johnmtll commented Nov 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Summary of Changes

Notes for Reviewers

What is the motivation for this change?

For bug fixes

Release Highlight

Release notes highlight

Double check the following

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

PavelSafronov left a comment

Choose a reason for hiding this comment

Uh oh!

PavelSafronov Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

PavelSafronov Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

johnmtll Nov 13, 2026

Choose a reason for hiding this comment

Uh oh!

PavelSafronov Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

PavelSafronov Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

PavelSafronov Nov 5, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

johnmtll commented Nov 3, 2026 •

edited

Loading