Re: go importer documentation/exceptions

[Katherine Cox-Buday <cox.katherine.e@gmail.com>]

I agree with the gist of what you're saying, but I first need to establish that Guix is actually not doing anything wrong before we can talk about how to make things better.

> On Saturday, April 23rd, 2022 at 9:51 AM, jgart <jgart@dismail.de> wrote:
>
> The Guix docs do not explicitly state that a uri like
> https://git.sr.ht/~emersion/chathistorysync@0.1.0 is not allowed:
>
> https://guix.gnu.org/manual/devel/en/html_node/Invoking-guix-import.html
>
> This leaves footguns for new users trying to use the go importer for
> the first time since a new user might want to just copy paste the go
> package's url into the terminal.

I'll explain more below, but a "package's URL" is a misnomer.

> Should we be explicit in the docs about what uri syntax is and is not
> allowed

Here is the output from `guix import go --help`:

Usage: guix import go PACKAGE-PATH[@VERSION] Import and convert the Go
module for PACKAGE-PATH. Optionally, a version can be specified after
the arobas (@) character.

And here is the definition of a package path from
https://go.dev/ref/mod#glos-package-path:

#+begin_quote

  package path: The path that uniquely identifies a package. A package
  path is a module path joined with a subdirectory within the module.
  For example "golang.org/x/net/html" is the package path for the
  package in the module "golang.org/x/net" in the "html" subdirectory.
  Synonym of import path.
  
#+end_quote

So I disagree that Guix doesn't explicitly state that a URI like the one you've given is not allowed, because it doesn't say to pass in a URI, it says to pass in a PACKAGE-PATH, which has a very specific meaning in Go.

Package paths happen to look like URLs, but they're not. They're URIs with special properties that go far beyond where to fetch code. As an example, you could fetch the package foo.bar/baz from https://my-repository.com/katco/my-lib. There is an algorithm[1] for resolving a module path to a SCS to fetch from, and Guix re-implements[2] this.

Now, having said all that, I can see how someone familiar with Guix, but not Go, would make this mistake. And since we're here to help humans, but not pedants, and not computers, we should keep that in mind when thinking about designing the tool.

In my opinion, we should assume the person importing Go packages knows what a Go package is, and therefore knows what a package path is. If they get it wrong and try and use a URL, that's when we should surface the difference between the two, and suggest they try again without any URL syntax.

WDYT?

[1] - https://go.dev/doc/modules/managing-source#tools
[2] - https://git.savannah.gnu.org/cgit/guix.git/tree/guix/import/go.scm#n474

-- 
Katherine