Skip to content

[Docs][Backports] Update developer documentation to reflect new automated backport workflow (#19284)#20351

Draft
mrodm wants to merge 8 commits into
mainfrom
update_backport_docs
Draft

[Docs][Backports] Update developer documentation to reflect new automated backport workflow (#19284)#20351
mrodm wants to merge 8 commits into
mainfrom
update_backport_docs

Conversation

@mrodm

@mrodm mrodm commented Jul 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Proposed commit message

[Docs][Backports] Update developer documentation to reflect new automated backport workflow (#19284)

Update developer-workflow-support-old-package.md and ci_pipelines.md to reflect
the automated backport workflow introduced across issues #19211–#19215 and #19686:
document backport_apply.sh, automatic changelog sync, owner synchronization, the
backport checklist comment, and the integrations-backport-dispatch pipeline.

WHAT:

docs/extend/developer-workflow-support-old-package.md:

  • Rewrote step 3 ("Create a PR for the bug fix") to document backport_apply.sh
    as the recommended tool: syntax, required/optional argument tables, and a
    numbered description of the 6 steps it performs (cherry-pick, version bump,
    changelog entry, owner sync, PR creation, sentinel link fix). Keeps manual
    cherry-pick as an alternative path.
  • Updated step 4 ("Update changelog in main"): replaced manual instructions with
    a description of the automatic sync-backport-changelog.yml flow — fires on
    backport PR merge, opens a sync PR against main labelled
    backport:sync-changelog and changelog-link-check:skip, posts a comment
    on the merged backport PR.
  • Added "Package owner synchronization" section: covers the automatic owner sync
    performed by backport_apply.sh (what is synced, commit message, no-op and
    warn-and-continue behaviours) and the check-backport-owners CI step (three
    possible comment outcomes, soft_fail behaviour).
  • Added "Backport checklist comment" section: when the comment is posted, example
    content, that it is currently informational only, and how to suppress a branch
    via archived/maintained_until.
  • Expanded .backports.yml field descriptions: full maintained_until and
    archived semantics (auto-exclusion, archiving does not delete the branch,
    excluded from checklist and branch creation — not schema validation), added
    the previously undocumented required remove_other_packages field (including
    it in both manual entry examples).
  • Deleted orphaned docs/extend/images/backport_input_step.png (no longer
    referenced in any doc).

docs/ci_pipelines.md:

  • Added check-changelog-pr-links documentation: validates changelog entry links
    match the PR being merged, soft_fail, changelog-link-check:skip label, and why
    sync-changelog PRs use it automatically.
  • Clarified check-backports-inventory runs on PRs targeting main only (skipped
    on backport-branch PRs).
  • Added the private integrations-backport-dispatch pipeline as the seventh
    pipeline, with description of the two-pipeline architecture and why the trigger
    was split from the public pipeline.
  • Added forward-looking note about check-changelog-versions-in-main step
    (coming with PR [backport] Auto-create backport PRs, fix changelog links, and sync changelogs to main #20197).

WHY:

The backport workflow has been significantly automated across several merged PRs
(#19997, #20062, #20119, #20236, #19930, #20251) and two open PRs (#20197,
#20284). The developer documentation still described the old fully-manual 4-step
procedure. This update brings the docs in line with the current automated
workflow so contributors have accurate guidance on how to release hotfixes for
older package versions.

Author's Checklist

How to test this PR locally

Review the rendered output of the two changed files:

  • docs/extend/developer-workflow-support-old-package.md
  • docs/ci_pipelines.md

Cross-check key claims against the codebase:

  • dev/scripts/backport_apply.sh — script CLI matches documented syntax
  • dev/backports/checklist/checklist.go — checklist comment matches example
  • .buildkite/pipeline.yml — check-backports-inventory guard, check-changelog-pr-links step
  • dev/backports/changelog/sync.go — sync PR labels

Related issues

This PR was generated with the assistance of Claude (claude-sonnet-4-6).

mrodm and others added 8 commits July 23, 2026 18:15
@mrodm @claude
docs(backport): document checklist comment and remove stale screenshot
0b3f41e 
Add a new "Backport checklist comment" section to
developer-workflow-support-old-package.md explaining when the
post-backport-checklist workflow posts a comment, what it shows,
that it is currently informational only (no checkboxes yet), and
how to suppress a branch via `archived` or `maintained_until` in
.backports.yml.

Remove the orphaned backport_input_step.png screenshot, which was
no longer referenced by any documentation page.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@mrodm @claude
docs(backport): document package owner synchronization (#19686)
1e417ca 
Add a new "Package owner synchronization" section to
developer-workflow-support-old-package.md covering:

- Automatic sync during apply: what is synced (manifest.yml
  owner.github, CODEOWNERS package line and sub-path entries),
  the separate "Sync <pkg> package owners from main" commit,
  no-op behavior when already in sync, and warn-and-continue
  when main is unreachable or the package has been removed.
- check-backport-owners CI step: when it runs (PRs targeting
  backport-* branches on packages/** or CODEOWNERS changes),
  the three PR comment outcomes (in-sync / mismatch with team
  list / check-failed), required author action on mismatch,
  and that soft_fail: true means a mismatch does not block merge.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@mrodm @claude
docs(backport): expand .backports.yml field documentation (#19264)
087a2e2 
Expand the maintained_until and archived field descriptions in the
.backports.yml schema table to document their full semantics:
maintained_until excludes the branch automatically once the date
passes (strictly before today UTC), and is preferred when the
end-of-life date is known; archived: true excludes the branch
immediately and does not delete it.

Also add the previously undocumented remove_other_packages field,
explaining its default true behavior and why it exists.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@mrodm @claude
docs(ci): document changelog link check and scope backports inventory…
f56221b 
… step

Add a note in ci_pipelines.md documenting the check-changelog-pr-links
Buildkite step: what it validates (changelog entry links match the PR
being merged), that it is soft_fail, and how to skip it via the
changelog-link-check:skip label. Explain that the sync-backport-changelog
workflow adds this label automatically on sync PRs since their entries
intentionally reference the original backport PR.

Also clarify that check-backports-inventory runs on PRs targeting main
and direct pushes to main only — it is skipped on backport-branch PRs,
which carry only a subset of packages.

Relates to #19284.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@mrodm @claude
docs(backport): document backport_apply.sh and add changelog version …
babbf7e 
…check (#19214)

Rewrite step 3 in developer-workflow-support-old-package.md to document
backport_apply.sh as the recommended tool: syntax, required/optional
arguments, and a numbered description of what it does end-to-end
(cherry-pick, version bump, changelog entry with placeholder link,
owner sync commit, PR creation, and link fix). Keep the manual
cherry-pick as an alternative and preserve the note about subsequent
fixes not needing a new branch. Add a forward-looking note about the
auto-backport workflow (PR #20197).

Add a note to ci_pipelines.md about the coming
check-changelog-versions-in-main step, which catches sync collisions
on backport-branch PRs before merge.

Relates to #19284.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@mrodm @claude
docs(backport): changelog sync to main is now automatic (#19215)
15c49c8 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@mrodm @claude
docs(ci): add integrations-backport-dispatch pipeline (#19211)
19b11b6 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@mrodm @claude
docs(backport): fix review findings — field semantics and stale examp…
e76316d 
…le date

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@mrodm mrodm self-assigned this Jul 24, 2026
mrodm
mrodm commented Jul 24, 2026
View reviewed changes
Comment thread docs/extend/images/backport_input_step.png

@mrodm mrodm Jul 24, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not used this image , this was a leftover from a previous PR.

@github-actions

github-actions Bot commented Jul 24, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

🔍 Preview links for changed docs

@andrewkroh andrewkroh added the documentation Improvements or additions to documentation. Applied to PRs that modify *.md files. label Jul 24, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@mrodm mrodm

Labels

documentation Improvements or additions to documentation. Applied to PRs that modify *.md files.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

backport: update developer documentation to reflect the new automated backport workflow

2 participants

@mrodm @andrewkroh