Skip to content

docs(cli): modernize "With Go toolchain" install instructions - #1428

Open
shaikn6 wants to merge 1 commit into
golang-migrate:masterfrom
shaikn6:docs/modernize-cli-go-toolchain-install
Open

shaikn6 wants to merge 1 commit into
golang-migrate:masterfrom
shaikn6:docs/modernize-cli-go-toolchain-install

Conversation

@shaikn6

@shaikn6 shaikn6 commented Aug 28, 2026

Copy link
Copy Markdown

What

The With Go toolchain section of cmd/migrate/README.md documented the pre-modules GOPATH workflow under Versioned / Unversioned:

go get -u -d github.com/golang-migrate/migrate/cmd/migrate
cd $GOPATH/src/github.com/golang-migrate/migrate/cmd/migrate
git checkout $TAG
go build -tags 'postgres' ... -o $GOPATH/bin/migrate ...

That path no longer works:

  • go get stopped installing command binaries in Go 1.18 (go get is now for dependency management only).
  • The go get ... github.com/golang-migrate/migrate/cmd/migrate path resolves to the pre-/v4 module and fails with found (v3.5.4+incompatible), but does not contain package … — this is exactly the failure in CLI Install instructions are incorrect for Go 1.16+ #603.
  • $GOPATH/src isn't populated in module mode.

Change

Replace the two blocks with the working go install <pkg>@<version> form — pinned release, @latest, and a multi-driver example — plus a note on where the binary is installed. Drop the two now-orphaned "Go 1.15 and below" notes.

Docs-only; no code touched.

Verified

$ go version
go version go1.26 ...
$ GOBIN=/tmp/bin go install -tags 'postgres mysql file github' \
    github.com/golang-migrate/migrate/v4/cmd/migrate@v4.19.1
$ /tmp/bin/migrate -help   # works, all four drivers listed

Fixes #603

The Versioned/Unversioned blocks documented the pre-modules GOPATH workflow
(go get -u -d, cd $GOPATH/src, git checkout, go build -o). That path is broken
on Go 1.16+, and `go get` stopped installing command binaries in Go 1.18 —
which is the failure reported in golang-migrate#603.

Replace both blocks with the working `go install <pkg>@<version>` form (pinned,
latest, and multi-driver), note where the binary is placed, and drop the now
-orphaned Go 1.15 GOPATH notes. Verified with Go 1.26.

Fixes golang-migrate#603
@shaikn6 shaikn6 closed this Sep 19, 2026
@shaikn6 shaikn6 reopened this Sep 19, 2026
@shaikn6

shaikn6 commented Oct 6, 2026

Copy link
Copy Markdown
Author

Hi maintainers, the only failing check on this PR is the Go 1.25.x test job. The failures are Docker containers timing out on startup (sqlserver and yugabytedb: "timed out waiting for container to get ready"). Go 1.26.x, lint and coverage all pass. This change doesn't touch those drivers. Could someone with write access re-run the failed job? Thanks!

@shaikn6 shaikn6 closed this Oct 7, 2026
@shaikn6 shaikn6 reopened this Oct 7, 2026
@shaikn6 shaikn6 closed this Oct 8, 2026
@shaikn6 shaikn6 reopened this Oct 8, 2026
@coveralls

Copy link
Copy Markdown

Coverage Status

coverage: 54.938%. first build — shaikn6:docs/modernize-cli-go-toolchain-install into golang-migrate:master

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

CLI Install instructions are incorrect for Go 1.16+

2 participants