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

[r...@golang.org]

Reviewers: golang-dev1,

Message:
Hello golan...@googlegroups.com,

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


Description:
doc/faq: add a FAQ about versioning

Fixes issue 5633.

Please review this at https://codereview.appspot.com/14283044/

Affected files (+39, -0 lines):
M doc/go_faq.html


Index: doc/go_faq.html
===================================================================
--- a/doc/go_faq.html
+++ b/doc/go_faq.html
@@ -1029,6 +1029,45 @@
</li>
</ul>

+<h3 id="get_version">
+How should I manage package versions using "go get"?</h3>
+
+<p>
+"Go get" does not have any explicit concept of package versions.
+Versioning is a source of significant complexity, especially in large code
bases,
+and we are unaware of any approach that works well at scale in a large
enough
+variety of situations to be appropriate to force on all Go users.
+What "go get" and the larger Go toolchain do provide is isolation of
+packages with different import paths.
+For example, the standard library's <code>html/template</code> and
<code>text/template</code>
+coexist even though both are "package template".
+This observation leads to some advice for package authors and package
users.
+</p>
+
+<p>
+As a package author, you should strive to keep the package API backwards
compatible,
+so that someone using today's copy of the package will be able to use
tomorrow's.
+This means, at minimum, not removing exported constants, types, variables,
and functions;
+not changing the type of exported constants, variables, and functions;
+not removing exported fields from exported struct types;
+and not adding or removing exported methods from exported interface types.
+If different functionality is required, add a new name instead of changing
an old one.
+If a complete break with the past is required, create a new package with a
new import path.
+</p>
+
+<p>
+As a package user, perhaps you cannot trust that the package author will
maintain
+backwards compatibility of the API, or perhaps you worry that future
implementation
+tradeoffs might hurt the performance of the package as used in your
application.
+The cleanest solution to this general problem is to make a copy of the
package
+as you want to use it, only updating to a new copy after you have been able
+to run correctness and performance tests ensuring that it still works well
for you.
+It usually works well to record that code under a new import path, making
clear that
+it is a local copy; for example, you might copy "original.com/pkg"
to "you.com/external/original.com/pkg".
+We have not yet added an official tool for this to the standard toolchain,
but users
+have written a few; Keith Rarick's <a
href="https://github.com/kr/goven">goven</a> is one example.
+</p>
+
<h2 id="Pointers">Pointers and Allocation</h2>

<h3 id="pass_by_value">

[r...@golang.org]

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.

https://codereview.appspot.com/14283044/

[a...@golang.org]

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.

https://codereview.appspot.com/14283044/

[Andrew Gerrand]

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

[tommi.v...@gmail.com]

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.

https://codereview.appspot.com/14283044/

[r...@golang.org]

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.

https://codereview.appspot.com/14283044/

[n...@nathany.com]

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.

https://codereview.appspot.com/14283044/

[a...@golang.org]

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

https://codereview.appspot.com/14283044/

[n...@nathany.com]

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.


https://codereview.appspot.com/14283044/

[Andrew Gerrand]

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

[n...@nathany.com]

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).


https://codereview.appspot.com/14283044/

[Andrew Gerrand]

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

[r...@golang.org]

LGTM



https://codereview.appspot.com/14283044/

[Russ Cox]

On Thu, Oct 3, 2013 at 1:31 AM, Andrew Gerrand <a...@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

[r...@golang.org]

*** 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


https://codereview.appspot.com/14283044/

[Rob Pike]

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

[Russ Cox]

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