README: Fix legacy import path instructions (#60)
In migrating to Go modules, we had to decide between the import paths
github.com/uber-go/atomic and go.uber.org/atomic. We chose the latter.
As a result of this, users of the legacy import path would get an error
message similar to the following:
github.com/uber-go/atomic: github.com/uber-go/atomic@v1.5.0: parsing go.mod:
module declares its path as: go.uber.org/atomic
but was required as: github.com/uber-go/atomic
We suggested that users of the legacy import path add the following to
their go.mod.
replace github.com/uber-go/atomic => go.uber.org/atomic v1.5.0
This is inaccurate and will result in the following error message:
go.uber.org/atomic@v1.5.0 used for two different module paths
(github.com/uber-go/atomic and go.uber.org/atomic)
This was not detected before because `go mod tidy` works fine with this
`replace` directive. It fails only when it gets to `go build`.
After digging into this more, per section 4.4 of the resolution section
of [How can I resolve "parsing go.mod: unexpected module path" (..)][1],
the correct method of resolving this is to downgrade the legacy import
path to a version prior to the use of Go modules.
[1]: https://github.com/golang/go/wiki/Modules#how-can-i-resolve-parsing-gomod-unexpected-module-path-and-error-loading-module-requirements-errors-caused-by-a-mismatch-between-import-paths-vs-declared-module-identity
So the correct `replace` directive here would be,
replace github.com/uber-go/atomic => github.com/uber-go/atomic v1.4.0
This fix was verified both, locally and by @atibhav21 who first ran into
this.diff --git a/README.md b/README.md
index 3cc368b..ade0c20 100644
--- a/README.md
+++ b/README.md
@@ -8,13 +8,25 @@
$ go get -u go.uber.org/atomic@v1
```
-Note: If you are using Go modules, this package will fail to compile with the
-import path `github.com/uber-go/atomic`. To continue using that import path,
-you will have to add a `replace` directive to your `go.mod`, replacing
-`github.com/uber-go/atomic` with `go.uber.org/atomic`.
+### Legacy Import Path
+
+As of v1.5.0, the import path `go.uber.org/atomic` is the only supported way
+of using this package. If you are using Go modules, this package will fail to
+compile with the legacy import path path `github.com/uber-go/atomic`.
+
+We recommend migrating your code to the new import path but if you're unable
+to do so, or if your dependencies are still using the old import path, you
+will have to add a `replace` directive to your `go.mod` file downgrading the
+legacy import path to an older version.
+
+```
+replace github.com/uber-go/atomic => github.com/uber-go/atomic v1.4.0
+```
+
+You can do so automatically by running the following command.
```shell
-$ go mod edit -replace github.com/uber-go/atomic=go.uber.org/atomic@v1
+$ go mod edit -replace github.com/uber-go/atomic=github.com/uber-go/atomic@v1.4.0
```
## Usage
