elastic / elastic/integrations

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

Open
#19,284 5 comments 1 reaction 1 assignee Claimed by @mrodm View on GitHub
Team:Ecosystem
Dominant language
Handlebars
Stars
333
Forks
647
Avg merge
3d 4h
Merged PRs (30d)
209

Description

## Summary

The current developer documentation at
`docs/extend/developer-workflow-support-old-package.md` describes a fully
manual 4-step procedure built around direct Buildkite UI interaction. Once all
other sub-issues of #19016 ship, this page will be out of date across every
section. This issue tracks rewriting it to match the new automated workflow.

## Background

The current page covers:
1. Finding the git commit for the target package version (`get_release_commit.sh`)
2. Manually triggering the **integrations-backport** Buildkite pipeline via the UI
3. Manually creating a PR with the bug fix against the backport branch
4. Manually opening a PR against `main` to update the changelog

After #19016's sub-issues land, the new workflow is:

| Old step | New mechanism |
|---|---|
| Manually trigger Buildkite UI to create a branch | Open a PR adding an entry to `.backports.yml`; `create-backport-branch.yml` handles the rest (#19211) |
| Manually cherry-pick, bump version, write changelog, open PR | Run `backport_apply.sh ` as one command, or let `auto-backport.yml` do it when a checklist box is checked (#19212, #19214) |
| Manually open a PR against `main` to sync the changelog | `sync-backport-changelog.yml` opens that PR automatically on every push to a backport branch (#19215) |
| No inventory of active branches | `.backports.yml` is the source of truth (#19210) |

## Acceptance criteria

- [ ] Rewrite the **overview** and **detailed steps** sections to describe the
new PR-driven branch creation flow (add entry to `.backports.yml`).
- [ ] Document the backport checklist: when it appears on a PR, what checking
a box does, and how to opt out.
- [ ] Document `backport_apply.sh`: syntax, required arguments, what it does
(cherry-pick, version bump, `changelog.yml` entry, PR creation), and when
to use it manually vs. letting automation handle it.
- [ ] Document that the main-branch changelog sync is now automatic
(`sync-backport-changelog.yml`) and no manual PR is needed.
- [ ] Document the automatic owner sync that runs as part of `backport_apply.sh`
(and `auto-backport.yml` once #19214 ships): what it syncs
(`manifest.yml owner.github` + `.github/CODEOWNERS` entries), the
separate "Sync `` package owners from main" commit it produces, the
no-op behavior when owners already match, and the warn-and-continue
behavior when `main` is unreachable or the package has been removed from
it (#19686).
- [ ] Document the `check-backport-owners` CI step: when it runs (PRs
targeting `backport-*` branches), what the PR comment looks like in each
outcome (in sync ✅ / mismatch table with team mentions / check-itself-failed
warning), what action the PR author should take on a mismatch, and that it
is currently `soft_fail: true` (#19686).
- [ ] Document `.backports.yml`: schema, how to register a new backport branch,
the `maintained_until` / `archived` fields, and how archival works (#19264).
- [ ] Remove or update the "Known issues" section if the issues described are
no longer relevant after the workflow change.
- [ ] Update any screenshots that reference the Buildkite UI input form.

## Dependencies

This issue should be picked up **after** #19210, #19211, #19212, #19213,
#19214, #19215, #19686 are merged, so the documentation reflects the final implemented
behaviour rather than a moving target.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.