Docs

Author: nightkr

README.md

@@ -55,6 +55,24 @@ bake --image-version 0.0.0-dev
 The GitHub action called `Build (and optionally publish) 0.0.0-dev images` can be triggered manually to do build all images in all versions.
 When triggered manually it will _not_ push the images to the registry.
 
+## Patches
+
+Many products apply Stackable-specific patches, managed by [Patchable](rust/patchable).
+
+### Check out patched sources locally
+
+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
+```
+
+### Save patched sources
+
+```sh
+cargo patchable export druid 26.0.0
+```
+
 ## Verify Product Images
 
 To verify if Apache Zookeeper validate against OpenShift preflight, run:

rust/patchable/README.md

@@ -0,0 +1,39 @@
+# Patchable
+
+Patchable is a tool for managing patches for the third-party products distributed by Stackable as part of the Stackable Data Platform.
+
+Patchable works by keeping a series of .patch files (in `docker-images/<PRODUCT>/stackable/patches/<VERSION>`)
+as its source of truth, but using temporary Git repositories as an interface to modify those patches.
+This lets us track the history of patches over time, but reuse the existing familiarity and tooling around Git.
+
+Patchable designates a commit as the upstream _base_ for each version, and considers each commit made on top of that
+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/
+# do stuff
+git commit
+popd
+cargo patchable export druid 26.0.0
+git status
+```
+
+For more details, run `cargo patchable --help`.
+
+## Notes
+
+- patchable only supports linear patch series (no merges beyond the base commit)
+- patchable doesn't support support merging "materialized" trees, merge the .patch files instead, and `checkout`/`export` to update the hashes
+- `patchable checkout` doesn't support resolving patch conflicts, use `git am` instead (and then `patchable export` the resolved patches)
+- Always run patchable via `cargo patchable` (rather than `cargo install`ing it), to ensure that you use the correct version for a given checkout of docker-images
+
+## Configuration
+
+Patchable stores a per-version file in `docker-images/<PRODUCT>/stackable/patches/<VERSION>/patchable.toml`.
+It currently recognizes the following keys:
+
+- `upstream` - the URL of the upstream repository (such as `https://github.com/apache/druid.git`)
+- `base` - the commit hash of the upstream base commit (such as `7cffb81a8e124d5f218f9af16ad685acf5e9c67c`)

rust/patchable/src/main.rs

@@ -71,18 +71,32 @@ impl ProductVersionContext<'_> {
     }
 }
 
+/// Patchable is a tool for managing patches for the third-party products distributed by Stackable.
 #[derive(clap::Parser)]
+#[clap(
+    // Encourage people to let cargo decide the current version
+    bin_name = "cargo patchable",
+)]
 struct Opts {
     #[clap(subcommand)]
     cmd: Cmd,
 }
 
 #[derive(clap::Parser)]
 enum Cmd {
+    /// Check out a patched source tree to docker-images/<PRODUCT>/patchable-work/worktree/<VERSION>
+    ///
+    /// The patches will be pulled from docker-images/<PRODUCT>/stackable/patches/<VERSION>
+    ///
+    /// The source tree will be overwritten if it already exists (equivalent to `git switch`).
     Checkout {
         #[clap(flatten)]
         pv: ProductVersion,
     },
+
+    /// Export the patches from the source tree at docker-images/<PRODUCT>/patchable-work/worktree/<VERSION>
+    ///
+    /// The patches will be saved to docker-images/<PRODUCT>/stackable/patches/<VERSION>
     Export {
         #[clap(flatten)]
         pv: ProductVersion,

rust/patchable/src/repo.rs

@@ -21,12 +21,15 @@ pub enum Error {
         branch: String,
         commit: error::CommitId,
     },
-    #[snafu(display("failed to create worktree folder at {path:?}"))]
+    #[snafu(display("failed to create worktree parent folder at {path:?}"))]
     CreateWorktreePath {
         source: std::io::Error,
         path: PathBuf,
     },
-    #[snafu(display("failed to create worktree {path:?} pointing at {branch} in {repo}"))]
+    #[snafu(display(
+        "failed to create worktree {path:?} pointing at {branch} in {repo} (hint: {})",
+        "it may have been created but deleted in the past, try `git -C {repo} worktree prune`"
+    ))]
     CreateWorktree {
         source: git2::Error,
         repo: error::RepoPath,