rebase-onto-upstream

name	rebase-onto-upstream
description	Rebases this Tenstorrent fork of terraform-provider-netbox onto the latest e-breuninger upstream and cuts a new release. Use when the user asks to rebase onto upstream, sync with upstream, pull in upstream changes, update from e-breuninger, or release a new version of the fork.

Rebase onto upstream

This skill encodes the full workflow for bringing the tenstorrent/terraform-provider-netbox fork up to date with e-breuninger/terraform-provider-netbox (the upstream) and producing a verified release.

The fork also depends on a second fork: msollanych-tt/go-netbox of fbreckle/go-netbox, wired in via a replace directive in go.mod. Both forks must be rebased together, in order. See AGENTS.md at the provider repo root for the full fork-management context.

Preconditions

• Both repos are present locally and clean (git status shows no changes):
  • terraform-provider-netbox with remotes origin = tenstorrent/... and upstream = e-breuninger/...
  • go-netbox (typically a sibling directory) with origin = msollanych-tt/... and upstream = fbreckle/...
• gh CLI authenticated against both forks
• Go 1.25+ installed locally
• The user has approved doing the rebase now (don't start without confirmation)

Workflow

Track progress with this checklist:

- [ ] Phase 1: rebase go-netbox master onto upstream/master
- [ ] Phase 1: push and tag new go-netbox version
- [ ] Phase 2: create rebase branch off upstream/master
- [ ] Phase 2: cherry-pick our patches in order, resolve conflicts
- [ ] Phase 2: bump go.mod replace to new go-netbox tag, go mod tidy
- [ ] Phase 2: verify build (go vet, go build, go test -short)
- [ ] Phase 2: push branch + prerelease tag, watch goreleaser CI
- [ ] Phase 2: validate prerelease binary against a real NetBox
- [ ] Phase 3: fast-forward master, push real tag
- [ ] Update AGENTS.md "state at last rebase" section

Phase 1 — Rebase go-netbox first

Order matters: upstream provider features sometimes depend on recent go-netbox changes (e.g. v2 token support depended on WritableToken.Expires omitempty removal).

cd ../go-netbox
git fetch upstream
git checkout master
git rebase upstream/master

Resolve conflicts on our patches. Our changes touch model files (e.g. WritableAvailableIP); upstream changes are usually generated client/model deltas elsewhere.

git push --force-with-lease origin master
git tag -a vX.Y.Z -m "Rebased onto upstream <sha>"
git push origin vX.Y.Z

X.Y.Z should bump the minor version (e.g. v0.3.0 → v0.4.0). Earlier tags used a -tenant-fix suffix; clean tags going forward. Force-pushing master is fine because the provider pins by tag, not branch.

Phase 2 — Rebase the provider

cd ../terraform-provider-netbox
git fetch upstream
git checkout -b rebase-onto-upstream-<MMMYYYY> upstream/master

Cherry-pick our patches in their original order. Get the list with:

git log --oneline master ^upstream/master

Read it bottom-up (oldest first) and cherry-pick in that order:

git cherry-pick <oldest-sha>
git cherry-pick <next-sha>
# ...

Conflict resolution rules

• go.sum conflicts every time. Resolve with git checkout --ours go.sum && git add go.sum. It will be regenerated by go mod tidy later.
• netbox/resource_netbox_available_ip_address.go is the file most likely to have real conflicts (both we and upstream actively touch it). Read both sides, preserve upstream's additions (e.g. custom_fields, DNS case suppression) and our additions (tenant_id) together.
• netbox/resource_netbox_service.go may conflict if upstream touched parent-object handling.
• Cherry-picks sometimes leave stray braces or whitespace. Always run go vet ./... after the cherry-picks.

Bump go-netbox dep

After all cherry-picks land, edit go.mod:

replace github.com/fbreckle/go-netbox => github.com/msollanych-tt/go-netbox vX.Y.Z

Use the new tag from Phase 1. Then:

go mod tidy

Verify locally

go vet ./...
go build ./...
go test -count=1 -short ./netbox/...

If any of these fail, fix them on this branch — either as a new commit or by amending the last cherry-pick. Do not go back and try to amend earlier cherry-picks; the history will get tangled.

If you fix anything in the test file or other patch-related files, amend into the most recent cherry-pick:

git add <files>
git commit --amend --no-edit

Push branch

git push -u origin rebase-onto-upstream-<MMMYYYY>

(Optional) prerelease tag

The release pipeline is the only place we have full cross-platform build coverage. For risky rebases or first-time releases, push an rc tag to dry-run the build:

git tag -a vA.B.C-rc1 -m "Prerelease, rebased on upstream <sha>"
git push origin vA.B.C-rc1

Most of the time you can skip this — dev_overrides against a real NetBox already validated the same code, and the release pipeline either builds or it doesn't (it's deterministic).

Caveat: prerelease tags don't satisfy ~> 5 constraints downstream (SemVer rule). To smoke-test from the registry you'd need to pin exactly. The dev_overrides path is usually faster.

Phase 3 — Cut the real tag

Once the rebase branch passes locally and (optionally) the rc build is green:

git checkout master
git merge --ff-only rebase-onto-upstream-<MMMYYYY>
git push origin master
git tag -a vA.B.C -m "Rebased on upstream <sha> + tenstorrent patches"
git push origin vA.B.C

Watch the release workflow:

gh run watch <run-id> --repo tenstorrent/terraform-provider-netbox --exit-status

Or list runs to find it:

gh run list --repo tenstorrent/terraform-provider-netbox --limit 5

The build takes ~6 minutes. On success, verify all artifacts published:

gh release view vA.B.C --repo tenstorrent/terraform-provider-netbox

Should show zips for darwin/linux/windows × arm64/amd64/386 plus SHA256SUMS + signature.

If the build fails on the real tag, you can't reuse the tag — bump the patch (vA.B.D) and try again. (This is part of why the optional rc step exists.)

Tag scheme: plain vA.B.C semver, monotonically increasing from our own release history. Don't anchor to upstream's version. Confirm with the user what the next patch number should be before tagging.

Phase 4 — Update AGENTS.md

Edit the "Quick reference: state at last rebase" section in AGENTS.md to reflect the new state:

• Upstream sha rebased onto
• Latest go-netbox tag
• Latest provider release tag

Commit this on master:

git add AGENTS.md
git commit -m "docs: update AGENTS.md state at rebase to <new-tag>"
git push origin master

What to never do

• Never push to upstream on either repo (you don't have permission).
• Never edit go.sum by hand — always regenerate with go mod tidy.
• Never reuse a published version tag.
• Never tag without explicit user confirmation of the next patch number to use.
• Never include the replace directive, the release-workflow tweak, or AGENTS.md in a PR opened against upstream e-breuninger.

Cleanup (optional)

After a successful rebase, old rebase-onto-upstream-<old-month> branches can be deleted:

git push origin --delete rebase-onto-upstream-<old-month>
git branch -d rebase-onto-upstream-<old-month>

Confirm with the user before deleting.

Reference

For the broader fork-management context (why two forks exist, what each carried patch does, what's upstreamable, local dev setup), see AGENTS.md at the provider repo root.