Setting aside for the moment the question of whether the documentation could be improved, here is a concrete example that might help.

Sample file structure on my local system, all outside of GOPATH:

    /tmp/playground/hello
    |-- go.mod
    `-- hello.go
    /tmp/playground/goodbye
    |-- go.mod
    `-- goodbye.go

And the contents of /tmp/playground/hello/go.mod:

    module example.com/me/hello

    require (
     example.com/me/goodbye v0.0.0
     rsc.io/quote v1.5.2
    )

    replace example.com/me/goodbye => ../goodbye

See a longer discussion and the rest of the example here (which is a runnable example if you are interested):
https://groups.google.com/d/msg/golang-nuts/1nYoAMFZVVM/eppaRW2rCAAJ

@gopherbot please add label modules

Thank you for the working module solution. Setting aside for the moment whether or not this is the canonical solution moving forward, it breaks when moving the code to the GOPATH, making the code non-backwards compatible. Is there another solution that works without changing the source code files? Otherwise it feels like a missing feature or a bug, instead of "a me not finding the right documentation" problem as I had assumed.

Here is the original problem source updated to work with modules.

~/code/modtest/a: cat a.go
package a

func Hello() string {
	return "Hello"
}
~/code/modtest/a: cat go.mod 
module example.com/me/a
~/code/modtest/a: go build
~/code/modtest/a: cd ../b
~/code/modtest/b: cat b.go 
package main

import (
    "fmt"
    
    "example.com/me/a"
)

func main() {
	fmt.Printf("%s\n", a.Hello())
}
~/code/modtest/b: cat go.mod 
module example.com/me/b

require example.com/me/a v0.0.0

replace example.com/me/a => ../a
~/code/modtest/b: go build
~/code/modtest/b: ./b
Hello

Moving both modules into the GOPATH results in the following:

~/code/src: cd a
~/code/src/a: go build
~/code/src/a: cd ../b
~/code/src/b: go build
b.go:6:2: cannot find package "example.com/me/a" in any of:
	/usr/local/go/src/example.com/me/a (from $GOROOT)
	/Users/rust/code/src/example.com/me/a (from $GOPATH)

If you return to the GOPATH world, then you would place the go source code back where Go 1.10 and earlier would expect it based on the import paths you are using in the code.

E.g., something like $GOPATH/src/example.com/me/a/a.go?

If you don't like that example.com, then you don't need to use it in your go.mod and corresponding import paths.

And sorry if I am misunderstanding; this is all new...

Thank you for your patience, adding just the replace a => ../a works. Thank you!

~/codeold/modtest: cd a
~/codeold/modtest/a: cat a.go 
package a

func Hello() string {
	return "Hello"
}
~/codeold/modtest/a: cat go.mod 
module a
~/codeold/modtest/a: cd ../b
~/codeold/modtest/b: cat b.go
package main

import (
    "fmt"
    "a"
)

func main() {
	fmt.Printf("%s\n", a.Hello())
}
~/codeold/modtest/b: cat go.mod
module b

require a v0.0.0

replace a => ../a

it's important to note, that you need the "require" AND the "replace" in the go.mod file.
I like to add them via the commandline, the commands should be encouraged and documented with examples.

the go mod init command does not populate go.mod with packages it cannot resolve. Therefore you must do:

go mod edit require example.com/post-adressdaten
go mod edit -replace example.com/post-adressdaten=../post-adressdaten/

@klaus

I like to add them via the commandline, the commands should be encouraged and documented with examples.

They are documented under go help mod edit

That a replace requires (!) a require is something that is going to be addressed in Go 1.12 via #26241

I'm going to close this issue on the basis I think all questions have been answered, but please shout it not.

@myitcv how about this case ?

/tmp/modtest1X9IT λ  tree
.
├── cmd
│   └── main.go
├── go.mod
└── handler.go

1 directory, 3 files
/tmp/modtest1X9IT λ  cat go.mod
module modtest

go 1.12
/tmp/modtest1X9IT λ  cat handler.go
package handler

import (
    "fmt"
)

func Handler() {
	fmt.Println("hello")
}
/tmp/modtest1X9IT λ  cat cmd/main.go
package main

import "handler"

func main() {
	// how to call handler.Handler here
	handler.Handler()
}

how to call handler.Handler in cmd/main.go if code is not hosted on github but on cloud storage or private google cloud source repo ?

I'd like to run cmd/main.go like this codelab for testing handler locally

thanks !