diff --git a/docs/features/django-fork.rst b/docs/features/django-fork.rst index 6414176..ba8bad0 100644 --- a/docs/features/django-fork.rst +++ b/docs/features/django-fork.rst @@ -391,6 +391,64 @@ validate a rebase with no PR involved, or when no suitable PR run exists yet with ``sphinx -W`` (warnings as errors), so a docs fix that has landed on the base branch will keep failing on every stale PR until each one is rebased. +Spotting upstream fixes released after the backend +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Rebasing a fork branch aligns it with upstream's *current* tip, which says +nothing about whether the **released** backend contains those commits. A +security fix backported to Django's ``stable/5.2.x`` the day after +django-mongodb-backend 5.2.4 shipped is on the fork branch, in CI, and absent +from every installed copy of the backend — and nothing in the sync output would +have said so. + +So after a successful ``--all-branches`` (or ``--branch``) sync, ``dbx sync`` +compares each mapped branch's upstream target against the highest release tag of +the same series in the group's ``release_repo`` and lists what upstream has that +the release does not: + +.. code-block:: text + + šŸ“‹ Upstream commits since the latest django-mongodb-backend release: + + 🌿 mongodb-6.1.x → upstream/stable/6.1.x + django-mongodb-backend 6.1.0 (2026-08-17) … upstream tip + 2 new commit(s): + [6.2 cycle] cabad83ed1 2026-08-18 [6.1.x] Fixed #37259 -- Restored support for old-signature Model.from_db() overrides. + [unannotated] 0db5e72fe6 2026-08-18 [6.1.x] Post-release version bump. + + 🌿 mongodb-5.2.x → upstream/stable/5.2.x + django-mongodb-backend 5.2.4 (2026-08-24) … upstream tip + āœ… nothing new upstream + +The release series comes from the branch name (``mongodb-5.2.x`` → the highest +``5.2.`` tag), so no extra per-branch configuration is needed; a branch +tracking an unreleased version (``mongodb-6.2.x`` → ``main``) reports that no +tag exists yet. The comparison uses committer dates, so a commit is "new" when +it landed on the stable branch after the release tag was cut. + +Each commit is labelled with the upstream **dev cycle** it was backported from. +Django annotates every backport with ``Backport of from main.``, so the +source commit's position on ``main`` — relative to the fork points of the +``upstream/stable/X.Y.x`` branches — identifies the cycle it was written in. +A ``[6.2 cycle]`` label on a ``stable/5.2.x`` commit is normal and simply means +the fix was authored during 6.2 development and backported to 5.2; commits with +no annotation (version bumps, per-branch release chores) are labelled +``[unannotated]``. + +Configure the release repo per synced repo: + +.. code-block:: toml + + [repo.groups.django.release_repo] + django = "django-mongodb-backend" + +The report is best-effort and never fails the sync: an unset ``release_repo``, +an un-cloned release repo, or a git error is reported as a warning and skipped. +It fetches tags in the release repo first so a stale clone does not over-report. +Pass ``--no-backport-report`` to skip it, and note it also runs under +``--dry-run`` (where it is the only thing that touches the network beyond the +single upstream fetch). + Adding a new release branch ---------------------------- diff --git a/docs/features/repo-management.rst b/docs/features/repo-management.rst index d24e7e0..9a6f72a 100644 --- a/docs/features/repo-management.rst +++ b/docs/features/repo-management.rst @@ -160,6 +160,10 @@ After cloning with the fork workflow, you can easily sync your local repository # Sync all branches but skip re-running downstream CI dbx sync django --all-branches --no-ci + # Sync all branches but skip the report of upstream commits landed since the + # latest downstream release + dbx sync django --all-branches --no-backport-report + # Preview what would be synced without making changes dbx sync mongo-python-driver --dry-run @@ -279,6 +283,8 @@ Manage worktrees for any repo with ``dbx worktree``: **Notes:** - Requires an ``upstream`` remote; on clone this comes from the ``upstream`` config key +- When a listed repo ends up without an ``upstream`` remote (cloned without ``--fork``, say), + ``dbx clone`` skips the worktree silently — pass ``--verbose`` to see the skip noted - Worktree directories are named ``-