Document how to rebase patch series

Author: nightkr

README.md

@@ -64,7 +64,7 @@ Many products apply Stackable-specific patches, managed by [Patchable](rust/patc
 This is not required for building the images, but is useful when debugging or hacking on our patch sets.
 
 ```sh
-cargo patchable checkout druid 26.0.0
+cd $(cargo patchable checkout druid 26.0.0)
 ```
 
 ### Save patched sources
@@ -73,6 +73,33 @@ cargo patchable checkout druid 26.0.0
 cargo patchable export druid 26.0.0
 ```
 
+### Porting patch series to a new version
+
+Patchable doesn't support restoring a patch series that doesn't apply cleanly. Instead, use `git cherry-pick` to rebase the patch series.
+
+For example, let's try rebasing our patch series from Druid 26.0.0 to Druid 28.0.0 (which is not packaged by SDP):
+
+```sh
+# Restore the old version
+# In addition to creating the version worktree, this also creates the branches patchable/26.0.0 (26.0.0 with our patches applied) and
+# patchable/base/26.0.0 (upstream 26.0.0 with no patches).
+cargo patchable checkout druid 26.0.0
+# Tell Patchable about the new version 28.0.0, which can be fetched from https://github.com/apache/druid.git, and has the tag druid-28.0.0
+cargo patchable init druid 28.0.0 --upstream https://github.com/apache/druid.git --base druid-28.0.0
+# Create and go to the worktree for the new version
+pushd $(cargo patchable checkout druid 28.0.0)
+
+# Rebase the patch series
+git cherry-pick patchable/base/26.0.0..patchable/26.0.0
+# Solve conflicts and `git cherry-pick --continue` until done
+# You can also use `git cherry-pick --skip` to skip patches that are no longer required
+
+# Leave and export the new patch series!
+popd
+cargo patchable export druid 28.0.0
+git status
+```
+
 ## Verify Product Images
 
 To verify if Apache Zookeeper validate against OpenShift preflight, run:

rust/patchable/README.md

@@ -12,8 +12,7 @@ to be an individual patch.
 ## Usage
 
 ```sh
-cargo patchable checkout druid 26.0.0
-pushd $(git rev-parse --show-toplevel)/druid/patchable-work/worktree/26.0.0/
+pushd $(cargo patchable checkout druid 26.0.0)
 # do stuff
 git commit
 popd

rust/patchable/src/main.rs

@@ -76,6 +76,10 @@ impl ProductVersionContext<'_> {
         self.work_root().join("worktree").join(&self.pv.version)
     }
 
+    fn base_branch(&self) -> String {
+        format!("patchable/base/{}", self.pv.version)
+    }
+
     fn worktree_branch(&self) -> String {
         format!("patchable/{}", self.pv.version)
     }
@@ -245,21 +249,47 @@ fn main() -> Result<()> {
                 &config.upstream,
             )
             .context(FetchBaseCommitSnafu)?;
+            let base_branch = ctx.base_branch();
+            let base_branch = match product_repo
+                .find_commit(base_commit)
+                .and_then(|base| product_repo.branch(&base_branch, &base, true))
+            {
+                Ok(_) => {
+                    tracing::info!(
+                        branch.base = base_branch,
+                        branch.base.commit = %base_commit,
+                        "updated base branch"
+                    );
+                    Some(base_branch)
+                }
+                Err(err) => {
+                    tracing::warn!(
+                        error = &err as &dyn std::error::Error,
+                        branch.base = base_branch,
+                        branch.base.commit = %base_commit,
+                        "failed to update base branch reference, ignoring..."
+                    );
+                    None
+                }
+            };
             let patched_commit = patch::apply_patches(&product_repo, &ctx.patch_dir(), base_commit)
                 .context(ApplyPatchesSnafu)?;
 
             let product_worktree_root = ctx.worktree_root();
+            let worktree_branch = ctx.worktree_branch();
             repo::ensure_worktree_is_at(
                 &product_repo,
                 &ctx.pv.version,
                 &product_worktree_root,
-                &ctx.worktree_branch(),
+                &worktree_branch,
                 patched_commit,
             )
             .context(CheckoutProductWorktreeSnafu)?;
 
             tracing::info!(
                 worktree.root = ?product_worktree_root,
+                branch.worktree = worktree_branch,
+                branch.base = base_branch,
                 "worktree is ready!"
             );