From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms8.migadu.com with LMTPS id oKuFJLpsSWV2owAAauVa8A:P1 (envelope-from ) for ; Mon, 06 Nov 2023 23:46:18 +0100 Received: from aspmx1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id oKuFJLpsSWV2owAAauVa8A (envelope-from ) for ; Mon, 06 Nov 2023 23:46:18 +0100 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 52645329B4 for ; Mon, 6 Nov 2023 23:46:18 +0100 (CET) Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=sdf.org header.s=sdf.org header.b=pbO6nICx; dmarc=pass (policy=none) header.from=gnu.org; 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" ARC-Seal: i=1; s=key1; d=yhetil.org; t=1699310778; a=rsa-sha256; cv=none; b=qTc7zvuoPPKBFUS2Zijjw2SybOnRvmtFZZrPq/eRJigvIKqZ8BceWS8VIOW+2n64vgqy6p 1fPi5qgTEB+kmREIAAi55OuMO77cPc7ex0TQwW4aZlkTtCnyaHaNQyumEl1b0i5f1ThKQK AabrDyQ2H3/68Gp/Kyqdgi5RC2SMbCDpHvo1+l0xIVfeeMBlxg5b4XX4l2WNMTilaPIVj6 Q9OoXpLFiRXGvOKQnIiE7mAZ3ApzwuOX7sDepOEjuHW6GCglq0UJCW2WwrAMI7fA9+F01m QOx9ploHG/bHMqDHuwAYrnVQKi6kFZJpIiUEXAIMIwAcLEXfphAJBnJ82+zivQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=sdf.org header.s=sdf.org header.b=pbO6nICx; dmarc=pass (policy=none) header.from=gnu.org; 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" ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1699310778; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=WIDtbg8qTPtK615NUbZx/MIIhI7KBLg+qdOjwr5nZ9s=; b=QhkOy/7sj0zCppWD/IoA0JVnaeZdD4af9eI73CUOJeXnQpTodxJBts5I74mpjJkBG3nx1/ eNZoGitJHG5cJ9CxEmF3R6ctflUXvkpQssLZJB72RQRGKe58h2CA0njF9eY4fO02RPau0A sTGvdmiAkU00H9mct/ES9STWXcNx1ctlwPjcjvbYLC2j5nyE8xpTPfMO6JXIWF/FpVAGzY OldVXusvWay5EC6HXyakMy/hD+/wIFcGDPbddcWhMnTTvokLKPYWmvgKSG+eL8NMon4kxh VhXxnwuODyfWU+sFDQHT3F0JP0QphsDH5uWRiZavp0ASGmP5+sVH3AF3cmIbYQ== Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1r08LZ-0002M4-GG; Mon, 06 Nov 2023 17:45:29 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r08LX-0002Li-W6 for guix-devel@gnu.org; Mon, 06 Nov 2023 17:45:28 -0500 Received: from mx.sdf.org ([205.166.94.24]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1r08LV-0005KE-7y for guix-devel@gnu.org; Mon, 06 Nov 2023 17:45:27 -0500 Received: from localhost (68-74-198-14.lightspeed.rlghnc.sbcglobal.net [68.74.198.14]) (authenticated (0 bits)) by mx.sdf.org (8.16.1/8.14.5) with ESMTPSA id 3A6MhC6c023497 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256 bits) verified NO); Mon, 6 Nov 2023 22:43:15 GMT DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=sdf.org; s=sdf.org; t=1699310597; bh=GP/02MqJaL9EbmG2X2+3Zo5+ZZJd289sSrOZlT/c1jg=; h=From:To:Cc:Subject:In-Reply-To:References:Date; b=pbO6nICxsbci1bkYtAW0K104NivU7gXCu/CIM7e1aE9LGm2H3OVtfgsKsq1KZDkul QZQZXKTv7w+8MdlbZkylBanpPVVqmoL4TO1benjR+E0B43bnLcooMUwSs7Y/25TnKs RyZCKApj+CGE52dSwBCoM8JPKLlOsOZ2Tw1IGH4g= To: Matt Cc: , "Ekaitz Zarraga" , "MSavoritias" Subject: Re: Enabling contribution through documentation In-Reply-To: <18b3a24114f.e66ea6b1235588.3958425111160808928@excalamus.com> (matt@excalamus.com's message of "Mon, 16 Oct 2023 22:18:44 +0200") References: <87msyhgccg.fsf@disroot.org> <547c097a-d805-9a55-11d9-b0434327f89d@gmail.com> <871qfpjhiz.fsf@gmail.com> <87a5udaq7q.fsf@envs.net> <87il8z9yw8.fsf@xelera.eu> <7364531e-5816-799d-5c71-621892082e48@fannys.me> <87h6niffpl.fsf_-_@sdf.org> <18b3a24114f.e66ea6b1235588.3958425111160808928@excalamus.com> Date: Mon, 06 Nov 2023 17:43:07 -0500 Message-ID: <878r7aa4g4.fsf@sdf.org> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=205.166.94.24; envelope-from=shcv@sdf.org; helo=mx.sdf.org X-Spam_score_int: -16 X-Spam_score: -1.7 X-Spam_bar: - X-Spam_report: (-1.7 / 5.0 requ) BAYES_00=-1.9, DKIM_INVALID=0.1, DKIM_SIGNED=0.1, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=no 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: , Reply-to: Samuel Christie From: Samuel Christie via "Development of GNU Guix and the GNU System distribution." Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: guix-devel-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Queue-Id: 52645329B4 X-Migadu-Scanner: mx12.migadu.com X-Migadu-Spam-Score: -6.61 X-Spam-Score: -6.61 X-TUID: CxZ3fVYHyrEh Hello Matt; sorry, I've been distracted and almost missed your=20 reply a few weeks ago. Matt writes: > [...] I tried to write a tutorial on packaging GNU Hello.=20 > Really, if I were to look over the shoulder of someone packaging=20 > GNU Hello, what would it look like? Why are they doing what=20 > they're doing in addition to what and how. It's not obvious at=20 > all. The Cookbook touches on GNU Hello. However, it's hard to=20 > see how someone new to the details of Guix packaging, such as=20 > myself, is supposed to go from 'Section 2.1.1 A =E2=80=9CHello World=E2= =80=9D=20 > package' to actually packaging something in the wild. All paths=20 > inevitably lead to the Guile manual. Yes, there are several layers of complexity at play: building the=20 target package (not easy when all dependencies must also be=20 packaged), and specifying the package in Guile. I'm not that uncomfortable with scheme, though I don't think I=20 fully understand g-expressions yet. It would be easier if I could=20 get Geiser working for looking up symbols, but if the docs were=20 better I suppose I wouldn't have to read the code. I have successfully packaged some of my own things, trying to use=20 guix for managing dev environments; it's not too bad for some=20 things, but gets much more complicated when I have to step outside=20 the comfort zone of directly using existing packages and build=20 systems as inputs. The other major thing I'm not yet familiar=20 with is the patch submission and management process; not that I=20 have anything patch-worthy yet, but it is a hurdle. > Packaging is inherently complex. It requires *at least* knowing=20 > something about Unix-like systems, build systems, and details of=20 > software development ranging from general programming concepts=20 > to specific applications to all the surrounding tooling. I think it would be fair to assume minimal competence with using a=20 shell. Everything else should be given as clear, exact steps to=20 take ('mkdir package' not 'make a directory for your package'), so=20 that even someone who knows nothing can perform the steps and=20 produce the result. > A common assumption is that "they don't have to know anything=20 > before getting started". Unfortunately, this is not true.=20 > Fortunately, we can often abstract this away by giving only the=20 > necessary information (not easy to do!) for whatever we're=20 > explaining and handing off details to another resource. This is=20 > where the Guile documentation fails Guix. I think of tutorials as exposure rather than explanation, so the=20 tutorial itself shouldn't need to explain much or rely on external=20 resources. However, once the reader has finished the tutorial,=20 they should be able to look up the steps they were exposed to.=20 That is what the rest of the documentation is for, so I agree it=20 should be improved.=20 It's less clear how to "fix the documentation" than "write a=20 tutorial" though. Maybe we can start with the tutorial, then=20 improve the documentation for everything it used? > I'd be happy to work alongside you. Cool! I'm going to be pretty distracted this week, but we could=20 start working on it asynchronously. Any thoughts on process? Maybe=20 we could have a repo managed the same way Guix is, so I can learn=20 that at the same time. (That is, emails for discussion and patches=20 to the tutorial) How hard would that be to get or set up? That could also be the=20 'practice repo' people doing the tutorial would use for the final=20 submission parts. After that, I think the first step is picking an easy but=20 non-trivial package to do. Maybe it should be one that's already=20 been packaged... I went through a list of packages that I wished=20 Guix had, and sadly none of them were easy enough for me to do. My=20 first choice was INN (a Usenet server), but it has multiple=20 service dependencies I wasn't sure how to handle. My other choices=20 were apparently in Rust, which always has waaay too many deps. We=20 could also do a better Hello tutorial. Thoughts? Thanks, -Samuel