You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[Docs][Backports] Update developer documentation to reflect new automated backport workflow - #20413
docs(backports): update developer docs to reflect automated backport workflow (#19284)
Bring developer-workflow-support-old-package.md and ci_pipelines.md in
line with the fully automated backport workflow: document the checklist
comment, auto-backport, changelog sync, owner synchronization, and the
integrations-backport-dispatch pipeline.
What
Updated docs/extend/developer-workflow-support-old-package.md and docs/ci_pipelines.md to reflect the fully automated backport workflow across issues #19211–#19215, #19686, and related follow-up PRs.
developer-workflow-support-old-package.md:
Rewrote the intro to lead with automation rather than "manual changes".
Added checklist callout in the overview linking to the checklist section.
Added "(skip if the branch already exists)" to step 2.
Restructured step 3 into Automatic (checklist/auto-backport) and Manual (backport_apply.sh) sub-paths; backport_apply.sh now documented with argument tables, two usage examples (basic and with --origin-pr-number), and a numbered description of what the script does.
Made pipeline list intro agnostic of pipeline count.
Added integrations-backport-dispatch as a Buildkite link (consistent with other entries); removed "(private)" label.
Removed trailing slashes from all Buildkite URLs.
Added check-changelog-pr-links, check-backports-inventory (main-only scope), check-changelog-versions-in-main, and the backport-dispatch pipeline architecture.
Added "Note: currently disabled" to the weekly job section.
Why
The backport workflow was significantly automated across multiple merged PRs (#19997, #20062, #20119, #20236, #19930, #20251, #20197, #20284, #20384, #20556, #20578, #20605, #21017, #21243, #21379). The developer documentation still described the old fully-manual procedure. This update brings both docs in line with the current automated workflow so contributors have accurate guidance on releasing hotfixes for older package versions.
Author's Checklist
Verified docs against final merged state of all referenced PRs.
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>
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>
)
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>
… 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 elastic#19284.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…check (elastic#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 elastic#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 elastic#19284.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ckages
Update docs to reflect the now-merged auto-backport automation (PR elastic#20197)
and upcoming skip_checklist_packages field (PR elastic#20384):
- Replace "Coming soon" note with description of auto-backport.yml: on merge,
the workflow reads checked branches from the checklist and creates backport
PRs automatically; post-merge checklist edits also trigger it.
- Update checklist comment section: describe checkboxes and auto-backport
trigger, update example to show [ ] checkbox format and new intro text, and
note that the comment is now recreated (delete+POST) on each push.
- Add "Suppressing a package from the checklist" block documenting the new
top-level skip_checklist_packages field (elastic#20384).
- ci_pipelines.md: remove stale "coming soon" qualifier from the
check-changelog-versions-in-main step — it shipped with elastic#20197.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Document known issue #3: the --coverage-format flag was introduced in
elastic-package v0.96.0 (2024-01-18) and is not available on backport
branches based on older commits. Solution: remove the flag from the
relevant script on the backport branch.
Generated with Claude Sonnet 4.6
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…n issue
The missing shellinit known issue only applies to elastic-package < v0.86.0.
From v0.86.0 onward, stack connection settings are read automatically from
the current profile so shellinit is no longer needed.
Generated with Claude Sonnet 4.6
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add a "Retrying a failed sync" note to step 4: when sync-backport-changelog.yml
fails after pushing the working branch but before opening the PR, any maintainer
with write access can re-trigger it by commenting /sync-changelog on the merged
backport PR — no dummy commit needed.
Based on PR elastic#20578 (open at time of writing — verify on merge).
Generated with Claude Sonnet 4.6
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…0578 merged
The failure comment includes the /sync-changelog retry hint on any sync
failure, not only when the working branch was already pushed. Verified
against the final merged state of PR elastic#20578.
Generated with Claude Sonnet 4.6
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Documents the !!seq unmarshal error that affects backport branches using
elastic-package < v0.96.0 after the CI sync PR elastic#20542 replaced the
standalone docker-compose binary installation with the Docker CLI plugin.
Includes root cause explanation and fix steps: revert DOCKER_COMPOSE_VERSION
to the pre-sync value in the three pipeline files, restore with_docker_compose
in common.sh, and wire it into the test scripts. Links to example commit
fbf68eb.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ssion (elastic#21017)
- Replace second `mage applyBackport` with `backport apply` in the
package owner synchronization section (missed in previous commit).
- Update /sync-changelog permission from "write access" to
"write or maintain access" to match PR elastic#21017 (merged 2026-09-03).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…tion
Add a paragraph to step 4 explaining that the sync-backport-changelog
workflow now automatically assigns the sync PR to the backport PR's
author (if not a bot and has write/maintain/admin access) or to the
merger (if not a bot). Reflects elastic#21243, merged 2026-09-15.
Add a sentence to the checklist comment section documenting that
auto-backport PRs are automatically assigned to the original PR's
author or merger using the same logic. Preemptive for elastic#21379 (open).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add Buildkite link for integrations-backport-dispatch (replacing bare
name) and remove "(private)" label for consistency with other entries.
Remove trailing slashes from all Buildkite URLs throughout the file.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ferences
Remove "(private)" from the pipeline list entry and drop "private"
from inline references in the body text for consistency. Retain the
explanation of why a dedicated dispatch pipeline is needed, narrowed
to the relevant scenario (public pipeline triggering a private one).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Update the intro paragraph to lead with automation instead of "manual
changes". Add a checklist callout to the overview so readers can jump
directly to the checklist section. Restructure step 3 into Automatic
and Manual sub-paths, with an anchor link to the checklist section and
clearer framing of when backport_apply.sh is needed. Add a context
sentence at the top of the checklist section for developers landing
there directly from a PR comment.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…own issues
Remove the stale "wait for EPR" instruction in the manual cherry-pick
path — the changelog sync fires automatically on merge and needs no
waiting. Split the backport_apply.sh snippet into a basic and an
assignee-resolution example so --origin-pr-number reads as optional.
Add a scope sentence to the Known issues section so readers know it
applies to old backport branches with stale CI infrastructure.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
mrodm
changed the title
[Docs][Backports] Update developer documentation to reflect new automated backport workflow (#19284)
[Docs][Backports] Update developer documentation to reflect new automated backport workflow
Sep 22, 2026
The checklist comment is now posted after a PR is merged to main by
backport-packages-detect.yml (push trigger) instead of while the PR is
open. Update the developer workflow doc accordingly:
- describe the post-merge timing and the cc line for author and merger
- drop the removed post-backport-checklist.yml and "updated on each push"
wording
- align the example comment with the current checklist template
- document who can trigger auto-backport, queued runs and de-duplication
- tell readers to tick branches after merge in the intro and step 3
Reflects elastic#21736.
Created by Claude.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…sections
Address Copilot review feedback on PR elastic#20413: a PR touching a package with
active backport branches can still get no checklist when that package is
listed in skip_checklist_packages, so say so in the eligibility text.
Also turn the "Suppressing a branch/package from the checklist" bold lines
into ### headings so they have real anchors, add them to the table of
contents, and link to the branch section from the maintained_until and
archived field descriptions.
Created by Claude.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Qualify notification guarantee when the backport PR cannot be resolved
docs/ci_pipelines.md:233
The notification is conditional: trigger_backport.sh leaves PR_NUMBER empty when resolve_pr_number cannot resolve the merge, and notify_backport_pr.sh then explicitly skips posting. This sentence guarantees a comment for every merge, so qualify it to reflect that failure mode.
Qualify sync PR creation when changelog changes trigger the workflow
The sync workflow is not triggered by every merged backport PR: its push trigger is filtered to **/changelog.yml changes. A manually created backport PR (or a merge without a changelog change) therefore will not open a sync PR, so this should be qualified to avoid promising an action that will not run.
Rewrite the intro of the checklist section: state that the comment is
posted only after a PR is merged to main, only when it changes a package
with active, non-suppressed backport branches, and never for PRs merged
into other branches. Drop the conversational "if you landed here" line.
Created by Claude.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
On a clean checkout there is no build/ directory, so this command fails because go build does not create the output directory before writing build/backport. Create the directory first so the documented setup works as written.
The integrations-schedule-daily cron lines in catalog-info.yaml use
day-of-week 1-5, so the job runs on weekdays, not every night. Update the
pipeline list entry and the Daily job section accordingly.
Also point the schedules link at catalog-info.yaml on main instead of an
old pinned commit that showed the previous cron.
Created by Claude.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The sync workflow is not guaranteed to open a PR for every merged backport: its push trigger is limited to changes matching **/changelog.yml, and Collect reports skipped/already_exists when there is no actionable entry or an open sync PR already exists. Please qualify this as an attempt and mention the skip outcome so the procedure does not promise a PR that will not be created.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
mrodm
changed the title
Proposed commit message
What
Updated
docs/extend/developer-workflow-support-old-package.mdanddocs/ci_pipelines.mdto reflect the fully automated backport workflow across issues #19211–#19215, #19686, and related follow-up PRs.developer-workflow-support-old-package.md:backport_apply.sh) sub-paths;backport_apply.shnow documented with argument tables, two usage examples (basic and with--origin-pr-number), and a numbered description of what the script does./sync-changelogretry command ([CI] Add /sync-changelog comment trigger to retry failed changelog sync PRs #20578); documented sync PR assignee resolution ([sync-changelog] Assign sync PRs and always run from main #21243); removed stale "wait for EPR" instruction.check-backport-ownersCI step.auto-backport.ymlbehaviour, assignee resolution on backport PRs ([auto-backport] Assign backport PRs to the original PR author or merger #21379), suppressing branches and packages (skip_checklist_packages, Skip security_detection_engine from backport checklist comment #20384).--coverage-format) and Move import-beats script #4 (Docker Compose YAML unmarshal error).backport add-entryandbackport applyCLI references (backport: extract mage backport targets into standalone cmd/backport CLI sub-module #20556).elastic-package< v0.86.0.docs/extend/images/backport_input_step.png.docs/ci_pipelines.md:integrations-backport-dispatchas a Buildkite link (consistent with other entries); removed "(private)" label.check-changelog-pr-links,check-backports-inventory(main-only scope),check-changelog-versions-in-main, and the backport-dispatch pipeline architecture.Why
The backport workflow was significantly automated across multiple merged PRs (#19997, #20062, #20119, #20236, #19930, #20251, #20197, #20284, #20384, #20556, #20578, #20605, #21017, #21243, #21379). The developer documentation still described the old fully-manual procedure. This update brings both docs in line with the current automated workflow so contributors have accurate guidance on releasing hotfixes for older package versions.
Author's Checklist
/sync-changelogretry section against final merged state of PR [CI] Add /sync-changelog comment trigger to retry failed changelog sync PRs #20578.How to test this PR locally
Review the rendered output of the two changed files:
docs/extend/developer-workflow-support-old-package.mddocs/ci_pipelines.mdRelated issues
🤖 Generated with Claude Code