Grokbase › Groups › Go › golang-dev › December 2012
FAQ
It's been proposed that we include the Go Tour in the Go binary
distributions, removing a step from a typical new user's "getting started"
procedure.

We would just build the gotour binary when building the rest of the
toolchain, and include the tour

Questions: (answers I prefer are marked with an [x])

* Where should the gotour binary live?

/usr/local/go/bin: This will effectively put it in user's path. Convenient,
but heavy-handed? It's unlikely to have a name collision though. [x]

/usr/local/go/pkg/GOOS_GOARCH/gotour: This means you must run "go tool
gotour" to run the tour. Slightly more complicated, but keeps the binary
out of the user's path.

* Where should the gotour content live?

/usr/local/go/tour: the gotour can use the GOROOT baked into to the go tool
to find its content.

* What should the tour packages (pic, tree, etc) live?

In the standard library package tree: possibly the simplest approach.
Appears in godoc, might be confusing/annoying.

Alongside the tour content: would then need the gotour to set a GOPATH
before building tour programs. [x]

* How do we handle content updates?

The tour's content is improved from time to time.

Notify the user that an update is available: The gotour binary could ping
the go-tour project's downloads page to see if there's a newer version of
the tour (or even Go itself) available.

Automatically download and update tour content: Seems like a fun
engineering challenge, but is it worth the effort?

Ignore the issue: Let the user get a new version of the tour with a new
version of Go.


Your input most appreciated.

Andrew

Search Discussions

  • Brad Fitzpatrick at Dec 17, 2012 at 11:44 pm ⇧

    On Mon, Dec 17, 2012 at 3:34 PM, Andrew Gerrand wrote:

    /usr/local/go/pkg/GOOS_GOARCH/gotour: This means you must run "go tool
    gotour" to run the tour. Slightly more complicated, but keeps the binary
    out of the user's path.
    Or just "go tool tour".
  • Andrew Gerrand at Dec 18, 2012 at 3:45 am ⇧

    On 18 December 2012 10:44, Brad Fitzpatrick wrote:
    On Mon, Dec 17, 2012 at 3:34 PM, Andrew Gerrand wrote:

    /usr/local/go/pkg/GOOS_GOARCH/gotour: This means you must run "go tool
    gotour" to run the tour. Slightly more complicated, but keeps the binary
    out of the user's path.
    Or just "go tool tour".
    Good call.
  • Patrick Mylund Nielsen at Dec 17, 2012 at 11:46 pm ⇧
    Do you think a large portion of users would use this local version rather
    than just browse to tour.golang.org? (I know I still google/type
    golang.org/pkg/<foo> all the time, even if I know I have godoc.) A link to
    tour.golang.org is easier to use, IMO. It doesn't get easier than that.

    If so, agree with all your suggestions. (If in stdlib, then the tour
    packages could probably be together under a tour/ folder without too much
    trouble?) For update, it could ping and run 'go get -u'/download the
    content for you if you answer yes, although I'm not sure if the tour really
    deserves this more than other parts of Go. One thing to note is that the
    user might not have write privileges to update the go-tour files, and
    almost certainly won't if the Go installation is shared. Either way I'm
    sure some people would prefer to have a --no-update option.

    If you think that the tour is going to be updated often, then IMO that is
    an argument for keeping it to tour.golang.org, not for doing something
    fancy on the client side.

    On Tue, Dec 18, 2012 at 12:34 AM, Andrew Gerrand wrote:

    It's been proposed that we include the Go Tour in the Go binary
    distributions, removing a step from a typical new user's "getting started"
    procedure.

    We would just build the gotour binary when building the rest of the
    toolchain, and include the tour

    Questions: (answers I prefer are marked with an [x])

    * Where should the gotour binary live?

    /usr/local/go/bin: This will effectively put it in user's path.
    Convenient, but heavy-handed? It's unlikely to have a name collision
    though. [x]

    /usr/local/go/pkg/GOOS_GOARCH/gotour: This means you must run "go tool
    gotour" to run the tour. Slightly more complicated, but keeps the binary
    out of the user's path.

    * Where should the gotour content live?

    /usr/local/go/tour: the gotour can use the GOROOT baked into to the go
    tool to find its content.

    * What should the tour packages (pic, tree, etc) live?

    In the standard library package tree: possibly the simplest approach.
    Appears in godoc, might be confusing/annoying.

    Alongside the tour content: would then need the gotour to set a GOPATH
    before building tour programs. [x]

    * How do we handle content updates?

    The tour's content is improved from time to time.

    Notify the user that an update is available: The gotour binary could ping
    the go-tour project's downloads page to see if there's a newer version of
    the tour (or even Go itself) available.

    Automatically download and update tour content: Seems like a fun
    engineering challenge, but is it worth the effort?

    Ignore the issue: Let the user get a new version of the tour with a new
    version of Go.


    Your input most appreciated.

    Andrew
  • Andrew Gerrand at Dec 18, 2012 at 3:47 am ⇧

    On 18 December 2012 10:46, Patrick Mylund Nielsen wrote:

    Do you think a large portion of users would use this local version rather
    than just browse to tour.golang.org? (I know I still google/type
    golang.org/pkg/<foo> all the time, even if I know I have godoc.) A link
    to tour.golang.org is easier to use, IMO. It doesn't get easier than that.

    The rationale for making the tour installable at all is so that you can
    write programs that block (like the web server example) or take a long time
    to execute. It's also so that you can do the tour on an aeroplane.

    If so, agree with all your suggestions. (If in stdlib, then the tour
    packages could probably be together under a tour/ folder without too much
    trouble?) For update, it could ping and run 'go get -u'/download the
    content for you if you answer yes, although I'm not sure if the tour really
    deserves this more than other parts of Go. One thing to note is that the
    user might not have write privileges to update the go-tour files, and
    almost certainly won't if the Go installation is shared. Either way I'm
    sure some people would prefer to have a --no-update option.
    I'm hesitant to add the tour/ packages to the standard library, as it may
    make them hard to update. Keeping the tour content in a separate place,
    where they are added to GOPATH by the gotour binary, at least makes the
    tour content self-contained and easy to update (the user can just "go get"
    the tour to another GOPATH if they want the latest versions.

    I think we should probably just skip the auto-updating part.

    Andrew
  • Minux at Dec 18, 2012 at 10:02 am ⇧

    On Tue, Dec 18, 2012 at 7:34 AM, Andrew Gerrand wrote:

    It's been proposed that we include the Go Tour in the Go binary
    distributions, removing a step from a typical new user's "getting started"
    procedure.

    We would just build the gotour binary when building the rest of the
    toolchain, and include the tour

    Questions: (answers I prefer are marked with an [x])

    * Where should the gotour binary live?

    /usr/local/go/bin: This will effectively put it in user's path.
    Convenient, but heavy-handed? It's unlikely to have a name collision
    though. [x]
    I think gotour in $PATH is fine. Because this will be what people'd expect
    if they install it using "go get".
    /usr/local/go/pkg/GOOS_GOARCH/gotour: This means you must run "go tool
    gotour" to run the tour. Slightly more complicated, but keeps the binary
    out of the user's path.
    it's up to you, I think this is also acceptable (go tool tour), the only
    drawback is that we need to document this
    as user are not likely to find this themselves.
    * Where should the gotour content live?

    /usr/local/go/tour: the gotour can use the GOROOT baked into to the go
    tool to find its content.
    I suggest $GOROOT/misc/tour.
    we can rearrange it to look like a GOPATH.
    * What should the tour packages (pic, tree, etc) live?

    In the standard library package tree: possibly the simplest approach.
    Appears in godoc, might be confusing/annoying.

    Alongside the tour content: would then need the gotour to set a GOPATH
    before building tour programs. [x]
    i think putting them in $GOROOT/misc/tour is ok.
    * How do we handle content updates?

    The tour's content is improved from time to time.

    Notify the user that an update is available: The gotour binary could ping
    the go-tour project's downloads page to see if there's a newer version of
    the tour (or even Go itself) available.
    I think this is good idea. We can still package a go-tour source package in
    the download page that
    matches the directory structure in $GOROOT/misc/tour, and all user need to
    do is to extract it.
    We can make the (go)tour binary in Go binary distribution do a little more,
    if it finds updated
    content in $GOROOT/misc/tour, it will build it in a temp. dir, and run it
    (optionally output instructions
    on how to update the (go)tour binary).
    Automatically download and update tour content: Seems like a fun
    engineering challenge, but is it worth the effort?
    I prefer notify the user when updates are available, but don't do it
    automatically (unless perhaps the
    user starts gotour with -update flag).
    Ignore the issue: Let the user get a new version of the tour with a new
    version of Go.
    at least we can notify the user the availability of new version, it won't
    take much effort to do
    provided we package go-tour source packages as tar.gz in download page of
    go-tour project.

    One alternatives is just notify the user when updates available, and tell
    them to use 'go get' to
    install it, we don't need to support update the in-tree copy of gotour (it
    seems this approach
    favors the "go tool tour" way of invoking the in-tree copy).
  • J L Vanderzwan at Dec 18, 2012 at 2:44 pm ⇧

    On Tuesday, 18 December 2012 11:02:00 UTC+1, minux wrote:

    it's up to you, I think this is also acceptable (go tool tour), the only
    drawback is that we need to document this
    as user are not likely to find this themselves.
    Maybe you already have this in mind when you talk about documentation, but
    it might also be a good idea to end the installation (from binary or
    source) with something along the lines of:

    "To start learning Go, run "go tool tour" and open your browser at
    localhost:6060"
  • Minux at Dec 18, 2012 at 4:09 pm ⇧

    On Tue, Dec 18, 2012 at 10:44 PM, wrote:
    On Tuesday, 18 December 2012 11:02:00 UTC+1, minux wrote:

    it's up to you, I think this is also acceptable (go tool tour), the only
    drawback is that we need to document this
    as user are not likely to find this themselves.
    Maybe you already have this in mind when you talk about documentation, but
    it might also be a good idea to end the installation (from
    I was assuming that after install a binary distribution, people tend to
    look at what it adds to $PATH
    by, perhaps, typing go and press TAB TAB.
    binary or source) with something along the lines of:

    "To start learning Go, run "go tool tour" and open your browser at
    localhost:6060"
    after thinking about possible conflicts with user installed go-tour, i
    think 'go tool tour' is more
    acceptable now.
  • J L Vanderzwan at Dec 18, 2012 at 4:43 pm ⇧

    On Tuesday, 18 December 2012 17:08:43 UTC+1, minux wrote:

    I was assuming that after install a binary distribution, people tend to
    look at what it adds to $PATH

    Speaking as an idiot who never thought of doing this before, I think
    explicitly telling the user about the existence of a local gotour would be
    a simple way to make this a bit more idiot-proof.

    In general it's probably good to aim at uninformed users when thinking of
    how and why to integrate this - after all: it's an educational tool meant
    for people new to Go, right after a fresh installation.
  • Francesc Campoy Flores at Dec 18, 2012 at 4:07 pm ⇧
    Hi,
    Francesc Campoy Flores | Go Developer Relations | campoy@google.com |
    415-990-4126


    On Tue, Dec 18, 2012 at 2:02 AM, minux wrote:

    On Tue, Dec 18, 2012 at 7:34 AM, Andrew Gerrand wrote:

    It's been proposed that we include the Go Tour in the Go binary
    distributions, removing a step from a typical new user's "getting started"
    procedure.

    We would just build the gotour binary when building the rest of the
    toolchain, and include the tour

    Questions: (answers I prefer are marked with an [x])

    * Where should the gotour binary live?

    /usr/local/go/bin: This will effectively put it in user's path.
    Convenient, but heavy-handed? It's unlikely to have a name collision
    though. [x]
    I think gotour in $PATH is fine. Because this will be what people'd expect
    if they install it using "go get".
    This is not the general case. For example, my $GOPATH/bin directory is not
    in my $PATH variable, so I don't expect to have anything new.

    I think that something like "go tool tour" or even better "go tour" would
    be more consistent with the rest of the tools.
    /usr/local/go/pkg/GOOS_GOARCH/gotour: This means you must run "go tool
    gotour" to run the tour. Slightly more complicated, but keeps the binary
    out of the user's path.
    it's up to you, I think this is also acceptable (go tool tour), the only
    drawback is that we need to document this
    as user are not likely to find this themselves.
    * Where should the gotour content live?

    /usr/local/go/tour: the gotour can use the GOROOT baked into to the go
    tool to find its content.
    I suggest $GOROOT/misc/tour.
    we can rearrange it to look like a GOPATH.
    * What should the tour packages (pic, tree, etc) live?

    In the standard library package tree: possibly the simplest approach.
    Appears in godoc, might be confusing/annoying.

    Alongside the tour content: would then need the gotour to set a GOPATH
    before building tour programs. [x]
    i think putting them in $GOROOT/misc/tour is ok.
    * How do we handle content updates?

    The tour's content is improved from time to time.

    Notify the user that an update is available: The gotour binary could ping
    the go-tour project's downloads page to see if there's a newer version of
    the tour (or even Go itself) available.
    I think this is good idea. We can still package a go-tour source package
    in the download page that
    matches the directory structure in $GOROOT/misc/tour, and all user need to
    do is to extract it.
    We can make the (go)tour binary in Go binary distribution do a little
    more, if it finds updated
    content in $GOROOT/misc/tour, it will build it in a temp. dir, and run it
    (optionally output instructions
    on how to update the (go)tour binary).
    Automatically download and update tour content: Seems like a fun
    engineering challenge, but is it worth the effort?
    I prefer notify the user when updates are available, but don't do it
    automatically (unless perhaps the
    user starts gotour with -update flag).
    Ignore the issue: Let the user get a new version of the tour with a new
    version of Go.
    at least we can notify the user the availability of new version, it won't
    take much effort to do
    provided we package go-tour source packages as tar.gz in download page of
    go-tour project.

    One alternatives is just notify the user when updates available, and tell
    them to use 'go get' to
    install it, we don't need to support update the in-tree copy of gotour (it
    seems this approach
    favors the "go tool tour" way of invoking the in-tree copy).
  • Minux at Dec 18, 2012 at 4:12 pm ⇧

    On Wed, Dec 19, 2012 at 12:07 AM, Francesc Campoy Flores wrote:

    This is not the general case. For example, my $GOPATH/bin directory is not
    in my $PATH variable, so I don't expect to have anything new.

    I think that something like "go tool tour" or even better "go tour" would
    be more consistent with the rest of the tools.
    could we extend the go command for "go tour"? if not, i think "go tool
    tour" is our best choice so far.
  • Andrew Gerrand at Dec 18, 2012 at 10:10 pm ⇧

    On 19 December 2012 03:12, minux wrote:
    On Wed, Dec 19, 2012 at 12:07 AM, Francesc Campoy Flores <
    campoy@google.com> wrote:
    This is not the general case. For example, my $GOPATH/bin directory is
    not in my $PATH variable, so I don't expect to have anything new.

    I think that something like "go tool tour" or even better "go tour" would
    be more consistent with the rest of the tools.
    could we extend the go command for "go tour"? if not, i think "go tool
    tour" is our best choice so far.
    I don't think we should make the go command aware of the tour. I don't want
    to bring the tour into the core, just the binary distributions.

    "go tool tour" seems fine. The instructions on tour.golang.org would say
    "Want to run the tour locally? Install a [binary distribution] and run "go
    tool tour"."

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupgolang-dev @
categoriesgo
postedDec 17, '12 at 11:34p
activeDec 18, '12 at 10:10p
posts12
users6
websitegolang.org

6 users in discussion

Andrew Gerrand: 4 posts Minux: 3 posts J L Vanderzwan: 2 posts Patrick Mylund Nielsen: 1 post Brad Fitzpatrick: 1 post Francesc Campoy Flores: 1 post

Content

People

Support

Translate

site design / logo © 2022 Grokbase