From 6e33981424a8e2aeaff776c1e1e5638aa0e67752 Mon Sep 17 00:00:00 2001
From: Abhinav Gupta <abg@uber.com>
Date: Mon, 4 Nov 2019 14:55:58 -0800
Subject: [PATCH] README: Fix legacy import path instructions

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.
---
 README.md | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 3cc368b..ade0c20 100644
--- a/README.md
+++ b/README.md
@@ -8,13 +8,25 @@ Simple wrappers for primitive types to enforce atomic access.
 $ 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