flatpak-sdk-extension-maintenance

Flatpak SDK And Extension Maintenance

Carry the release intent of a reference PR across branch/*; never carry the source branch's identity. Prefer a verified chain of original update commits because it preserves intermediate release metadata and produces useful history on branches that have fallen several versions behind.

Inputs

Obtain or infer:

• The reference PR URL or <owner>/<repo>#<number>.
• The local checkout, or permission to clone the PR's repository.
• Any branch exclusions. With no exclusions, target every remote branch/*.

Ask only for information that repository and GitHub state cannot answer.

1. Establish The Reference Update

1. Check the primary worktree and remotes. Preserve all existing user changes;

perform branch work in isolated temporary worktrees.

1. Use gh pr view to record the repository, PR number, base branch, head

commits, title, changed files, merged state, and checks. Fetch the PR head through refs/pull/<number>/head rather than assuming its branch still exists.

1. Inspect every commit and file diff. Identify the semantic transition:

dependency or component, old version/ref, new version/ref, source URL, checksum, release date, and metadata entries.

1. Confirm this is a focused update. Treat unrelated code, permissions,

runtime changes, or unexplained generated-file changes as a boundary that needs user guidance before propagation.

The reference is established when every changed hunk is classified as either release intent or unrelated scope, and no unexplained hunk remains.

2. Inventory Runtime Branches

1. Fetch and prune remote refs without changing the primary worktree.
2. Enumerate remote refs matching exactly branch/*. Do not include similarly

named refs such as beta, update branches, or PR heads.

1. For each branch, inspect its manifest and update metadata to determine its

current version/ref and branch-specific identity. Record at least manifest branch, runtime, runtime version, SDK, and any differing build settings.

1. Classify each branch:

• current: already contains the desired update; skip it.
• behind: has a version from the same update line; build a chain.
• ahead or divergent: updating would downgrade or cross release lines;

report it and request guidance.

• equivalent PR exists: an open PR already targets the same branch and

desired version; skip it and report the URL.

The inventory is complete when every branch/* ref has exactly one classification.

3. Build A Verified Update Chain

For each distinct version gap, discover merged update PRs against the reference base branch and inspect their original commits. Build a contiguous chain where each transition's old version equals the previous transition's new version, ending at the reference PR's desired version.

Accept a chain link only when:

• Its component and release line match the reference update.
• Its diff is a focused predecessor of the reference update.
• Its declared source URL, checksum, release date, and metadata agree with the

commit diff.

• The next link starts at the version produced by this link.

Prefer original PR commits over merge commits. Fetch them through PR refs or their immutable commit IDs. Never infer a missing checksum or fabricate a release entry. If no verified contiguous chain exists, explain the missing transition and request guidance.

4. Prepare Each Target

Use one isolated worktree and one new local branch per outdated target. Choose a deterministic, collision-free name that identifies the runtime branch and desired version.

1. Start from the current remote target ref.
2. Cherry-pick verified commits oldest-first, preserving their commit messages.
3. If a cherry-pick conflicts, resolve by release intent:

• Preserve the target's branch, runtime, runtime version, SDK, permissions,

build options, formatting, and unrelated metadata.

• Apply the verified source URL/ref and checksum from the picked commit.
• Add missing release entries once, maintaining the target file's ordering

and style. Keep target-specific historical entries.

• Compare the staged resolution with the picked commit's diff before

continuing.

1. If a conflict reaches outside the classified update hunks or admits more

than one plausible result, abort that target's cherry-pick, leave other targets intact, and report the exact ambiguity.

Release intent crosses branches; branch identity does not.

5. Validate Before Publication

Run static and source checks for every prepared target:

1. Confirm the diff changes only files and fields justified by the verified

update chain.

1. Confirm branch identity matches the original target exactly.
2. Confirm the final manifest names the desired version/ref and source URL.
3. Download each changed source and verify its declared checksum. Reuse a

securely cached download when branches declare the same source.

1. Parse JSON, YAML, and XML with available repository or system tooling. Run

relevant lightweight repository lint commands when present.

1. Verify release metadata is newest-first, contains each chained release once,

and uses the verified dates.

1. Confirm commits are based on the latest remote target and the worktree is

otherwise clean.

Do not substitute a full local Flatpak build for these checks unless the user asks. Flathub PR builds provide compilation coverage after publication.

6. Draft The Pull Request Body

Write each body after validation so every claim is backed by a completed check. Keep it short enough to scan alongside the diff: one branch-specific reference line followed by the checks that passed.

Backport of #<reference-pr> to `branch/<runtime>` (includes #<prerequisite-pr>).

Validation:
- source checksum matches the manifest
- manifest and AppStream metadata parse successfully
- release entries are ordered and unique
- branch-specific runtime settings are unchanged
- diff is limited to the expected update files

Omit the parenthetical when no prerequisite update is needed. Omit any validation bullet whose check did not run or pass. If conflict resolution changed what reviewers need to inspect, replace the relevant generic bullet with one concrete statement about the preserved target setting.

Apply an unslop writing pass before presenting the draft:

• Remove restatements of the title, process narration, filler, and claims that

merely say the change is successful or comprehensive.

• Keep only the Validation: label; headings such as Summary, Changes, Notes,

and Testing add structure without information in these small update PRs.

• Name the target branch and link the reference and prerequisite PR numbers.
• Use the same checklist order across branches so differences are visible.

Save each final body to a file for review and later pass that exact file to gh pr create --body-file.

7. Approval Gate

Before any push or PR creation, present a table with:

Include blocked, skipped, and already-current branches. Show the exact proposed pushes and PR base branches, then show each exact PR title and body. Summarize resolved conflicts and ask for explicit approval to publish. Preparation approval from earlier in the conversation is not publication approval.

8. Publish After Approval

After explicit approval:

1. Re-fetch each target and stop if its remote head moved.
2. Push each prepared branch without force.
3. Open one PR per target branch with the approved focused title and its saved

body via gh pr create --body-file. Do not regenerate or expand the body during publication.

1. Return every PR URL and any branch that failed to publish.

Leave merging to the user and Flathub's checks. Never merge, enable auto-merge, delete remote branches, or publish a partially validated target.

Completion

A run is complete when every remote branch/* branch is represented by a PR URL, a verified already-current/open-PR skip, or a precise blocker. Clean up temporary worktrees after their commits are safely published or the user asks to discard them; retain unpublished local branches until the user decides.