Document how to import invalid patch series into patchable

Author: nightkr

README.md

@@ -79,6 +79,27 @@ cargo patchable export druid 26.0.0
 cargo patchable init druid 28.0.0 --upstream https://github.com/apache/druid.git --base druid-28.0.0
 ```
 
+### Importing patch series into Patchable
+
+Patchable is stricter about applying invalid patches (both metadata and patches themselves) than Git is.
+
+If an initial `cargo patchable checkout` fails then `git am` can be useful for the initial migration:
+
+```sh
+# Create Patchable configuration for the new version, if it doesn't already exist
+cargo patchable init druid 30.0.0 --upstream https://github.com/apache/druid.git --base druid-30.0.0
+# Check out the upstream base commit, without trying to apply the patches
+pushd $(cargo patchable checkout druid 30.0.0 --base-only)
+
+# Apply the patch series
+git am ../../../stackable/patches/30.0.0/*.patch
+# Resolve any conflicts that arise, and `git am --continue` until done
+
+# Leave and export the new patch series!
+popd
+cargo patchable export druid 30.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.

rust/patchable/src/main.rs

@@ -118,6 +118,10 @@ enum Cmd {
     Checkout {
         #[clap(flatten)]
         pv: ProductVersion,
+
+        /// Check out the base commit, without applying patches
+        #[clap(long)]
+        base_only: bool,
     },
 
     /// Export the patches from the source tree at docker-images/<PRODUCT>/patchable-work/worktree/<VERSION>
@@ -241,7 +245,7 @@ fn main() -> Result<()> {
     let images_repo = Repository::discover(".").context(FindImagesRepoSnafu)?;
     let images_repo_root = images_repo.workdir().context(NoImagesRepoWorkdirSnafu)?;
     match opts.cmd {
-        Cmd::Checkout { pv } => {
+        Cmd::Checkout { pv, base_only } => {
             let ctx = ProductVersionContext {
                 pv,
                 images_repo_root,
@@ -280,8 +284,13 @@ fn main() -> Result<()> {
                     None
                 }
             };
-            let patched_commit = patch::apply_patches(&product_repo, &ctx.patch_dir(), base_commit)
-                .context(ApplyPatchesSnafu)?;
+            let patched_commit = if !base_only {
+                patch::apply_patches(&product_repo, &ctx.patch_dir(), base_commit)
+                    .context(ApplyPatchesSnafu)?
+            } else {
+                tracing::warn!("--base-only specified, skipping patches");
+                base_commit
+            };
 
             let product_worktree_root = ctx.worktree_root();
             let worktree_branch = ctx.worktree_branch();