From 45f368f91da07f13eced2970adbe69bba8db432c Mon Sep 17 00:00:00 2001 From: vincent Date: Mon, 29 Jun 2026 17:41:12 -0400 Subject: [PATCH 1/5] docs: add Veilid upgrade skill --- .claude/skills/veilid-upgrade/SKILL.md | 127 ++++++++++ .../references/dependency-map.md | 223 ++++++++++++++++++ AGENTS.md | 17 ++ CLAUDE.md | 15 ++ 4 files changed, 382 insertions(+) create mode 100644 .claude/skills/veilid-upgrade/SKILL.md create mode 100644 .claude/skills/veilid-upgrade/references/dependency-map.md create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/.claude/skills/veilid-upgrade/SKILL.md b/.claude/skills/veilid-upgrade/SKILL.md new file mode 100644 index 0000000..f243d7d --- /dev/null +++ b/.claude/skills/veilid-upgrade/SKILL.md @@ -0,0 +1,127 @@ +--- +name: veilid-upgrade +description: Upgrade Veilid across the OpenArchive Rust dependency chain. Use when asked to upgrade Veilid, bump Veilid, move to a new Veilid version, refresh veilid-core or veilid-tools tags, or run the cross-repo Veilid release cascade for veilid-iroh-blobs, save-dweb-backend, and save-rust. +--- + +# Veilid Upgrade + +Upgrade Veilid one repository at a time, in dependency order: + +1. `../veilid-iroh-blobs` +2. `../save-dweb-backend` +3. current `save-rust` + +Read `references/dependency-map.md` before editing. It contains the repo-specific pins, git URLs, and verification commands. Treat it as a map, not as a substitute for inspecting the current files. + +## Ground Rules + +- Locate dependency entries by package key or `rg`, never by hardcoded line number. +- Keep fork-origin migration separate from a Veilid version bump unless the user explicitly asks to combine them. +- Pause after each PR is opened and ask the human to review and merge before tagging and continuing downstream. +- Verify each repo's default branch, origin, and push/tag permissions before creating PRs or tags. +- Default to a patch version bump for routine dependency-only upgrades; use a minor bump only when the changelog or API impact warrants it. + +## One-Time Fork Migration + +The chain currently depends on personal upstream forks: + +- `RangerMauve/veilid-iroh-blobs` +- `tripledoublev/iroh` + +Best practice is to fork them under `OpenArchive` and repoint references in a standalone PR before or after the Veilid upgrade. Do not mix that origin migration into the Veilid bump unless the user asks. + +Until the migration is done, operate against the current upstreams listed in the manifests. + +## Step 0: Verify The Target Veilid Tag + +Discover the target tag live. Prefer machine-readable sources over GitLab HTML pages: + +```bash +git ls-remote --tags https://gitlab.com/veilid/veilid.git +curl -fsS 'https://gitlab.com/api/v4/projects/veilid%2Fveilid/repository/tags?per_page=10' +curl -fsS https://gitlab.com/veilid/veilid/-/raw/main/CHANGELOG.md +``` + +Record the target tag, the target commit hash, and the changelog entry. + +Run the hickory/iroh gate before editing: + +1. Inspect the target tag's `veilid-tools/Cargo.toml` hickory dependency or scan the changelog for hickory changes. +2. If Veilid still forces the resolver constraint that required `hickory-resolver = "=0.25.2"`, keep the hickory pins and iroh patches unchanged. +3. If Veilid relaxed the constraint, drop the hickory pins and iroh patches only as a separate, well-tested change unless the user explicitly asks to combine it. +4. For routine bumps, default to keeping the existing hickory pins and iroh patches. + +## Steps 1-3: Upgrade Each Repo + +For each repo in order: + +1. Inspect the current manifest: + +```bash +rg 'veilid-core|veilid-tools|veilid-iroh-blobs|save-dweb-backend|hickory-resolver|patch.crates-io|tripledoublev|RangerMauve|OpenArchive' Cargo.toml +``` + +2. Edit `Cargo.toml`: + +- Update every `veilid-core` and `veilid-tools` git tag to the target Veilid tag. +- Update downstream git tags only after the upstream repo's PR has merged and its release tag has been pushed. +- Update all occurrences found by search, including target-specific dependency stanzas. +- Bump the package version. +- Leave hickory and iroh patch entries untouched unless Step 0 explicitly calls for a separate compatibility cleanup. + +3. Refresh the lockfile with package-aware commands from `references/dependency-map.md`. + +- Run `cargo update -p ` only for packages present in that repo. +- If Cargo refuses a package target because of source ambiguity or graph absence, run a full lockfile refresh with `cargo update` or let `cargo build` resolve it. +- Inspect `Cargo.lock` to confirm the new Veilid commit hash and any downstream git tag/hash landed. + +4. Build and test. + +- Use a normal fresh build in the current tree. Do not run `cargo clean` unless stale artifacts or dependency resolution make it necessary. +- Discover smoke test names before invoking exact filters: + +```bash +cargo nextest list +cargo test -- --list +``` + +5. Open a PR and pause. + +- Verify default branch and permissions with `gh repo view --json defaultBranchRef` and git remote checks. +- Create a branch named like `chore/veilid-0.5.x`. +- Commit the repo-local upgrade. +- Open a PR to the repo's default branch. +- Stop and ask the human to review and merge. + +6. After merge, tag the release before continuing downstream: + +```bash +git pull --ff-only +git tag v +git push origin v +``` + +The next repo must not point at an upstream tag until that tag exists remotely. + +## Final save-rust Release + +Run the same loop for `save-rust`. Use the repo convention for the release commit, for example: + +```text +chore: release v0.2.x +``` + +Tag and push the final `save-rust` release after its PR merges. + +## Verification + +- Each repo builds and tests before its PR. +- `Cargo.lock` in each repo records the expected Veilid commit hash for the target tag. +- Downstream repos point at the freshly pushed upstream release tags. +- In `save-rust`, verify the new `save-dweb-backend` tag/hash and Veilid hash in `Cargo.lock`. +- Search all three manifests for stale old tags, replacing `OLD_VEILID_REGEX` with the previous Veilid version escaped for regex, for example `0\.5\.5`: + +```bash +OLD_VEILID_REGEX='0\.5\.x' +rg "${OLD_VEILID_REGEX}|v${OLD_VEILID_REGEX}" ../veilid-iroh-blobs/Cargo.toml ../save-dweb-backend/Cargo.toml Cargo.toml +``` diff --git a/.claude/skills/veilid-upgrade/references/dependency-map.md b/.claude/skills/veilid-upgrade/references/dependency-map.md new file mode 100644 index 0000000..efcdca5 --- /dev/null +++ b/.claude/skills/veilid-upgrade/references/dependency-map.md @@ -0,0 +1,223 @@ +# Veilid Upgrade Dependency Map + +Use this file after reading `SKILL.md`. Verify every fact against the live manifests before editing. Do not rely on line numbers. + +## Repo Layout + +The expected sibling checkout layout from `save-rust` is: + +```text +../veilid-iroh-blobs +../save-dweb-backend +. +``` + +If a repo is missing, stop and ask the user whether to clone it, locate it, or skip that stage. + +## Current Dependency Chain + +```text +veilid tag + -> veilid-iroh-blobs release tag + -> save-dweb-backend release tag + -> save-rust release tag +``` + +The downstream repo must not be updated until the upstream repo has a merged PR and a pushed release tag. + +## Shared Compatibility Patch + +The current compatibility workaround is: + +- `hickory-resolver = "=0.25.2"` +- `tripledoublev/iroh` patch entries under `[patch.crates-io]` + +Keep this workaround during routine Veilid bumps unless the target Veilid changelog or `veilid-tools/Cargo.toml` proves the resolver constraint has been relaxed. If it has been relaxed, remove the workaround as a separate PR unless the user explicitly asks to combine it. + +## Target Discovery + +Use one or both machine-readable checks: + +```bash +git ls-remote --tags https://gitlab.com/veilid/veilid.git +curl -fsS 'https://gitlab.com/api/v4/projects/veilid%2Fveilid/repository/tags?per_page=10' +``` + +Read the raw changelog: + +```bash +curl -fsS https://gitlab.com/veilid/veilid/-/raw/main/CHANGELOG.md +``` + +If fetching from the network fails because of sandboxing, request approval for the same command rather than guessing the target. + +## veilid-iroh-blobs + +Path: + +```bash +cd ../veilid-iroh-blobs +``` + +Important manifest entries to find with `rg`: + +```bash +rg 'version =|veilid-core|hickory-resolver|patch.crates-io|iroh-net|tripledoublev' Cargo.toml +``` + +Expected dependency surfaces: + +- package version, currently in the `0.3.x` line +- `veilid-core` git tag from `https://gitlab.com/veilid/veilid.git` +- `hickory-resolver = "=0.25.2"` +- `[patch.crates-io] iroh-net` from `https://github.com/tripledoublev/iroh.git` + +Routine edit: + +- Update all `veilid-core` tag occurrences to the target Veilid tag. +- Bump the package version, usually patch. +- Keep hickory and iroh patch entries unless the Step 0 gate says otherwise. + +Lockfile refresh candidates: + +```bash +cargo update -p veilid-core +cargo build +cargo test +``` + +If `cargo update -p veilid-core` is ambiguous or insufficient, use `cargo update`, then inspect `Cargo.lock`. + +Release handoff: + +- Open PR against the repo's default branch. +- After merge, tag `v` and push it. +- `save-dweb-backend` cannot start until this tag exists remotely. + +## save-dweb-backend + +Path: + +```bash +cd ../save-dweb-backend +``` + +Important manifest entries to find with `rg`: + +```bash +rg 'version =|veilid-core|veilid-tools|veilid-iroh-blobs|hickory-resolver|patch.crates-io|tripledoublev|RangerMauve|OpenArchive' Cargo.toml +``` + +Expected dependency surfaces: + +- package version, currently in the `0.3.x` line +- `veilid-core` git tag from `https://gitlab.com/veilid/veilid.git` +- `veilid-tools` git tag from `https://gitlab.com/veilid/veilid.git` +- `veilid-iroh-blobs` git tag from `https://github.com/RangerMauve/veilid-iroh-blobs` unless the OpenArchive fork migration has already happened +- `hickory-resolver = "=0.25.2"` +- seven `[patch.crates-io]` iroh workspace crates from `https://github.com/tripledoublev/iroh.git` + +Routine edit: + +- Update all `veilid-core` and `veilid-tools` tag occurrences to the target Veilid tag. +- Update `veilid-iroh-blobs` to the tag pushed from the previous repo. +- Bump the package version, usually patch. +- Keep hickory and iroh patch entries unless the Step 0 gate says otherwise. + +Lockfile refresh candidates: + +```bash +cargo update -p veilid-core -p veilid-tools -p veilid-iroh-blobs +cargo build +cargo nextest run +``` + +If any `-p` target fails because the package is absent or ambiguous, run narrower `cargo update -p` commands or a full `cargo update`, then inspect `Cargo.lock`. + +Smoke-test workflow: + +```bash +cargo nextest list +cargo nextest run 'test(basic_test) | test(test_health_endpoint) | test(test_upload_list_delete)' +``` + +Only use exact test filters after confirming the names still exist. + +Release handoff: + +- Open PR against the repo's default branch. +- After merge, tag `v` and push it. +- `save-rust` cannot start until this tag exists remotely. + +## save-rust + +Path: + +```bash +cd +``` + +Important manifest entries to find with `rg`: + +```bash +rg 'version =|save-dweb-backend|veilid-core|hickory-resolver|patch.crates-io|tripledoublev' Cargo.toml +``` + +Expected dependency surfaces: + +- package name `save` +- package version, currently in the `0.2.x` line +- `save-dweb-backend` git tag from `https://github.com/OpenArchive/save-dweb-backend` +- `veilid-core` git tag from `https://gitlab.com/veilid/veilid.git` +- an additional Android-target `veilid-core` dependency +- `hickory-resolver = "=0.25.2"` +- seven `[patch.crates-io]` iroh workspace crates from `https://github.com/tripledoublev/iroh.git` + +Routine edit: + +- Update all `veilid-core` tag occurrences to the target Veilid tag. +- Update `save-dweb-backend` to the tag pushed from the previous repo. +- Bump the package version, usually patch. +- Keep hickory and iroh patch entries unless the Step 0 gate says otherwise. + +Lockfile refresh candidates: + +```bash +cargo update -p veilid-core -p save-dweb-backend +cargo build +cargo nextest run +``` + +If any `-p` target fails because the package is absent or ambiguous, run narrower `cargo update -p` commands or a full `cargo update`, then inspect `Cargo.lock`. + +Smoke-test workflow: + +```bash +cargo nextest list +cargo nextest run 'test(basic_test) | test(test_health_endpoint) | test(test_upload_list_delete)' +``` + +Only use exact test filters after confirming the names still exist. + +Release: + +- Use a release commit message like `chore: release v0.2.x`. +- Open PR against the repo's default branch. +- After merge, tag `v` and push it. + +## Fork-Origin Migration + +Do this only as a standalone change unless the user explicitly asks otherwise. + +Potential future URLs: + +- `https://github.com/OpenArchive/veilid-iroh-blobs` +- `https://github.com/OpenArchive/iroh.git` + +Migration checklist: + +1. Update the `veilid-iroh-blobs` git URL in `save-dweb-backend`. +2. Update every `[patch.crates-io]` iroh entry in all three repos. +3. Refresh lockfiles without changing Veilid tags. +4. Build and test all affected repos. +5. Open a focused PR that only changes fork origins and lockfile source hashes. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..14ee8b8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,17 @@ +# Agent Guidance + +## Veilid Cross-Repo Upgrades + +For Veilid upgrades, read `.claude/skills/veilid-upgrade/SKILL.md` and `.claude/skills/veilid-upgrade/references/dependency-map.md`, then follow that runbook. + +The `.claude/skills/...` directory is a Claude Code skill location, not a native Codex skill trigger. For Codex, this `AGENTS.md` file is the discoverability pointer. + +Assume the sibling repo layout: + +```text +../veilid-iroh-blobs +../save-dweb-backend +. +``` + +Upgrade in dependency order: `veilid-iroh-blobs`, then `save-dweb-backend`, then `save-rust`. Locate dependency pins with `rg` or package keys, not line numbers. Keep fork-origin migration separate from Veilid version bumps unless the user explicitly asks to combine them. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..d0fc277 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,15 @@ +# Claude Guidance + +## Veilid Cross-Repo Upgrades + +For Veilid upgrades, use the repo-local skill at `.claude/skills/veilid-upgrade/SKILL.md` and read `.claude/skills/veilid-upgrade/references/dependency-map.md` before editing. + +The expected dependency chain is: + +```text +veilid -> veilid-iroh-blobs -> save-dweb-backend -> save-rust +``` + +This checkout is expected to sit beside `../veilid-iroh-blobs` and `../save-dweb-backend`. Upgrade one repo at a time, wait for review/merge, tag the upstream release, then move to the next downstream repo. + +Do not combine the OpenArchive fork-origin migration with a Veilid version bump unless the user explicitly asks. From c5b31e91c6c4044f03a57b931c8b40b97332b6f7 Mon Sep 17 00:00:00 2001 From: vincent Date: Mon, 29 Jun 2026 18:09:42 -0400 Subject: [PATCH 2/5] docs: note OpenArchive fork targets --- .claude/skills/veilid-upgrade/SKILL.md | 11 ++++++++--- .../veilid-upgrade/references/dependency-map.md | 12 ++++++------ 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/.claude/skills/veilid-upgrade/SKILL.md b/.claude/skills/veilid-upgrade/SKILL.md index f243d7d..c54fbe0 100644 --- a/.claude/skills/veilid-upgrade/SKILL.md +++ b/.claude/skills/veilid-upgrade/SKILL.md @@ -23,14 +23,19 @@ Read `references/dependency-map.md` before editing. It contains the repo-specifi ## One-Time Fork Migration -The chain currently depends on personal upstream forks: +The chain historically depended on personal upstream forks: - `RangerMauve/veilid-iroh-blobs` - `tripledoublev/iroh` -Best practice is to fork them under `OpenArchive` and repoint references in a standalone PR before or after the Veilid upgrade. Do not mix that origin migration into the Veilid bump unless the user asks. +OpenArchive forks now exist and should be the long-term dependency sources: -Until the migration is done, operate against the current upstreams listed in the manifests. +- `OpenArchive/veilid-iroh-blobs` +- `OpenArchive/iroh` + +Repoint references in standalone PRs before or after a Veilid upgrade. Do not mix that origin migration into the Veilid bump unless the user asks. + +Until a repo's migration PR is merged, operate against the current upstreams listed in that repo's manifest. ## Step 0: Verify The Target Veilid Tag diff --git a/.claude/skills/veilid-upgrade/references/dependency-map.md b/.claude/skills/veilid-upgrade/references/dependency-map.md index efcdca5..8e00738 100644 --- a/.claude/skills/veilid-upgrade/references/dependency-map.md +++ b/.claude/skills/veilid-upgrade/references/dependency-map.md @@ -30,7 +30,7 @@ The downstream repo must not be updated until the upstream repo has a merged PR The current compatibility workaround is: - `hickory-resolver = "=0.25.2"` -- `tripledoublev/iroh` patch entries under `[patch.crates-io]` +- iroh patch entries under `[patch.crates-io]` Keep this workaround during routine Veilid bumps unless the target Veilid changelog or `veilid-tools/Cargo.toml` proves the resolver constraint has been relaxed. If it has been relaxed, remove the workaround as a separate PR unless the user explicitly asks to combine it. @@ -70,7 +70,7 @@ Expected dependency surfaces: - package version, currently in the `0.3.x` line - `veilid-core` git tag from `https://gitlab.com/veilid/veilid.git` - `hickory-resolver = "=0.25.2"` -- `[patch.crates-io] iroh-net` from `https://github.com/tripledoublev/iroh.git` +- `[patch.crates-io] iroh-net` from `https://github.com/OpenArchive/iroh.git` after fork-origin migration, or the current manifest URL if migration has not landed yet Routine edit: @@ -113,9 +113,9 @@ Expected dependency surfaces: - package version, currently in the `0.3.x` line - `veilid-core` git tag from `https://gitlab.com/veilid/veilid.git` - `veilid-tools` git tag from `https://gitlab.com/veilid/veilid.git` -- `veilid-iroh-blobs` git tag from `https://github.com/RangerMauve/veilid-iroh-blobs` unless the OpenArchive fork migration has already happened +- `veilid-iroh-blobs` git tag from `https://github.com/OpenArchive/veilid-iroh-blobs` after fork-origin migration, or the current manifest URL if migration has not landed yet - `hickory-resolver = "=0.25.2"` -- seven `[patch.crates-io]` iroh workspace crates from `https://github.com/tripledoublev/iroh.git` +- seven `[patch.crates-io]` iroh workspace crates from `https://github.com/OpenArchive/iroh.git` after fork-origin migration, or the current manifest URL if migration has not landed yet Routine edit: @@ -171,7 +171,7 @@ Expected dependency surfaces: - `veilid-core` git tag from `https://gitlab.com/veilid/veilid.git` - an additional Android-target `veilid-core` dependency - `hickory-resolver = "=0.25.2"` -- seven `[patch.crates-io]` iroh workspace crates from `https://github.com/tripledoublev/iroh.git` +- seven `[patch.crates-io]` iroh workspace crates from `https://github.com/OpenArchive/iroh.git` after fork-origin migration, or the current manifest URL if migration has not landed yet Routine edit: @@ -209,7 +209,7 @@ Release: Do this only as a standalone change unless the user explicitly asks otherwise. -Potential future URLs: +OpenArchive fork URLs: - `https://github.com/OpenArchive/veilid-iroh-blobs` - `https://github.com/OpenArchive/iroh.git` From ddb88a3c08ecc73eabed7eb2dcc1c602f09bf22d Mon Sep 17 00:00:00 2001 From: vincent Date: Mon, 29 Jun 2026 18:35:05 -0400 Subject: [PATCH 3/5] docs: fix runbook command defects in veilid-upgrade skill - nextest filter expressions now use -E (a bare quoted string is a substring match and silently runs 0 tests) - save-dweb-backend runs the full nextest suite (its CI does); drop the save-rust-only smoke names that do not exist in that repo - stale-tag verification greps a concrete previous version instead of the no-op literal 0\.5\.x - tag step checks out the default branch first so the tag lands on the merge commit, not the feature branch tip Co-Authored-By: Claude Opus 4.8 --- .claude/skills/veilid-upgrade/SKILL.md | 9 +++++---- .../veilid-upgrade/references/dependency-map.md | 16 ++++++++++------ 2 files changed, 15 insertions(+), 10 deletions(-) diff --git a/.claude/skills/veilid-upgrade/SKILL.md b/.claude/skills/veilid-upgrade/SKILL.md index c54fbe0..d394dc5 100644 --- a/.claude/skills/veilid-upgrade/SKILL.md +++ b/.claude/skills/veilid-upgrade/SKILL.md @@ -98,9 +98,10 @@ cargo test -- --list - Open a PR to the repo's default branch. - Stop and ask the human to review and merge. -6. After merge, tag the release before continuing downstream: +6. After merge, switch to the repo's default branch and fast-forward before tagging — the feature branch does not contain the squash/merge commit, so tagging without checking out the default branch tags the wrong commit: ```bash +git checkout # usually 'main'; veilid-iroh-blobs uses 'default' git pull --ff-only git tag v git push origin v @@ -124,9 +125,9 @@ Tag and push the final `save-rust` release after its PR merges. - `Cargo.lock` in each repo records the expected Veilid commit hash for the target tag. - Downstream repos point at the freshly pushed upstream release tags. - In `save-rust`, verify the new `save-dweb-backend` tag/hash and Veilid hash in `Cargo.lock`. -- Search all three manifests for stale old tags, replacing `OLD_VEILID_REGEX` with the previous Veilid version escaped for regex, for example `0\.5\.5`: +- Search all three manifests for the PREVIOUS Veilid version (the one you upgraded FROM), escaped for regex — it should return nothing. Set `OLD_VEILID` to that concrete version; e.g. for a 0.5.5 → 0.5.6 bump use `0\.5\.5` (the unanchored match also covers the `v0.5.5` tag form): ```bash -OLD_VEILID_REGEX='0\.5\.x' -rg "${OLD_VEILID_REGEX}|v${OLD_VEILID_REGEX}" ../veilid-iroh-blobs/Cargo.toml ../save-dweb-backend/Cargo.toml Cargo.toml +OLD_VEILID='0\.5\.5' +rg "${OLD_VEILID}" ../veilid-iroh-blobs/Cargo.toml ../save-dweb-backend/Cargo.toml Cargo.toml ``` diff --git a/.claude/skills/veilid-upgrade/references/dependency-map.md b/.claude/skills/veilid-upgrade/references/dependency-map.md index 8e00738..0555901 100644 --- a/.claude/skills/veilid-upgrade/references/dependency-map.md +++ b/.claude/skills/veilid-upgrade/references/dependency-map.md @@ -134,14 +134,18 @@ cargo nextest run If any `-p` target fails because the package is absent or ambiguous, run narrower `cargo update -p` commands or a full `cargo update`, then inspect `Cargo.lock`. -Smoke-test workflow: +Test workflow — save-dweb-backend's CI runs the full suite, so run it all. `.config/nextest.toml` already serializes and retries the flaky Veilid P2P/DHT tests: ```bash -cargo nextest list -cargo nextest run 'test(basic_test) | test(test_health_endpoint) | test(test_upload_list_delete)' +cargo nextest run ``` -Only use exact test filters after confirming the names still exist. +To narrow to specific tests, discover names first and pass them as a filter EXPRESSION with `-E`. A bare quoted string WITHOUT `-E` is a substring match and silently runs 0 tests: + +```bash +cargo nextest list +cargo nextest run -E 'test(parse_url_rejects_malformed_url)' +``` Release handoff: @@ -190,11 +194,11 @@ cargo nextest run If any `-p` target fails because the package is absent or ambiguous, run narrower `cargo update -p` commands or a full `cargo update`, then inspect `Cargo.lock`. -Smoke-test workflow: +Smoke-test workflow — match CI's smoke set. Pass the filter as an EXPRESSION with `-E`; without `-E` the quoted string is a substring match and silently runs 0 tests: ```bash cargo nextest list -cargo nextest run 'test(basic_test) | test(test_health_endpoint) | test(test_upload_list_delete)' +cargo nextest run -E 'test(basic_test) | test(test_health_endpoint) | test(test_upload_list_delete)' ``` Only use exact test filters after confirming the names still exist. From 7fca37130d77a445c093c808ccb51ca7af504358 Mon Sep 17 00:00:00 2001 From: vincent Date: Mon, 29 Jun 2026 18:38:11 -0400 Subject: [PATCH 4/5] docs: use verified release remote for tags; clarify wrapper-crate release tags - Tag step no longer assumes 'origin' is the release repo. veilid-iroh-blobs may have origin=RangerMauve and a separate openarchive remote, so confirm with 'git remote -v' and push the tag to the merged-into remote. - Fork-origin migration checklist now distinguishes 'do not change Veilid version tags' from 'you may need to cut new wrapper-crate release tags'; bump the package version and tag a new version rather than moving a tag. Co-Authored-By: Claude Opus 4.8 --- .claude/skills/veilid-upgrade/SKILL.md | 10 ++++++---- .../skills/veilid-upgrade/references/dependency-map.md | 9 +++++---- 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/.claude/skills/veilid-upgrade/SKILL.md b/.claude/skills/veilid-upgrade/SKILL.md index d394dc5..334ccb0 100644 --- a/.claude/skills/veilid-upgrade/SKILL.md +++ b/.claude/skills/veilid-upgrade/SKILL.md @@ -98,13 +98,15 @@ cargo test -- --list - Open a PR to the repo's default branch. - Stop and ask the human to review and merge. -6. After merge, switch to the repo's default branch and fast-forward before tagging — the feature branch does not contain the squash/merge commit, so tagging without checking out the default branch tags the wrong commit: +6. After merge, switch to the repo's default branch and fast-forward before tagging — the feature branch does not contain the squash/merge commit, so tagging without checking out the default branch tags the wrong commit. Do NOT assume `origin` is the release repo: the local `origin` may not point at it (e.g. veilid-iroh-blobs often has `origin` = RangerMauve and a separate `openarchive` remote = OpenArchive). Confirm with `git remote -v` and push the tag to the remote the PR actually merged into: ```bash -git checkout # usually 'main'; veilid-iroh-blobs uses 'default' -git pull --ff-only +git remote -v # identify the release remote (the merged-into repo) +RELEASE_REMOTE=origin # set to the verified release remote, e.g. openarchive +git checkout # usually 'main'; veilid-iroh-blobs uses 'default' +git pull --ff-only "$RELEASE_REMOTE" git tag v -git push origin v +git push "$RELEASE_REMOTE" v ``` The next repo must not point at an upstream tag until that tag exists remotely. diff --git a/.claude/skills/veilid-upgrade/references/dependency-map.md b/.claude/skills/veilid-upgrade/references/dependency-map.md index 0555901..6c21505 100644 --- a/.claude/skills/veilid-upgrade/references/dependency-map.md +++ b/.claude/skills/veilid-upgrade/references/dependency-map.md @@ -220,8 +220,9 @@ OpenArchive fork URLs: Migration checklist: -1. Update the `veilid-iroh-blobs` git URL in `save-dweb-backend`. -2. Update every `[patch.crates-io]` iroh entry in all three repos. -3. Refresh lockfiles without changing Veilid tags. +1. Update the `veilid-iroh-blobs` git URL in `save-dweb-backend` (and any other direct consumer) to the OpenArchive fork. +2. Update every `[patch.crates-io]` iroh entry in all three repos to `OpenArchive/iroh`. +3. Refresh lockfiles so the source hashes repoint to the OpenArchive forks. Do NOT change the **Veilid version tags** — `veilid-core`/`veilid-tools` stay on their current `vX.Y.Z`. 4. Build and test all affected repos. -5. Open a focused PR that only changes fork origins and lockfile source hashes. +5. Keep each repo's diff focused on fork origins + lockfile source hashes — no Veilid version change. +6. Separate from the Veilid tags above, you will likely need to cut **new wrapper-crate release tags** so downstream repos can consume the merged fork-origin commits. Never move an existing pushed tag — instead bump the wrapper package `version` and tag the new version: e.g. release `veilid-iroh-blobs` (bump `version`, tag `v0.3.x`) after its migration merges, then `save-dweb-backend` (bump `version`, tag `v0.3.y`), repointing each downstream git tag the same way the Veilid cascade does. This is a wrapper-crate release bump, distinct from a Veilid version change. From 69774dd6926ea82e33651cdcfcc36a914a7a9d86 Mon Sep 17 00:00:00 2001 From: vincent Date: Mon, 29 Jun 2026 19:00:00 -0400 Subject: [PATCH 5/5] docs: add GitHub Release step to upgrade runbook A pushed git tag does not appear on the Releases page; these repos keep a Release per tag. Add a 'gh release create' step after the tag push, and note that Releases should be created only for tags on the merged default branch, after all PRs for the upgrade have merged. Co-Authored-By: Claude Opus 4.8 --- .claude/skills/veilid-upgrade/SKILL.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/.claude/skills/veilid-upgrade/SKILL.md b/.claude/skills/veilid-upgrade/SKILL.md index 334ccb0..b67aa57 100644 --- a/.claude/skills/veilid-upgrade/SKILL.md +++ b/.claude/skills/veilid-upgrade/SKILL.md @@ -109,6 +109,13 @@ git tag v git push "$RELEASE_REMOTE" v ``` +7. Publish the GitHub Release from that tag. These repos keep a Release per tag, and a pushed git tag does NOT appear on the Releases page on its own. Only create a Release for a tag that is already on the merged default branch (never for an open PR). Match the repo's existing release-title convention: + +```bash +gh release list --repo OpenArchive/ # confirm the title convention, e.g. " vX.Y.Z" +gh release create v --repo OpenArchive/ --title " v" --notes "..." +``` + The next repo must not point at an upstream tag until that tag exists remotely. ## Final save-rust Release @@ -119,7 +126,7 @@ Run the same loop for `save-rust`. Use the repo convention for the release commi chore: release v0.2.x ``` -Tag and push the final `save-rust` release after its PR merges. +After its PR merges, tag and push the final `save-rust` release, then publish the GitHub Release (step 7). Create the Release only once every PR for this upgrade has merged, so it reflects the final merged state. ## Verification