| name | update-fsc |
|---|---|
| description | Upgrade Panurus's fabric-smart-client dependency to the latest main commit, resolve API/lint breakage until `make checks` is clean, then open a PR. Trigger: /update-fsc |
| trigger | /update-fsc |
Panurus depends on github.com/hyperledger-labs/fabric-smart-client (FSC) across
every Go module in the repo, pinned to a main-branch pseudo-version (e.g.
v0.14.3-0.20260716152906-60a85d843ab6). This runbook is a reusable, agent-agnostic
procedure — for a human or an AI agent — to bump that dependency to the latest FSC
main commit, absorb any resulting API changes, and get the repo's checks green.
This doc is the single source of truth. In Claude Code it is also exposed as the
/update-fsc skill via a symlink at .claude/skills/update-fsc/SKILL.md.
- Working tree is clean:
git statusshows nothing to commit. If not, stash (git stash -u) or commit first — do not discard existing work. ghis authenticated (gh auth status) — needed only at the very end, to open the PR.- Network access to
github.com/hyperledger-labs/fabric-smart-client.
git fetch origin
SHA=$(git ls-remote https://github.com/hyperledger-labs/fabric-smart-client.git refs/heads/main | cut -f1)
git checkout -b fsc-update-${SHA:0:12} origin/mainUse the existing update-dep Makefile target (Makefile:304). It walks every
non-vendor go.mod in the repo, runs go get <DEP>@<VER> wherever that module is a
dependency, and finishes with make tidy.
make update-dep DEP=github.com/hyperledger-labs/fabric-smart-client VER=$SHA
make update-dep DEP=github.com/hyperledger-labs/fabric-smart-client/integration VER=$SHABoth runs are required: /integration is a separate Go module path inside the FSC
repo, and update-dep's matching (go list -m all | grep "^$(DEP) ") only catches
modules whose require line starts with the exact DEP string. go get module@<sha>
resolves the commit hash into the correct pseudo-version automatically.
Two FSC sub-modules are separate Go modules, pinned by replace in
token/services/storage/db/kvs/hashicorp and cmd/tokengen and required indirectly elsewhere:
github.com/hyperledger-labs/fabric-smart-client/platform/fabric/services/state/cc/querygithub.com/hyperledger-labs/fabric-smart-client/platform/view/services/comm/host/libp2p
FSC tags them on the same commit as each release (v0.28.0 is one commit for the root
module and both sub-modules), and FSC core and its libp2p host can change together, so
they must be kept on the same tag as core. So:
- Tagged release (
VER=vX.Y.Z): bump both sub-modules to the same tag. Edit thereplacelines inhashicorpandtokengenby hand, rungo get <sub-module>@vX.Y.Zin every other module that lists them, thenmake tidy. Confirm withgrep -rn "cc/query\|host/libp2p" --include=go.mod .that no old tag is left. - Pseudo-version off
main: keep them on the latest FSC tag that is not newer than the target commit, unless a later step's build error demands otherwise.
FSC's own Makefile pins the Fabric/Fabric-X versions its integration-test tooling
(binaries, Docker images) is built and tested against — currently FABRIC_VERSION,
FABRIC_TWO_DIGIT_VERSION (derived from it), FABRIC_X_TOOLS_VERSION, and
FABRIC_X_COMMITTER_VERSION, declared near the top under # pinned versions.
Panurus's root Makefile (lines 1-7) and fabricx.mk mirror these same variables
independently — they are not inherited from the Go module, so a bump can silently
leave Panurus testing against a stale Fabric/Fabric-X version even though the code
compiles fine. This matters specifically for integration tests, which are what
actually exercise the pinned binaries/images.
GOMODCACHE=$(go env GOMODCACHE)
FSC_MK="$GOMODCACHE/github.com/hyperledger-labs/fabric-smart-client@$(cd . && go list -m -f '{{.Version}}' github.com/hyperledger-labs/fabric-smart-client)/Makefile"
grep -n "^FABRIC_VERSION\|^FABRIC_CA_VERSION\|^FABRIC_TWO_DIGIT_VERSION\|^FABRIC_X_TOOLS_VERSION\|^FABRIC_X_COMMITTER_VERSION" "$FSC_MK"
grep -n "^FABRIC_VERSION\|^FABRIC_CA_VERSION\|^FABRIC_TWO_DIGIT_VERSION\|^FABRIC_X_TOOLS_VERSION\|^FABRIC_X_COMMITTER_VERSION" Makefile fabricx.mkFor each variable present in both files, bump Panurus's value to match FSC's if they
differ. FABRIC_CA_VERSION is Panurus-only (FSC's install-fabric-bins target doesn't
take a CA version) — leave it alone unless the FSC diff explicitly touches fabric-ca.
Also diff the Docker image references FSC's Makefile pulls for these same
versions (fabric-baseos, fabric-ccenv, fabric-x-committer-test-node targets) —
registry host (e.g. ghcr.io/hyperledger/... vs. plain hyperledger/... on Docker
Hub) and image names can change independently of the version numbers. Compare against
Panurus's fabric-docker-images target in Makefile and fabricx-docker-images in
fabricx.mk, and update the docker pull/docker tag lines to match FSC's source if
they've drifted.
For every module in GO_MODULES (see GO_MODULES in the Makefile for the current list — today:
. integration token/services/storage/db/kvs/hashicorp cmd/artifactgen cmd/tokengen cmd/token_validation_service cmd/skicleanup cmd/tokendiag cmd/node x/token/services/network/evm):
(cd <module-dir> && go build ./... && go vet -all ./...)go vet also type-checks _test.go files, catching test-only breakage that go build
misses.
For each error:
- Read the FSC symbol's new signature/doc:
go doc <package>.<Symbol>, or read the source directly under$(go env GOMODCACHE)/github.com/hyperledger-labs/fabric-smart-client@<pseudo-version>/....go env GOMODCACHEis the read-only module cache; do not edit files there — update the call site in this repo instead. - Make the minimal, surgical change needed at the call site — do not refactor
unrelated code (project convention, see
AGENTS.md). - If an FSC interface used by a
counterfeitermock changed shape, regenerate mocks:go generate ./.... - Re-run step 4 until
go buildandgo vetare clean in every module.
make lint-auto-fix
make checksmake checks runs: licensecheck gofmt goimports govet gofix misspell ineffassign staticcheck govulncheck protos-lint buf-format tidy-check (see checks.mk). Fix
whatever it flags and re-run until it passes cleanly. Do not skip or silence
individual checks.
govulncheck findings with no upstream fix are tracked in
ci/govulncheck-allowlist.txt, not silenced ad hoc. If this FSC bump changes
which vulnerable transitive dependency (e.g. a libp2p dependency) is reachable — a fix ships upstream, the call
path disappears, or a new reachable finding appears — update the allowlist
file accordingly instead of leaving it stale or bypassing the check.
make unit-tests
make unit-tests-race # preferred when time allowsFix any regression the dependency bump introduced. Integration tests
(make integration-tests-*) are heavy (Docker, Fabric binaries) and CI-gated — run
them locally only if the environment (FAB_BINS, Docker images) is already set up;
otherwise note in the PR that they're expected to run in CI.
One signed-off commit:
git add -A
git commit -s -m "chore(deps): bump fabric-smart-client to ${SHA:0:12}"Include the old → new pseudo-version in the commit body. Never introduce
fmt.Errorf/fmt for error construction in any file you touch — use
github.com/hyperledger-labs/fabric-smart-client/pkg/utils/errors per project
convention.
Do not push or open a PR without the user's explicit go-ahead, per AGENTS.md.
Report what changed and that make checks / make unit-tests are green, and wait for
confirmation.
If make checks (or the build) cannot be made clean, do not open a PR — report the
remaining blockers to the user instead of pushing broken state.
git push -u origin fsc-update-${SHA:0:12}
gh pr create --base main \
--title "chore(deps): bump fabric-smart-client to ${SHA:0:12}" \
--assignee @me \
--label "dep update" \
--milestone "$(gh api repos/LFDT-Panurus/panurus/milestones --jq '.[] | select(.state=="open") | .title' | head -1)" \
--project "Panurus" \
--body "Updates github.com/hyperledger-labs/fabric-smart-client to the latest main commit (${SHA}).
- Ran \`make checks\` and \`make unit-tests\` — both clean.
- <call out any notable API-adaptation changes here>"Routine dependency bumps in this repo have shipped both with and without a linked issue — open one only if the maintainer wants extra tracking for this run.