From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms5.migadu.com with LMTPS id iHZDOznRZ2JCkQAAbAwnHQ (envelope-from ) for ; Tue, 26 Apr 2022 13:02:18 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id iHEvOznRZ2KRkAAAauVa8A (envelope-from ) for ; Tue, 26 Apr 2022 13:02:17 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 6389E3CBC6 for ; Tue, 26 Apr 2022 13:02:17 +0200 (CEST) Received: from localhost ([::1]:41162 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1njIxU-00032F-E5 for larch@yhetil.org; Tue, 26 Apr 2022 07:02:16 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:41914) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1njIse-0006UZ-Ec for guix-devel@gnu.org; Tue, 26 Apr 2022 06:57:16 -0400 Received: from mail-qk1-x731.google.com ([2607:f8b0:4864:20::731]:43731) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1njIsc-0003Fh-DB for guix-devel@gnu.org; Tue, 26 Apr 2022 06:57:16 -0400 Received: by mail-qk1-x731.google.com with SMTP id 79so970487qkk.10 for ; Tue, 26 Apr 2022 03:57:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=UK6CJ8O46Kh1tQG3hTWuQpjxcRTkIcpnB6OdAYuYHfM=; b=pK23c9zW/TN++tZnMQ6jlHt1FLBSLuTQyrliVWbdze50PsLCRPUX8tUMiWTjIbKPa+ b5Gh4ZlJr8mrsCSmdv4koIsxeou7w88QY9j9ozk1fuv0S293v5umGY6GJ4Dkf5XE4JGC +7M7EX66sQxsQgegOMbbQ4SWZ27HGrTtgnOWzit7jepceQdkBmk2YUvV6t+S7BrwZ+iA czC4TXjC9vAPLp8odqBA/wa6s7FLGkdtjc5tWNTtCoaTZKBP6Ooq4BaaVqUiLnC7/nbU 2SQQnPbluK9uqHo0sD8gliU6fdtLMdrC249FQ2BGrdK7AkY34rR0gX95tUOXvyyaMcBt PZnw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version; bh=UK6CJ8O46Kh1tQG3hTWuQpjxcRTkIcpnB6OdAYuYHfM=; b=G+bVTh//CrsNxxwSNWOYMPa88umYYP8h6w8bVA8Szy/W33md8li6Shh00pnzvi5g1m VuyZYTi5ej565bjIpf0ddLcRFAU1AJxGnvaWUcXqSLhuyDK49hAgCX/BjXq3BfSAFrwQ 3LXKN0gvCZ9rOTlD3ekl1p67WX7di8CgSa75mL42JdxkKwpcXjT9ddiSqgNtVM7cHKPt g5Lwi2MXu4hk15pZu3IYy2YtjfALLySLmW3qr9gXPrU6mBmd6pItgyceccpyDa106BJi U15r3t7cuBLoUm7ykgR6/rt8Ta1jODO4jmO1dJnfTrRybZ8YJIXK7G9WCuXtKqiR5t9F GT6w== X-Gm-Message-State: AOAM533hAquLk1TLTnArBoC+tPmXsMP3FvoTtdR+I0P36/S+r7IH5D/s 6gme0G5B55rnKm1kO5UI9ZGhJcosV9mc5A== X-Google-Smtp-Source: ABdhPJzm8Wh51+UZjlq6vVxRVKbUQAfo79TryHyT7r66msDTG+k7DN0HaSkoyQHXqBsAcq9Zc5Lt6g== X-Received: by 2002:a37:40d7:0:b0:69c:8c7c:bf64 with SMTP id n206-20020a3740d7000000b0069c8c7cbf64mr12591479qka.417.1650970633077; Tue, 26 Apr 2022 03:57:13 -0700 (PDT) Received: from washu-v4 (172-221-246-205.res.spectrum.com. [172.221.246.205]) by smtp.gmail.com with ESMTPSA id 19-20020a05620a079300b0069eb4c4e007sm6148555qka.29.2022.04.26.03.57.12 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 26 Apr 2022 03:57:12 -0700 (PDT) From: Katherine Cox-Buday To: jgart Subject: Re: go importer documentation/exceptions References: <20220423125110.GB9845@gac.attlocal.net> Date: Tue, 26 Apr 2022 05:57:11 -0500 In-Reply-To: <20220423125110.GB9845@gac.attlocal.net> (jgart@dismail.de's message of "Sat, 23 Apr 2022 12:51:10 -0400") Message-ID: <87fsm0nmd4.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=2607:f8b0:4864:20::731; envelope-from=cox.katherine.e@gmail.com; helo=mail-qk1-x731.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: guix-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Guix Devel Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: "Guix-devel" X-Migadu-Flow: FLOW_IN X-Migadu-To: larch@yhetil.org X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1650970937; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=UK6CJ8O46Kh1tQG3hTWuQpjxcRTkIcpnB6OdAYuYHfM=; b=TBe1cFWdBar/TZO46fllPIFLJL5WC+DEZc+W+7AyVe4FkBhEXt8q7tyK6DflAXWIv7GIOm EK8q/jWPkH4y3Tw5mWTHwiiv6HAeVgJjtlTTwCD+7V2P5LKQ4SL85DfQB+qe0ORWnYSDQI v2t25hBfE76RjXiqpCOrf9hd6AcWDrWa55BajoXj9ex7hGUuRmssj2wa9QGlKLYmBFGGwV xtBDjpuPJK8k2I3/RuBOMp99uOm6VmeP3q4lme9+zHsADiin8nuNX9rlN0l4fsbgMvj0+l l2W5+3jZcbgKsQ3+4An+u4g3bt6nY6faKC1zpllFAyiS2WEPLKCUo+vhJC/p2w== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1650970937; a=rsa-sha256; cv=none; b=ByE+rNRJ2Ggj6ckIpjyRj4k5WY+b4gOBxC/ujHZ/tBdUoKYAmhLcxuTE0NQQehowz3MJ5a SeD6JHRK503Cx7xQj4mqMNNXHq97229QrP2FJHVcb0T39e0gE8GPnWMidyq1fxoX8Eb4D5 Y6Xzcr/HP6waiF5twXkDl9tkJGsvt0ghJ5IM9uTiBsJldyx1W2r6nvkCNx9B9yeDl2VyGL EnUgpj2U3qeQSNwRJGRjKK95BJH9/T+vkRkfdcAO0318q6PzizY6Z2WiVZmTuhgb6NTWtw L8vSIAuPOtdQpcTehWOWZwJy+wEcsXi9oaGljl2oX7ynKQ3osLr5Jd7o8DOZLA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=pK23c9zW; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -6.01 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20210112 header.b=pK23c9zW; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 6389E3CBC6 X-Spam-Score: -6.01 X-Migadu-Scanner: scn0.migadu.com X-TUID: clJpYrnsw47u 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 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