go importer documentation/exceptions

go importer documentation/exceptions

[jgart]

Hi Guixers,

Here's my experience of learning the right syntax for the go importer:

2022-04-23 16:27:42	<jgart>	guix import go https://git.sr.ht/~emersion/chathistorysync@0.1.0
2022-04-23 16:27:53	<jgart>	guix import go https://git.sr.ht/~emersion/chathistorysync@latest
2022-04-23 16:27:58	<jgart>	I tried that too
2022-04-23 16:28:00	<jgart>	and
2022-04-23 16:28:09	<jgart>	guix import go https://git.sr.ht/~emersion/chathistorysync@v0.1.0
2022-04-23 16:28:28	<jgart>	singpolyma: is this related to the issue you have open?
2022-04-23 16:29:41	<singpolyma>	Do you get an error about a tag being missing?
2022-04-23 16:31:32	<jgart>	here's the exact errors for all three attempts: https://paste.sr.ht/~whereiseveryone/dae9350b5680a3960e0e56c6b7c5da5660d3b8a6
2022-04-23 16:32:29	<jgart>	looks like a 410: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410
2022-04-23 16:33:26	<jgart>	guix import go git.sr.ht/~emersion/chathistorysync@0.1.0
2022-04-23 16:33:30	<jgart>	this worked

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.

Should we be explicit in the docs about what uri syntax is and is not allowed
or should we provide better exceptions when the go importer blows up?

all best,

jgart

https://whereis.みんな/
gemini://whereis.みんな/
http://litterbox.whereis.みんな/

Re: go importer documentation/exceptions

[Kaelyn]

------- Original Message -------
On Saturday, April 23rd, 2022 at 9:51 AM, jgart <jgart@dismail.de> wrote:


> Hi Guixers,
>
> Here's my experience of learning the right syntax for the go importer:
>
> 2022-04-23 16:27:42 <jgart> guix import go https://git.sr.ht/~emersion/chathistorysync@0.1.0
>
> 2022-04-23 16:27:53 <jgart> guix import go https://git.sr.ht/~emersion/chathistorysync@latest
>
> 2022-04-23 16:27:58 <jgart> I tried that too
>
> 2022-04-23 16:28:00 <jgart> and
>
> 2022-04-23 16:28:09 <jgart> guix import go https://git.sr.ht/~emersion/chathistorysync@v0.1.0
>
> 2022-04-23 16:28:28 <jgart> singpolyma: is this related to the issue you have open?
>
> 2022-04-23 16:29:41 <singpolyma> Do you get an error about a tag being missing?
>
> 2022-04-23 16:31:32 <jgart> here's the exact errors for all three attempts: https://paste.sr.ht/~whereiseveryone/dae9350b5680a3960e0e56c6b7c5da5660d3b8a6
>
> 2022-04-23 16:32:29 <jgart> looks like a 410: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410
>
> 2022-04-23 16:33:26 <jgart> guix import go git.sr.ht/~emersion/chathistorysync@0.1.0
>
> 2022-04-23 16:33:30 <jgart> this worked
>
>
> 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.
>
> Should we be explicit in the docs about what uri syntax is and is not allowed
> or should we provide better exceptions when the go importer blows up?

My $0.02: both would be best. Documenting the correct syntax instead of relying on error messages for that information makes for a much nicer user experience, as do better/clearer exceptions when a tool fails.

Cheers,
Kaelyn
>
> all best,
>
> jgart
>
> https://whereis.みんな/
> gemini://whereis.みんな/
> http://litterbox.whereis.みんな/

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