radicle/patch: Add Change ID — heartwood

Radicle patches have IDs, which are the commit IDs of the COB.

Other tools, like Jujutusu, Gerrit, and GitButler use Change IDs to refer to commits consistently as they are rebased.

COB

In order for Radicle to integrate with these tools more easily in the future, add an action that allows linking a patch with a Change ID.

This naturally requires an optional struct member and some boilerplate.

CLI

rad patch show will print the Change ID if linked.

CLI Tests

Most of this is taken from Jujutsu’s own testing setup, see: https://github.com/jj-vcs/jj/blob/98d884827e2b9db72d480bb0c3610e51f103b7d4/cli/tests/common/test_environment.rs#L106-L150

Not all features are preserved, but this is good enough.

See also: https://lore.kernel.org/git/CAESOdVAspxUJKGAA58i0tvks4ZOfoGf1Aa5gPr0FXzdcywqUUw@mail.gmail.com/T

           ]);
           nativeCheckInputs = with pkgs; [
             jq
             jujutsu
           ];
           env =

     cwd: Option<PathBuf>,
     homes: HashMap<String, Home>,
     formula: &'a TestFormula,
     /// For seeding randomness in Jujutsu.
     jj_seed: usize,
 }
 impl<'a> TestRunner<'a> {

             cwd: None,
             homes: formula.homes.clone(),
             formula,
             jj_seed: 0,
         }
     }

         if let Some(ref h) = test.home {
             if let Some(home) = self.homes.get(h) {
                 env.insert("USER".to_owned(), h.to_owned());
                 return TestRun {
                     home: home.clone(),
                     env,

                     fs::create_dir_all(run.path())?;
                 }
                 let jj_envs = if assertion.command == "jj" {
                     runner.jj_seed += 1;
                     vec![
                         ("JJ_RANDOMNESS_SEED", runner.jj_seed.to_string()),
                         ("JJ_TIMESTAMP", "2001-02-03T04:05:06+07:00".to_string()),
                         ("JJ_OP_TIMESTAMP", "2001-02-03T04:05:06+07:00".to_string()),
                     ]
                 } else {
                     vec![]
                 };
                 let bins = self
                     .bins
                     .iter()

                     .env("PATH", &bins)
                     .env("RUST_BACKTRACE", "1")
                     .envs(run.envs())
                     .envs(jj_envs)
                     .current_dir(run.path())
                     .args(args)
                     .with_assert(assert.clone())

 Let's make sure that the config is exactly what we expect.
 ```
 $ jj config list
 ui.editor = "true"
 user.name = "Test User"
 user.email = "test.user@example.com"
 debug.commit-timestamp = "2001-02-03T04:05:06+07:00"
 debug.randomness-seed = 1
 debug.operation-timestamp = "2001-02-03T04:05:06+07:00"
 operation.hostname = "host.example.com"
 operation.username = "test-username"
 ```
 We enable writing Change ID headers to our commits.
 ```
 $ jj config set --user git.write-change-id-header true
 ```
 We initialize Jujutusu for our repository.
 ```(stderr)
 $ jj git init --colocate
 Done importing changes from the underlying Git repo.
 Hint: The following remote bookmarks aren't associated with the existing local bookmarks:
   master@rad
 Hint: Run `jj bookmark track master@rad` to keep local bookmarks updated on future pulls.
 Initialized repo in "."
 ```
 Off we go!
 ```
 $ jj status
 The working copy has no changes.
 Working copy  (@) : pmmvwywv ed64a0f3 (empty) (no description set)
 Parent commit (@-): xpnzuzwn f2de534b master master@rad | Second commit
 ```
 Just making sure that Git sees the Change ID…
 ```
 $ git cat-file commit ed64a0f3
 tree b4eecafa9be2f2006ce1b709d6857b07069b4608
 parent f2de534b5e81d7c6e2dcaf58c3dd91573c0a0354
 author Test User <test.user@example.com> 981147906 +0700
 committer Test User <test.user@example.com> 981147906 +0700
 change-id pmmvwywvzvvnvnzntqnqknuzpwttyvkr
 ```
 \ No newline at end of file

 The scenario in this file is a variation of the one in `rad-patch.md`,
 but uses Change IDs generated by Jujutsu.
 When contributing to another's project, it is common for the contribution to be
 of many commits and involve a discussion with the project's maintainer.  This is supported
 via Radicle's patches.
 Here we give a brief overview for using patches in our hypothetical car
 scenario.  It turns out instructions containing the power requirements were
 missing from the project.
 ```
 $ jj new
 $ touch REQUIREMENTS
 ```
 Here the instructions are added to the project's README for 1.21 gigawatts and
 commit the changes to git.
 ```
 $ jj describe --message "Define power requirements"
 ```
 Once the code is ready, we open (or create) a patch with our changes for the project.
 As of 2025-05 we can't use `jj` to do this directly, see:
  - <https://github.com/jj-vcs/jj/issues/4075>
  - <https://github.com/jj-vcs/jj/pull/2098>
 However, since we initialized Jujutusu to colocate with Git, we can just use
 Git to push.
 ``` (stderr)
 $ git push rad -o patch.message="Define power requirements" -o patch.message="See details." HEAD:refs/patches
 ✓ Patch 0a47ee4cd4a976a021df5acf60eee5eb74b0c62d opened
 ✓ Change ID pmmvwywvzvvnvnzntqnqknuzpwttyvkr detected and linked
 To rad://z42hL2jL4XNk6K8oHQaSWfMgCL7ji/z6MknSLrJoTcukLrE435hVNQT4JUhbvWLX4kUzqkEStBU8Vi
  * [new reference]   HEAD -> refs/patches
 ```
 It will now be listed as one of the project's open patches.
 ```
 $ rad patch
 ╭─────────────────────────────────────────────────────────────────────────────────────────╮
 │ ●  ID       Title                      Author         Reviews  Head     +   -   Updated │
 ├─────────────────────────────────────────────────────────────────────────────────────────┤
 │ ●  0a47ee4  Define power requirements  alice   (you)  -        ed64a0f  +0  -0  now     │
 ╰─────────────────────────────────────────────────────────────────────────────────────────╯
 ```
 Let's also create a bookmark for it.
 ```
 $ jj bookmark create flux-capacitor-power
 ```
 ```
 $ rad patch show 0a47ee4 -p
 ╭─────────────────────────────────────────────────────╮
 │ Title      Define power requirements                │
 │ Patch      0a47ee4cd4a976a021df5acf60eee5eb74b0c62d │
 │ Author     alice (you)                              │
 │ Change ID  pmmvwywvzvvnvnzntqnqknuzpwttyvkr         │
 │ Head       ed64a0f39d9929f5945d47e07de109fdf1dabc57 │
 │ Head       3e674d1a1df90807e934f9ae5da2591dd6848a33 │
 │ Branches   flux-capacitor-power                     │
 │ Commits    ahead 1, behind 0                        │
 │ Status     open                                     │
 │                                                     │
 │ See details.                                        │
 ├─────────────────────────────────────────────────────┤
 │ 3e674d1 Define power requirements                   │
 ├─────────────────────────────────────────────────────┤
 │ ● opened by alice (you) (3e674d1) now               │
 ╰─────────────────────────────────────────────────────╯
 ```
 \ No newline at end of file

             term::format::secondary(labels.join(", ")).into(),
         ]);
     }
     if let Some(change_id) = patch.change_id() {
         attrs.push([
             term::format::tertiary("Change ID".to_owned()).into(),
             term::format::secondary(change_id).into(),
         ]);
     } else if verbose {
         attrs.push([
             term::format::tertiary("Change ID".to_owned()).into(),
             term::format::dim("None".to_owned()).into(),
         ]);
     }
     attrs.push([
         term::format::tertiary("Head".to_owned()).into(),
         term::format::secondary(revision.head().to_string()).into(),

     formula(cwd.as_ref(), test)?
         .env("RAD_HOME", home.to_string_lossy())
         .env("JJ_CONFIG", home.join(".jjconfig.toml").to_string_lossy())
         .envs(envs)
         .run()?;

         .env("GIT_COMMITTER_DATE", "1671125284")
         .env("GIT_COMMITTER_EMAIL", "radicle@localhost")
         .env("GIT_COMMITTER_NAME", "radicle")
         .env("JJ_USER", "Test User")
         .env("JJ_EMAIL", "test.user@example.com")
         .env("JJ_OP_HOSTNAME", "host.example.com")
         .env("JJ_OP_USERNAME", "test-username")
         .env("JJ_TZ_OFFSET_MINS", "660")
         .env("EDITOR", "true")
         .env("TZ", "UTC")
         .env("LANG", "C")

     Ok(formula)
 }
 fn program_reports_version(program: &str) -> bool {
     use std::io::ErrorKind;
     use std::process::{Command, Stdio};
     match Command::new(program)
         .arg("--version")
         .stdout(Stdio::null())
         .status()
     {
         Err(e) if e.kind() == ErrorKind::NotFound => {
             log::warn!(target: "test", "`{program}` not found.");
             false
         }
         Err(e) => panic!("while checking for program {program}: {}", e),
         Ok(_) => true,
     }
 }
 #[test]
 fn rad_auth() {
     test("examples/rad-auth.md", Path::new("."), None, []).unwrap();

 #[test]
 fn rad_cob_multiset() {
     {
         // `rad-cob-multiset` is a `jq` script, which requires `jq` to be installed.
         // We test whether `jq` is installed, and have this test succeed if it is not.
         // Programmatic skipping of tests is not supported as of 2024-08.
         use std::io::ErrorKind;
         use std::process::{Command, Stdio};
         match Command::new("jq").arg("-V").stdout(Stdio::null()).status() {
             Err(e) if e.kind() == ErrorKind::NotFound => {
                 log::warn!(target: "test", "`jq` not found. Succeeding prematurely.");
                 return;
             }
             Err(e) => panic!("while checking for jq: {}", e),
             Ok(_) => {}
         }
     // `rad-cob-multiset` is a `jq` script, which requires `jq` to be installed.
     // We test whether `jq` is installed, and have this test succeed if it is not.
     // Programmatic skipping of tests is not supported as of 2024-08.
     if !program_reports_version("jq") {
         return;
     }
     let mut environment = Environment::new();

 }
 #[test]
 fn rad_patch_jj() {
     // We test whether `jj` is installed, and have this test succeed if it is not.
     // Programmatic skipping of tests is not supported as of 2024-08.
     if !program_reports_version("jj") {
         return;
     }
     let mut environment = Environment::new();
     let profile = environment.profile(config::profile("alice"));
     let working = tempfile::tempdir().unwrap();
     // Setup a test repository.
     fixtures::repository(working.path());
     test(
         "examples/rad-init.md",
         working.path(),
         Some(&profile.home),
         [],
     )
     .unwrap();
     test(
         "examples/jj-init.md",
         working.path(),
         Some(&profile.home),
         [],
     )
     .unwrap();
     test(
         "examples/rad-patch-jj.md",
         working.path(),
         Some(&profile.home),
         [],
     )
     .unwrap();
 }
 #[test]
 fn rad_patch_diff() {
     let mut environment = Environment::new();
     let profile = environment.profile(config::profile("alice"));

 {
     let reference = working.find_reference(src.as_str())?;
     let commit = reference.peel_to_commit()?;
     let change_id = commit
         .header_field_bytes("change-id")
         .ok()
         .and_then(|buf| buf.as_str().map(String::from));
     let dst = git::refs::storage::staging::patch(nid, commit.id());
     // Before creating the patch, we must push the associated git objects to storage.

             patch::MergeTarget::default(),
             base,
             commit.id(),
             change_id,
             &[],
             signer,
         )

             } else {
                 "opened"
             };
             let patch = patch.id;
             let patch_id = patch.id;
             eprintln!(
                 "{} Patch {} {action}",
                 term::format::positive("✓"),
                 term::format::tertiary(patch),
                 term::format::tertiary(patch_id),
             );
             if let Some(change_id) = patch.change_id() {
                 eprintln!(
                     "{} Change ID {} detected and linked",
                     term::format::positive("✓"),
                     term::format::tertiary(change_id),
                 );
             }
             // Create long-lived patch head reference, now that we know the Patch ID.
             //
             //  refs/namespaces/<nid>/refs/heads/patches/<patch-id>
             //
             let refname = git::refs::patch(&patch).with_namespace(nid.into());
             let refname = git::refs::patch(&patch_id).with_namespace(nid.into());
             let _ = stored.raw().reference(
                 refname.as_str(),
                 commit.id(),

             // Setup current branch so that pushing updates the patch.
             if let Some(branch) =
                 rad::setup_patch_upstream(&patch, commit.id().into(), working, upstream, false)?
                 rad::setup_patch_upstream(&patch_id, commit.id().into(), working, upstream, false)?
             {
                 if let Some(name) = branch.name()? {
                     if profile.hints() {

                     }
                 }
             }
             Ok(Some(ExplorerResource::Patch { id: patch }))
             Ok(Some(ExplorerResource::Patch { id: patch_id }))
         }
         Err(e) => Err(e),
     };

         revision: RevisionId,
         commit: git::Oid,
     },
     #[serde(rename = "linkChangeId")]
     LinkChangeId { change_id: String },
     //
     // Review actions

     pub(super) timeline: Vec<EntryId>,
     /// Reviews index. Keeps track of reviews for better performance.
     pub(super) reviews: BTreeMap<ReviewId, Option<(RevisionId, ActorId)>>,
     /// Change ID associated with the patch. This is emitted by tools like Jujutsu.
     pub(super) change_id: Option<String>,
 }
 impl Patch {

             assignees: BTreeSet::default(),
             timeline: vec![id.into_inner()],
             reviews: BTreeMap::default(),
             change_id: None,
         }
     }

         &self.author
     }
     /// Change ID linked to the patch.
     pub fn change_id(&self) -> &Option<String> {
         &self.change_id
     }
     /// All revision authors.
     pub fn authors(&self) -> BTreeSet<&Author> {
         self.revisions

             Action::Merge { .. } => match self.target() {
                 MergeTarget::Delegates => Authorization::Deny,
             },
             Action::LinkChangeId { .. } => Authorization::from(actor == author),
             // Anyone can submit a review.
             Action::Review { .. } => Authorization::Allow,
             Action::ReviewRedact { review, .. } | Action::ReviewEdit { review, .. } => {

             Action::Assign { assignees } => {
                 self.assignees = BTreeSet::from_iter(assignees.into_iter().map(ActorId::from));
             }
             Action::LinkChangeId { change_id } => {
                 self.change_id = Some(change_id);
             }
             Action::RevisionEdit {
                 revision,
                 description,

             labels: labels.into_iter().collect(),
         })
     }
     /// Links this patch to a Change ID.
     pub fn link_change_id(&mut self, change_id: String) -> Result<(), store::Error> {
         self.push(Action::LinkChangeId { change_id })
     }
 }
 pub struct PatchMut<'a, 'g, R, C> {

         target: MergeTarget,
         base: impl Into<git::Oid>,
         oid: impl Into<git::Oid>,
         change_id: Option<String>,
         labels: &[Label],
         cache: &'g mut C,
         signer: &Device<G>,

             if state != Lifecycle::default() {
                 tx.lifecycle(state)?;
             }
             if let Some(change_id) = change_id {
                 tx.link_change_id(change_id)?;
             }
             Ok(())
         })?;
         cache

                 target,
                 branch.base,
                 branch.oid,
                 None,
                 &[],
                 &alice.signer,
             )