Re: go importer documentation/exceptions

[Katherine Cox-Buday]

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