Add REBASE.md with the upstream-update workflowpixelated-scaling-option

1 files changed, 77 insertions, 0 deletions

diff --git a/REBASE.md b/REBASE.md
new file mode 100644
index 000000000..02dd12c85
--- /dev/null
+++ b/REBASE.md
@@ -0,0 +1,77 @@
+# Rebase workflow
+
+This branch (`pixelated-scaling-option`) carries one feature commit on top
+of upstream KDE Dolphin (pixelated thumbnail scaling + hide-file-extensions).
+This file is only on this branch, never on `master`.
+
+## Layout
+
+- `master` — pure mirror of `kde/master`. Never commit here.
+- `pixelated-scaling-option` — feature commit + this file.
+- Remote `kde` → `https://invent.kde.org/system/dolphin.git` (upstream).
+- Remote `origin` → `ssh://katana/srv/git/dolphin.git` (cgit mirror).
+- Companion repo: `~/Documents/Repositories/arch-dolphin`, branch
+  `pixelated-scaling-option`, holds the PKGBUILD and the generated patch.
+
+## When a new Dolphin version is released
+
+### 1. Update master to upstream
+
+```
+git fetch kde
+git checkout master
+git reset --hard kde/master
+git push --force-with-lease origin master
+```
+
+### 2. Rebase the feature branch
+
+```
+git checkout pixelated-scaling-option
+git rebase master
+git push --force-with-lease origin pixelated-scaling-option
+```
+
+If conflicts hit `kfileitemmodel.cpp` or `viewsettingstab.{cpp,h}`: keep
+the genuine feature additions and take upstream for everything else.
+Do **not** let the resolution bring back deleted upstream code (e.g. the
+font-style warning UI, `expandUrlAfterInserted`, `RatingRole`) — that
+was the original bug we cleaned up in commit `41d6039c9`.
+
+### 3. Pick the new release tag
+
+```
+git tag -l 'v*' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -5
+```
+
+Pick the latest (e.g. `v26.08.0`). KDE only keeps recent tarballs on
+`download.kde.org`, so use a current one.
+
+### 4. Regenerate the patch against that tag
+
+```
+FEATURE_SHA=$(git log --grep='pixel scaling and filename' -n 1 --format=%H pixelated-scaling-option)
+TAG=v26.08.0   # whatever you picked
+
+git checkout --detach "$TAG"
+git cherry-pick "$FEATURE_SHA"
+git diff HEAD~1 HEAD > ~/Documents/Repositories/arch-dolphin/pixelated-scaling-and-hide-extensions.patch
+git checkout pixelated-scaling-option
+```
+
+### 5. Bump and rebuild the package
+
+```
+cd ~/Documents/Repositories/arch-dolphin
+git checkout pixelated-scaling-option
+
+# edit PKGBUILD: set pkgver=<TAG without 'v'>
+updpkgsums
+# updpkgsums will replace the patch's SKIP with a real sha; flip it back to SKIP
+
+makepkg -sf --skippgpcheck
+sudo pacman -U dolphin-*.pkg.tar.zst
+
+git add PKGBUILD pixelated-scaling-and-hide-extensions.patch
+git commit -m "upgpkg: <version>: Upstream update"
+```