Skip to content

docs: Turn MIGRATION.md into a per-service runbook - #70

Merged
duynhne merged 1 commit into
mainfrom
docs/migration-runbook
Aug 7, 2026
Merged

docs: Turn MIGRATION.md into a per-service runbook#70
duynhne merged 1 commit into
mainfrom
docs/migration-runbook

Conversation

@duynhne

@duynhne duynhne commented Aug 7, 2026

Copy link
Copy Markdown
Contributor

Rewrites the migration guide from the freshly pulled main of all ten services, for whoever executes the migration (docs-only — no service repo is touched).

Highlights

  • Telemetry safety stated with evidence: the entire v0.35.0→v0.36.0 code delta is one internal grpcx trace-id helper (identical output, test-pinned) + the go 1.26.0 directive; every obsx/zapx/grpcx symbol services actually use is listed as unchanged. Post-deploy telemetry checklist covers stdout trace_id, OTLP log correlation, trace flow, east-west continuity, db.client.operation.duration + obsx.DurationBuckets histograms, profiling, and shutdown flush — with the pre-existing auth-service TraceContext gap called out so it isn't mistaken for a regression.
  • Corrected module map: payment needs 9 modules (authmw, grpcx, proto, idempotency on top of the floor), not the 6 the old doc implied. Verified per-service via grep, with the grep included so the code stays the source of truth.
  • Checklist per service PR: delete (never edit) the old require — no root v0.36.0 exists; add the module block; replace the now-dead ../pkg local-dev trailer with per-module lines; group github.com/duynhlab/pkg/* in dependabot.yml in the same PR; tidy/build/test/integration; grep guard; CI green.
  • Rollback + canary order (auth first with a soak; order/checkout last).

🤖 Generated with Claude Code

Rewritten from the live main of all ten services: corrected module
map (payment needs 9 modules incl. authmw/grpcx/proto), per-service
go.mod facts, a checklist per migration PR (go.mod + go.sum +
dependabot groups only, never a .go file), a post-deploy telemetry
verification checklist with the auth TraceContext outlier called
out, rollback, canary order, and the gotchas that bite scripted
edits (no root v0.36.0 tag, product's require on line 7, dead
replace trailers, daily ungrouped Dependabot).
@sonarqubecloud

sonarqubecloud Bot commented Aug 7, 2026

Copy link
Copy Markdown

@duynhne
duynhne merged commit fea6e99 into main Aug 7, 2026
11 checks passed
@duynhne
duynhne deleted the docs/migration-runbook branch August 7, 2026 09:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant