code review 14283044: doc/faq: add a FAQ about versioning

doc/faq: add a FAQ about versioning

Fixes issue 5633.

[rsc, 2013-10-02 17:07:45]

Hello golang-dev@googlegroups.com,

I'd like you to review this change to
https://code.google.com/p/go/

[r, 2013-10-02 22:50:41]

https://codereview.appspot.com/14283044/diff/2001/doc/go_faq.html
File doc/go_faq.html (right):

https://codereview.appspot.com/14283044/diff/2001/doc/go_faq.html#newcode1049
doc/go_faq.html:1049: so that someone using today's copy of the package will be
able to use tomorrow's.
this really only applies if your package has users, and most don't. also it
would be nice to tone down the use of the second person. state the facts, not
the recipe. plus it's long and repetitive.

Packages intended for public use should try to maintain backwards compatibility
as they evolve.
The <link>Go 1 compatibility guidelines</link> are a good reference here: don't
remove exported names,
encourage tagged composite literals, and so on.
If different functionality is required, add a new name instead of changing an
old one.
If a complete break is required, create a new package with a new import path.

https://codereview.appspot.com/14283044/diff/2001/doc/go_faq.html#newcode1059
doc/go_faq.html:1059: As a package user, perhaps you cannot trust that the
package author will maintain
If you're using an externally supplied package and worry that it might change in
unexpected ways,
the simplest solution is to copy it to your local repository.
(This is the approach Google takes internally.)
Store the copy under a new important path that identifies it as a local copy.
For example..... <what you have>
Keith Rarick's goven package is one tool to help automate this process.

[Tv, 2013-10-02 22:56:33]

https://codereview.appspot.com/14283044/diff/2001/doc/go_faq.html
File doc/go_faq.html (right):

https://codereview.appspot.com/14283044/diff/2001/doc/go_faq.html#newcode1065
doc/go_faq.html:1065: It usually works well to record that code under a new
import path, making clear that
I'm not thrilled about official FAQ recommending import path rewriting. Creating
a GOPATH with the correct contents is much less disruptive to the actual source
code; it boils down to "this import path, at this version (, overriding the
repository location to use a local mirror)".

[adg, 2013-10-03 00:06:12]

https://codereview.appspot.com/14283044/diff/2001/doc/go_faq.html
File doc/go_faq.html (right):

https://codereview.appspot.com/14283044/diff/2001/doc/go_faq.html#newcode1065
doc/go_faq.html:1065: It usually works well to record that code under a new
import path, making clear that
On 2013/10/02 22:56:33, Tv wrote:
> "this import path, at this version (, overriding the
> repository location to use a local mirror)".

I don't see how this is a better situation. A careless "go get -u" could
irretrievably hose your entire state. At least the suggestion in this change
(copying package code to a new import path) is reliable and well-tested. (We do
this for camlistore and also internally at Google, and it works well.)

https://codereview.appspot.com/14283044/diff/2001/doc/go_faq.html#newcode1068
doc/go_faq.html:1068: have written a few; Keith Rarick's <a
href="https://github.com/kr/goven">goven</a> is one example.
Is it really worth calling Keith out by name? The link to the tool should
suffice.

[Tv, 2013-10-03 00:14:38]

On 2013/10/03 00:06:12, adg wrote:
> I don't see how this is a better situation. A careless "go get -u" could
> irretrievably hose your entire state. At least the suggestion in this change
> (copying package code to a new import path) is reliable and well-tested. (We
do
> this for camlistore and also internally at Google, and it works well.)

That's not "irretrievably" in my mind, it's easily fixable. Having a tool to
make your GOPATH to come to compliance with a manifest sounds a lot better to me
than rewriting all the source code you want to use.

And a careless "git pull" will do the same as a careless "go get -u", anyway.

Alternative angle: any setup that keeps multiple repos and is not based on some
sort of a manifest list of desired packages and versions will miss the need to
upgrade a repo. And putting everything into a single repo is a pretty bad idea,
for general use.

What you want is a specific combination of versions of several packages,
possibly forked. Just "tips of my local repos" isn't quite the same. I fail to
see how that's achievable without a manifest listing what the goal is.

[adg, 2013-10-03 00:20:32]

This CL is really not the place to rehash discussions about the best
approach.

Maybe this FAQ entry should link to a wiki page that lists various
approaches.

But I am fine with the approach recommended in this change, because it does
not introduce new mechanisms (like the manifest file). It would be a bad
idea for us to recommend an unproven approach.

Andrew

[rsc, 2013-10-03 01:51:16]

PTAL

https://codereview.appspot.com/14283044/diff/2001/doc/go_faq.html
File doc/go_faq.html (right):

https://codereview.appspot.com/14283044/diff/2001/doc/go_faq.html#newcode1049
doc/go_faq.html:1049: so that someone using today's copy of the package will be
able to use tomorrow's.
On 2013/10/02 22:50:42, r wrote:
> this really only applies if your package has users, and most don't. also it
> would be nice to tone down the use of the second person. state the facts, not
> the recipe. plus it's long and repetitive.
> 
> Packages intended for public use should try to maintain backwards
compatibility
> as they evolve.
> The <link>Go 1 compatibility guidelines</link> are a good reference here:
don't
> remove exported names,
> encourage tagged composite literals, and so on.
> If different functionality is required, add a new name instead of changing an
> old one.
> If a complete break is required, create a new package with a new import path.

Done.

https://codereview.appspot.com/14283044/diff/2001/doc/go_faq.html#newcode1059
doc/go_faq.html:1059: As a package user, perhaps you cannot trust that the
package author will maintain
On 2013/10/02 22:50:42, r wrote:
> If you're using an externally supplied package and worry that it might change
in
> unexpected ways,
> the simplest solution is to copy it to your local repository.
> (This is the approach Google takes internally.)
> Store the copy under a new important path that identifies it as a local copy.
> For example..... <what you have>
> Keith Rarick's goven package is one tool to help automate this process.

Done.

https://codereview.appspot.com/14283044/diff/2001/doc/go_faq.html#newcode1065
doc/go_faq.html:1065: It usually works well to record that code under a new
import path, making clear that
On 2013/10/02 22:56:33, Tv wrote:
> I'm not thrilled about official FAQ recommending import path rewriting.
Creating
> a GOPATH with the correct contents is much less disruptive to the actual
source
> code; it boils down to "this import path, at this version (, overriding the
> repository location to use a local mirror)".

The content is really not up for discussion in this CL. This is our (the Go
team's) answer, based on our experience and how we solve the problem in our own
work. You are certainly welcome to your own answer, but not here.

https://codereview.appspot.com/14283044/diff/2001/doc/go_faq.html#newcode1068
doc/go_faq.html:1068: have written a few; Keith Rarick's <a
href="https://github.com/kr/goven">goven</a> is one example.
On 2013/10/03 00:06:12, adg wrote:
> Is it really worth calling Keith out by name? The link to the tool should
> suffice.

Especially with the shorter text Rob suggested, using Keith's name makes clear
that it's his tool and not ours, which both gives him credit and makes clear
that it's not an official part of the Go toolchain.

[nathany, 2013-10-03 02:07:04]

https://codereview.appspot.com/14283044/diff/13001/doc/go_faq.html
File doc/go_faq.html (right):

https://codereview.appspot.com/14283044/diff/13001/doc/go_faq.html#newcode1058
doc/go_faq.html:1058: Store the copy under a new import path that identifies it
as a local copy.
I'm happy with the Go Team recommending the approach used internally at Google
in the FAQ, though I think I'd prefer the details of the approach and specific
tools be provided via a Wiki page.

[adg, 2013-10-03 02:47:31]

LGTM

https://codereview.appspot.com/14283044/diff/13001/doc/go_faq.html
File doc/go_faq.html (right):

https://codereview.appspot.com/14283044/diff/13001/doc/go_faq.html#newcode1052
doc/go_faq.html:1052: If a complete break is required, create a new package with
a new import path.</p>
</p> on next line please

[nathany, 2013-10-03 05:10:20]

On 2013/10/03 02:47:31, adg wrote:
> LGTM

As mentioned in issue 5633, there is a new mailing list dedicated to this topic
if you would like to link it from the FAQ or associated Wiki page:
https://groups.google.com/forum/#!forum/go-package-management

In particular, you may appreciate Keith Rarick's comments on his own Goven tool
vs. his experience with Godeps. 
https://groups.google.com/d/msg/go-package-management/_CjIePh-BC4/9QxLtFAgXpQJ

I'll reaffirm my previous suggestion to link to the Wiki when recommending
specific tools... at least for now.

[adg, 2013-10-03 05:14:27]

I don't think such a wiki page exists. Want to create one?


On 3 October 2013 15:10, <nj@nathany.com> wrote:

> On 2013/10/03 02:47:31, adg wrote:
>
>> LGTM
>>
>
> As mentioned in issue 5633, there is a new mailing list dedicated to
> this topic if you would like to link it from the FAQ or associated Wiki
> page:
>
https://groups.google.com/**forum/#!forum/go-package-**management<https://gro...
>
> In particular, you may appreciate Keith Rarick's comments on his own
> Goven tool vs. his experience with Godeps.
> https://groups.google.com/d/**msg/go-package-management/_**
>
CjIePh-BC4/9QxLtFAgXpQJ<https://groups.google.com/d/msg/go-package-management/_CjIePh-BC4/9QxLtFAgXpQJ>
>
> I'll reaffirm my previous suggestion to link to the Wiki when
> recommending specific tools... at least for now.
>
>
>
https://codereview.appspot.**com/14283044/<https://codereview.appspot.com/142...
>

[nathany, 2013-10-03 05:29:16]

On 2013/10/03 05:14:27, adg wrote:
> I don't think such a wiki page exists. Want to create one?

Here is a Wiki page that can be linked to from the FAQ.

https://code.google.com/p/go-wiki/wiki/PackageVersioning

It needs more work to classify the various tools (eg. code vendoring tools like
Goven).

[adg, 2013-10-03 05:31:56]

Russ, want to update with a link to "/wiki/PackageVersioning"? (Will work
with the latest godocs)

[r, 2013-10-03 06:03:23]

LGTM

[rsc, 2013-10-03 13:18:03]

On Thu, Oct 3, 2013 at 1:31 AM, Andrew Gerrand <adg@golang.org> wrote:

> Russ, want to update with a link to "/wiki/PackageVersioning"? (Will work
> with the latest godocs)
>

I added

<p>
The <a href="/wiki/PackageVersioning">PackageVersioning</a> wiki page
collects
additional tools and approaches.
</p>

but really under duress. I object to the entire idea of a "go package
management" mailing list. The only thing that I see coming out of that is
complexity.

Russ

[rsc, 2013-10-03 13:18:56]

*** Submitted as https://code.google.com/p/go/source/detail?r=7aaac307aa0e ***

doc/faq: add a FAQ about versioning

Fixes issue 5633.

R=golang-dev, r, tommi.virtanen, adg, nj
CC=golang-dev
https://codereview.appspot.com/14283044

[r, 2013-10-03 16:23:58]

Take out the link to that Wiki page, please. It encourages thinking about
the problem in the wrong way.

[rsc, 2013-10-03 16:58:06]

On Thu, Oct 3, 2013 at 12:23 PM, Rob Pike <r@golang.org> wrote:

> Take out the link to that Wiki page, please. It encourages thinking about
> the problem in the wrong way.
>

https://codereview.appspot.com/14345043