[SCM] PostGIS branch master updated. 3.7.0beta2-7-g8c59690f6
git at osgeo.org
git at osgeo.org
Mon Aug 10 01:29:49 PDT 2026
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "PostGIS".
The branch, master has been updated
via 8c59690f60446d9659a254dc99c3d59103169a99 (commit)
via 912cc17d85274a76a8a28d616c8249999c1250db (commit)
from 10b5cd9534f6a436a73af191a367ed6e8be7155f (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 8c59690f60446d9659a254dc99c3d59103169a99
Merge: 10b5cd953 912cc17d8
Author: Darafei Praliaskouski <komzpa at gmail.com>
Date: Mon Aug 10 01:29:48 2026 -0700
Merge pull request 'Document split-component backpatching' (!708) from Komzpa/postgis:docs/backpatch-pre-split-components-20260810 into master
Reworks the maintainer backpatching checklist so it stays focused on
backpatch-specific decisions and links to the docs that own adjacent workflow
rules.
The updated page keeps the branch-sweep guidance concise, removes stale
branch-range examples and generic pull-request prose, and links out for commit,
branch, metadata, project-inventory, and testing details.
It also documents the parts that are easy to miss:
* a complete backpatch sweep must inspect the split component repositories
listed in the project inventory;
* the sweep must include backpatchable fixes from component history, not only
commits already copied into the PostGIS tree;
* old stable branches need small in-tree ports that match their branch layout,
generated SQL state, build rules, and test semantics;
* component-only packaging, CI, release, and layout changes stay in the
component repository;
* separate source fixes should stay separate in the target branch; do not squash
unrelated component commits into one broad backpatch commit only because they
were found in one sweep;
* target commits should use the source author when they are mainly a manual port
of one source commit, and `Co-authored-by` should name only people who helped
write that target commit.
Validation:
* `git diff --check upstream/master...HEAD`
* scoped file gate: only `doc/development/maintenance/backpatching.md`
Reviewed-on: https://gitea.osgeo.org/postgis/postgis/pulls/708
commit 912cc17d85274a76a8a28d616c8249999c1250db
Author: Darafei Praliaskouski <me at komzpa.net>
Date: Mon Aug 10 01:44:30 2026 +0400
Document split-component backpatching
diff --git a/doc/development/maintenance/backpatching.md b/doc/development/maintenance/backpatching.md
index 4531fdc19..446e86b64 100644
--- a/doc/development/maintenance/backpatching.md
+++ b/doc/development/maintenance/backpatching.md
@@ -5,202 +5,124 @@ weight: 20
geekdocHidden: false
---
-Backpatching keeps supported release lines consistent without turning stable
-branches into feature branches. Use this checklist when a bug fix, release-line
-CI fix, or security fix may need to move between `master` and supported
-`stable-*` branches.
+Use this checklist to propagate bug fixes between `master` and supported
+`stable-*` branches. For general branch, commit, and authorship rules, see
+[Commit and branch guidelines](commit-guidelines.md). For pull request labels,
+milestones, and draft state, see
+[Pull request metadata](pull-request-metadata.md).
-## Supported Branch Set
+## Select Target Branches
-Start from the active support window. At the time of writing, the supported
-branch set is `master` through `stable-3.2`. Exclude end-of-life branches unless
-the release manager explicitly asks for an exceptional backpatch.
+Determine the current support window from the release state. Fetch the
+canonical OSGeo Gitea branches, then inspect `Version.config` and the top
+`NEWS` section on each candidate branch. Do not backpatch to an end-of-life
+branch without release-manager approval.
-Confirm the current branch state before editing:
+Check open pull requests before preparing a branch. An existing pull request
+may already contain all or part of the same fix lineage.
-* fetch the canonical OSGeo Gitea repository;
-* inspect `Version.config` and the top `NEWS` section on each target branch;
-* check for existing open pull requests that already carry part of the same
- backpatch lineage.
+## Scan In Both Directions
-GitHub pull requests are review surfaces. The canonical source branch remains
-the OSGeo Gitea branch.
+First scan from older branches towards newer branches. Compare adjacent release
+lines to find fixes committed directly to an older stable branch but missing
+from a newer branch or `master`.
-## Pull Request Family Shape
+Then scan from newer branches towards older supported branches. For each fix,
+continue until the first branch where the bug or affected code does not exist.
+Do not introduce a feature or a new API only to make a fix apply to an older
+release.
-Keep one pull request per target branch in a backpatch family: one common
-`master` pull request when the lineage still needs `master` work, plus one pull
-request for each supported `stable-*` branch that needs the fix. If several
-`master`-only follow-ups are found while repairing the family, fold them into
-the common `master` pull request instead of opening separate `master` pull
-requests by subtopic.
+Classify candidates by behavior, not by commit or pull request ranges. Include
+fixes for runtime correctness, crashes, security, installation, upgrades,
+packaging, supported builds, and user-facing documentation. Exclude version
+bumps, release preparation, translations, refactoring, and feature work unless
+they contain a distinct backpatchable fix.
-Cross-link the common `master` pull request and the stable pull requests in
-their bodies. When a subtopic is intentionally `master`-only, say that in the
-stable pull-request bodies instead of creating a second `master` lane.
+Before porting a fix, check the target branch's capabilities. Relevant
+differences may include:
-## First Pass: Older Fixes Missing From Newer Branches
+* C and SQL APIs, function signatures, and generated tables;
+* build targets and dependency versions;
+* extension objects and upgrade paths;
+* regression fixtures and expected semantics.
-Before pushing changes from new branches to old branches, scan in the opposite
-direction. A fix may have been committed directly to an older stable branch and
-missed `master` or a newer stable line.
+Stop when the affected behavior is absent or the fix would require unsupported
+infrastructure. Record the reason in the pull request or maintainer handoff.
-Compare adjacent branches:
+## Inspect Split Component Repositories
-* `stable-3.6` not in `master`
-* `stable-3.5` not in `stable-3.6`
-* `stable-3.4` not in `stable-3.5`
-* `stable-3.3` not in `stable-3.4`
-* `stable-3.2` not in `stable-3.3`
+A backpatch sweep must inspect relevant split component repositories, even when
+the report or pull request names only the PostGIS tree. Use the repository links
+in the [PostGIS project inventory](../governance/project-inventory.md). Review
+component commits, pull requests, release notes, and tests for the same bug and
+for follow-up fixes. Do not limit the sweep to commits already present in the
+PostGIS repository.
-Classify only real fix candidates: runtime correctness, crashes, security,
-packaging, install or upgrade behavior, release-line CI blockers, and
-user-facing documentation corrections. Ignore release-prep commits, version
-bumps, translation churn, broad refactors, and feature work unless they expose a
-missing regression test or `NEWS` entry for a real bug fix.
+For new work, use the component repository. When a supported stable branch
+still contains that component in the PostGIS tree, port the applicable fix to
+the branch's in-tree source:
-If an older branch contains a real fix that still applies to `master`, open a
-pull request to `master` first. If `master` has already fixed the same bug by a
-different implementation, consider whether the regression test or `NEWS` entry
-is still missing before opening a code PR.
+* `address_standardizer` uses `extensions/address_standardizer/`;
+* `postgis_tiger_geocoder` uses `extras/tiger_geocoder/`.
-## Second Pass: Newer To Older
+Inspect the target branch's files, build rules, generated data, loader scripts,
+and regression targets before editing. Carry only the code fix and tests that
+fit that branch. Leave component-only packaging, CI, release, and repository
+layout changes in the component repository.
-After the upward scan, walk from newer branches to older supported branches.
-For each fix lineage, cherry-pick or port the fix until reaching the first older
-branch that does not have the affected bug.
+If the fix changes generated or year-specific SQL, use the target branch's
+generation path when it exists and produces a focused change. Otherwise update
+the stored SQL directly and keep the diff limited to the affected behavior.
-Stop when the affected code path, SQL function, extension object, build target,
-or regression test does not exist on the older branch. Do not backport a new
-feature only to make a bug fix fit an older release line.
+Adapt tests to the target branch's public behavior. Do not copy expected output
+for functions or cases that the branch does not support.
-Backport by branch capability, not by pull-request number range. For each
-source hunk, check that the target branch has the same API surface and test
-contract before carrying it over:
+## Preserve Provenance
-* C enum values, pixel types, version macros, and generated lookup tables;
-* SQL wrappers versus C functions with planner support hooks;
-* function signatures, default arguments, and sentinel values;
-* build-system variables and recursive `make` entry points;
-* supported PostgreSQL and dependency versions in CI;
-* regression-test fixtures and expected output semantics.
-
-Do not backpatch fuzzer harnesses, seed corpora, OSS-Fuzz input-target
-plumbing, or fuzzer-only CI repairs to stable branches unless that exact stable
-branch runs the fuzzer target. In the normal PostGIS branch layout, fuzzer
-target work is `master`-only; stable branches should receive the runtime fix and
-any ordinary regression coverage that exercises shipped code, not the fuzzer
-driver used to find or smoke-test it.
-
-If a source test only proves behavior introduced on newer branches, omit or
-adapt that subtest on older branches. Keep the regression that protects the
-portable bug fix, but do not force an expected row only because it appeared in
-the newer branch. A missing expected row means: first inspect the SQL query and
-the target branch's function semantics, then decide whether the code or the
-test is non-portable.
-
-Record the stop reason in the pull request or maintainer handoff, for example:
-
-```text
-Stops at stable-3.3 because stable-3.2 does not have CG_AlphaShape.
-```
-
-## Commit Shape And Provenance
-
-Prefer one source commit to one target commit. Clean cherry-picks should use
-`git cherry-pick -x` so the source commit hash is preserved.
-
-When cherry-picking a commit that is already a cherry-pick, keep only the
-provenance that helps reviewers trace the backpatch. Avoid stacking repeated
-`(cherry picked from commit ...)` lines mechanically; collapse noisy duplicate
-trailers into one clear source commit, or use a `Ported-from:` line for a manual
-port.
-
-When a clean cherry-pick is not possible, make the smallest faithful port and
-record the source in the commit body:
+Prefer one source commit per target commit. Use `git cherry-pick -x` for a clean
+cherry-pick. For a manual port, record the source commit in the commit body, for
+example:
```text
Ported-from: https://gitea.osgeo.org/postgis/postgis/commit/<sha>
```
-If several source commits were iterative attempts to fix one bug, it is fine to
-collapse them into a smaller, correct target series. Do not collapse unrelated
-fixes into one commit, and do not rewrite public PR history only to hide later
-CI follow-up commits. Once a branch has been pushed for review, append focused
-follow-up commits for target-branch CI issues unless the maintainer explicitly
-asks for a rewrite.
+Keep separate source fixes separate in the target branch. Do not squash
+unrelated component commits into one broad backpatch commit only because they
+were found in the same sweep. If a target commit is mainly a manual port of one
+source commit, use that source commit's author. Add `Co-authored-by` trailers
+only for people who helped write that target commit.
-Use source-commit subjects where they remain accurate. If the target branch API
-or file layout differs, adjust the subject to describe the target-branch fix
-while keeping the `Ported-from:` line.
+If several source commits are attempts at one fix, they may be reduced to a
+smaller correct series. Follow [Commit and branch guidelines](commit-guidelines.md)
+for subjects, tracker references, and authorship.
-## NEWS
+## Update NEWS
-Assume a backpatch-worthy fix needs `NEWS` on every branch where it lands,
-including `master`, unless investigation shows it is purely internal and not
-release-note-worthy. A `NEWS` entry should describe the user-visible bug or
-supported build behavior, not the branch archaeology.
+Inspect the top `NEWS` section on every target branch. Add an entry when the fix
+is user-visible, release-note-worthy, security-relevant, or tracked as a bug.
+Use the target branch's current release section and existing heading style.
+Describe the fixed behavior, not the branch history.
-Put the entry under the top release section for the target branch and match that
-branch's existing heading style. Use:
+Keep wording consistent across branches, but adjust details that differ by
+release line. Follow [Commit and branch guidelines](commit-guidelines.md) for
+tracker notation and contributor credit.
-* `#NNNN` for Trac tickets;
-* `GH-NNN` for GitHub pull requests only inside `NEWS`;
-* `GT-NNN` for Gitea pull requests only inside `NEWS`.
+## Validate Each Port
-When a bug fix has no existing ticket, use concise user-facing wording and the
-contributor name if the surrounding section uses contributor credits.
-
-## Tests And Validation
-
-Every code backpatch should carry a regression test when a focused test is
-practical. For test-output drift caused by newer dependencies, make the test
-less brittle when possible instead of only replacing expected output with one
-machine's result.
-
-Before pushing a backpatch PR, run at least:
+Run validation on each target branch; success on the source branch is not
+evidence for the port. At minimum, run:
* `git diff --check`;
-* syntax or build smoke relevant to the touched files;
-* the focused regression target when the target branch can realistically run in
- the local environment.
+* the relevant build or syntax check;
+* the focused regression target when the branch and local environment support
+ it;
+* the repository's `NEWS` checks when `NEWS` changes.
-If local validation is not practical, state the exact blocker in the pull
-request. After pushing, read back the PR head SHA and CI state. The goal is a
-mergeable, green PR. If CI finds target-branch-only drift or harness breakage,
-fix it in the same PR when it belongs to making that backpatch mergeable.
+Use [Testing and debugging](../testing/_index.md) for build and regression
+commands. If a focused test cannot run, state the exact blocker and the
+validation that was completed.
-## Existing Backpatch Pull Requests
-
-Before creating a new PR, check open stable-branch pull requests. Preserve an
-existing PR when it is clean and correctly scoped. Supersede or repair it only
-when it has the wrong base, misses commits from the same lineage, lacks `NEWS`
-or tests, has misleading public text, or has conflicts that are cleaner to fix
-by replacing the branch.
-
-Do not fold unrelated master feature PRs into the backpatch sweep merely because
-they are open. Include only stable-base PRs, clear backpatch PRs, and PRs that
-the branch comparison proves are part of the fix lineage.
-
-## Pull Request Body
-
-The PR body should let reviewers trace the fix without reading local notes.
-Include:
-
-* the source commit or commits, preferably as OSGeo Gitea URLs;
-* the target branch;
-* whether the change was a clean cherry-pick, manual port, or collapsed fix
- series;
-* validation that was run, and any validation that was not practical;
-* any stop reason for older branches.
-
-For ticketed fixes, include a concrete Trac follow-up line for the oldest branch
-that will contain the fix after merge:
-
-```text
-After merge: update https://trac.osgeo.org/postgis/ticket/6081 fixed version to 3.5.7.
-```
-
-Use the target branch's next release version from `Version.config` and `NEWS`.
-If the same ticket lands on several branches, the follow-up should name the
-oldest supported release that contains the fix.
+The pull request or handoff should identify the source commit, whether the
+change is a cherry-pick or manual port, validation performed, and the stop
+reason for any older branch that was considered but not changed.
-----------------------------------------------------------------------
Summary of changes:
doc/development/maintenance/backpatching.md | 266 ++++++++++------------------
1 file changed, 94 insertions(+), 172 deletions(-)
hooks/post-receive
--
PostGIS
More information about the postgis-tickets
mailing list