Versioned URLs for GitHub with gonuts.org

[Gustavo Niemeyer]

In an attempt to make stable APIs more popular, I've just published a
tiny service at gonuts.org that offers a mechanism to have with GitHub
repositories the same sort of versioned URLs exposed at labix.org
(labix.org/v2/mgo, etc). For example:

gonuts.org/v1/docs

No registration necessary. Just name the repository (and optionally
the organization) properly and it works.

There's good documentation at https://gonuts.org describing how the
convention looks like, including some details about when to bump the
version of a package.

Please let me know if you find any issues.


gustavo @ http://niemeyer.net

[Joseph Lisee]

Why use this instead of the GitHub URLs?

With gonuts:

import "gonuts.org/user/v1/package"

Without:

import "github.com/user/go-package-v1"

I agree that the gonuts version is cleaner, but now I am coupling my code to a two 3rd party websites instead of just one.

-Joe L.

[Gustavo Niemeyer]

On Tue, Mar 4, 2014 at 11:44 AM, Joseph Lisee <jli...@gmail.com> wrote:
> I agree that the gonuts version is cleaner,

Right. Often that matters (and it does to me, anyway).

> but now I am coupling my code to a two 3rd party websites instead of just one.

If that works for you, I'm happy as well. I'm after stable APIs, not
how you get there.


gustavo @ http://niemeyer.net

[Gustavo Niemeyer]

This looks like a FAQ, so I've added more details to the documentation:

Note that gonuts.org does not hold the package code. Instead, the go
tool is redirected and obtains the code straight from the respective
GitHub repository. The advantage of using gonuts.org is that the URL
is cleaner, shorter, redirects to the package documentation at
godoc.org when opened with a browser, and most importantly encourages
the adoption of stable versioned package APIs.

--

gustavo @ http://niemeyer.net

[Nate Finch]

In the github account name use case:

gonuts.org/<user>/v<N>/<package> => github.com/<user>/go-<package>-v<N>

the go- prefix on the repo name seems entirely extraneous. There's no possible collision with code you don't own, so it doesn't seem to be helping anything to add the go- except to make the repo name uglier.

[Gustavo Niemeyer]

From the documentation:

Why the go- prefix

It provides context, it prevents conflicts with unrelated repositories
and organizations so that using short and clear names is possible, and
it discourages package authors from using the boring go<something>
style.

> --
> You received this message because you are subscribed to the Google Groups
> "golang-nuts" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to golang-nuts...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.

[Marcelo]

On Mar 4, 2014 8:36 AM, "Gustavo Niemeyer" <gus...@niemeyer.net> wrote:

> In an attempt to make stable APIs more popular, I've just published a
> tiny service at gonuts.org that offers a mechanism to have with GitHub
> repositories the same sort of versioned URLs exposed at labix.org
> (labix.org/v2/mgo, etc).

Thanks for doing this, and thank you in particular for posting guidelines regarding managing the version numbers.

Marcelo

[Péter Szilágyi]

Hi Gustavo,

  The tool is cool, and I can imagine a lot of very useful use cases, but there are a few issues that somehow bother me:

• You force a package naming convention that cannot be circumvented. I agree that go<something> is boring, but go-<something> is equally boring and I don't like being restrained with my package names. The only place where I actually inserted the implementing language into a repo name was the bindings to my messaging system (but even there after the package name - i.e. iris-go, iris-erl - and not before). Still, I prefer original, creative and meaningful names. A name is brand and equally part of the API (even if not directly), which your convention hugely constrains.
• Requiring each package to have it's own github user is imho a bit steep. Beside a lot of extra complications to manage a load of users, it also breaks all existing code organization convention (i.e. if all my related repos are under one user, and I move out the Go packages, chaos will entail). The design looks nice and makes sense, but it's way more complicated than people will be willing to put up with. I doubt it will gain traction.
• You require github exclusively. Although that is also my favorite source hosting service, you again limit the freedom of people to move between sites. A lot of people I know prefer bitbucket, and a significant part of the go packages are on Google code. Is your versioning system desirable enough to force devs hands in such a way?
• As brought up earlier, it's another dependency in the development life cycle, and a very serious one. Can you guarantee that your site will always remain online? Will you operate it indefinitely? Any source code using this scheme will immediately be bound to it for all time. IMO, this is a very serious decision to make as a dev.

  As long as your within an organizations, these issues can be solved by sticking to *the* convention, but out at large I think the limitations outweigh the benefits.

Cheers,

  Peter

--

[Gustavo Niemeyer]

Hi Péter,

On Tue, Mar 4, 2014 at 5:04 PM, Péter Szilágyi <pet...@gmail.com> wrote:
> You force a package naming convention that cannot be circumvented. I agree
> that go<something> is boring, but go-<something> is equally boring and I
> don't like being restrained with my package names. The only place where I

That's not true. The *package* can be named to your taste. The tool
forces a naming convention on the GitHub repository, and that's
required to implement its functionality without more boilerplate. So
hopefully we'll have more foos and bars, and less gofoos and gobars,
but even that is up to if you really want it.

> Requiring each package to have it's own github user is imho a bit steep.

I don't know what you're talking about here. It doesn't.

> You require github exclusively. Although that is also my favorite source

GitHub is by far the most popular code hosting site. Sounds like a
good place to start.

> As brought up earlier, it's another dependency in the development life
> cycle, and a very serious one. Can you guarantee that your site will always
> remain online?

Of course not. I don't know of any site that always remains online.
That said, this is a trivial service, and having it highly available
is no trouble. The efforts on that will be proportional to its use.

> Will you operate it indefinitely? Any source code using this
> scheme will immediately be bound to it for all time. IMO, this is a very
> serious decision to make as a dev.

Yes, I will operate it indefinitely. It would be very ironic if while
pursuing the stability of code at large I broke everybody at once.

> As long as your within an organizations, these issues can be solved by
> sticking to *the* convention, but out at large I think the limitations
> outweigh the benefits.

If that's not clear, the goal of gonuts.org is to strongly encourage
authors to consider the stability of their APIs over time, and to
offer a simple path towards that. Pretty much 100% of the packages
hosted at GitHub today don't do anything like that. So, if you're
worried that gonuts.org will break your code somehow, we're on the
same side of the problem. Your code *will* be broken soon if the
packages you depend upon do not adopt a stability strategy.


gustavo @ http://niemeyer.net

[Nate Finch]

I find the domain name to be unfortunately confusing with gonuts.io, a go package management site.

I think the go- prefix on repos is ugly and unnecessary if you specify the group or username. You're trading off *encouraging* the package to be prettier by *forcing* the repo to be uglier. That does not seem like a good trade-off.

That being said, I think it's great to encourage people to version their packages, and I think it's a great service provide for people who can't our don't want to run their own vanity url.

Fyi, while I think it's cute that gonuts.org uses it's own service to show docs, I personally found it confusing that the url changes to godoc.org. I kept trying to figure out how to get to the gonuts.org homepage.

[Gustavo Niemeyer]

On Tue, Mar 4, 2014 at 7:56 PM, Nate Finch <nate....@gmail.com> wrote:
> I find the domain name to be unfortunately confusing with gonuts.io, a go package management site.

Sorry about that.

> I think the go- prefix on repos is ugly and unnecessary if you specify the group or username.
> You're trading off *encouraging* the package to be prettier by *forcing* the repo to be uglier.
> That does not seem like a good trade-off.

Quite a lot of people use the "go" prefix in their repositories either
way, and that's generally fine as when you're looking through a list
of things in GitHub, it's not obvious that "yaml" is actually
"go-yaml". This isn't true when you're importing them from Go,
though.. it's obvious that whatever you're importing into Go source
code is "go-<something>".

We don't have to agree on that, though. We won't achieve consensus on
any convention we agree on.


gustavo @ http://niemeyer.net