From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:403:478a::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id gJDYNPnODWWUWQEAauVa8A:P1 (envelope-from ) for ; Fri, 22 Sep 2023 19:29:30 +0200 Received: from aspmx1.migadu.com ([2001:41d0:403:478a::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id gJDYNPnODWWUWQEAauVa8A (envelope-from ) for ; Fri, 22 Sep 2023 19:29:29 +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 C41C1504F5 for ; Fri, 22 Sep 2023 19:29:29 +0200 (CEST) Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=elenq.tech header.s=protonmail2 header.b=qiJWydCN; 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"; dmarc=pass (policy=none) header.from=elenq.tech ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1695403769; 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: 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=en0GMoY47VhKJZu1JJDCTMsq1gAg+qfTOaCO7bmlMz8=; b=cUw+4kFWTU7oah/xu8Kf0N0Nn+kLmMXiGTG7UJeYsT9zJIKyT2bGpBxduoRabgRCl9S7a2 c2RjgHbGPpnjYLZJwMif1bGpeYSWnfH0EhhnVGLTS5C55gckXG9JPQZ+UC3KY1Izvspd6x KJsdVo5dgAfmSQEZrSZtI/ky3sIxeRC04FGZc14lyGvqAgGaLd01wMZRO0uBWcRw6b7hqv PlyZCNixOqNI+AeqUkn/o+B00fG0871sSnaxiM1QEDdQoyN6YndZKC+Lmrm4dRWCiSiLon 6LYSwCkh3X0MH4kyFqMgZB5Jj7VTrC9cZC8YRLBvjNdpTay8EwlB0Ztl5ShmEA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1695403769; a=rsa-sha256; cv=none; b=e2BeI+GF4h1cf/sH4KO7lnR+4WYCBuVf/usWBvCVXgx0eBmoFp8xnqu7LJlJlVZMPZ4nuL /MYLtNM1SXdU3b2emaBbq5RYq3EAdHz+iezOTbE8EuYQFVPI3yDvdbbCm8v/M/ipafzdrs 7GWDBgG65HyPbB1xKQmcRXJVG+UeR/xvaUCAc/zzj65ZDkENVxrP6mwmdNdv/rl7PsOvSi vQZM0meNmMbiNnAMkYN08OHlYTQ2SelcRaq42AvhQiqgi4CuJcYvcVYcFFAEc8djOPot0X /AtPBXmcUR5qw3hZvk7GCPv0PoDZ8fEqH6Q1hvVCNAFVT39/plirxaFTir3j8g== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=elenq.tech header.s=protonmail2 header.b=qiJWydCN; 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"; dmarc=pass (policy=none) header.from=elenq.tech Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qjjxb-0001Uw-HI; Fri, 22 Sep 2023 13:28:59 -0400 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 1qjjxZ-0001Uo-Lj for guix-devel@gnu.org; Fri, 22 Sep 2023 13:28:57 -0400 Received: from mail-4022.proton.ch ([185.70.40.22]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qjjxW-00071Y-Qs for guix-devel@gnu.org; Fri, 22 Sep 2023 13:28:57 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=elenq.tech; s=protonmail2; t=1695403729; x=1695662929; bh=en0GMoY47VhKJZu1JJDCTMsq1gAg+qfTOaCO7bmlMz8=; h=Date:To:From:Cc:Subject:Message-ID:In-Reply-To:References: Feedback-ID:From:To:Cc:Date:Subject:Reply-To:Feedback-ID: Message-ID:BIMI-Selector; b=qiJWydCNY/RcQwmJ/zdC5tbjVv4Sa9MugFvwv4/DjxmYysUUs9MlyvdjNaPgE0JKF Xyew1Fx8qA92DynQhqcuio6nS+AB87MAudH6WTdL0Lsbo9mRVf2/6l+iMlZrr9rZwF 5d0J4RnYvUk+a2wTlPqkPnNg3+QkvnU+sukUGTMlG0bXN7XInp4Xncpemc0Pmn0mnS 3yvLL0sVU8GzZwBIlKU8fY8AHW88QZHRJYyD+o53E55xXIUB+WwqDlD747R+Kl4t2X jsrG40uk37uvbt5Qz8PvM1yQMhWzENIFWtT6ch3hlQ+G8KihQIOYtKRGMjBXR0EGzy k/0AZiikbqADA== Date: Fri, 22 Sep 2023 17:28:41 +0000 To: MSavoritias From: Ekaitz Zarraga Cc: Imran Iqbal , Giovanni Biscuolo , =?utf-8?B?5a6L5paH5q2m?= , Maxim Cournoyer , Katherine Cox-Buday , "(" , guix-devel@gnu.org Subject: Re: How can we decrease the cognitive overhead for contributors? Message-ID: In-Reply-To: <7364531e-5816-799d-5c71-621892082e48@fannys.me> 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> Feedback-ID: 3263582:user:proton MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=185.70.40.22; envelope-from=ekaitz@elenq.tech; helo=mail-4022.proton.ch 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, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 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: , 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-Scanner: mx0.migadu.com X-Migadu-Spam-Score: -7.03 X-Spam-Score: -7.03 X-Migadu-Queue-Id: C41C1504F5 X-TUID: SgqhTcsQWFlu =20 > I think a lot of this discussion is stuck on what is better web or > email. Where it doesn't have to be. >=20 > What we instead need to do is acknowledge that some people like the web > approach. >=20 > And accommodate them so we can have guix used by more people. Simple as t= hat :D Exactly. An option is to make some kind of user-story based documentation might help= ? For example: ------ - If you are used to a web-based git forge such as gitlab or github, Guix's= approach to collaboration might seem a little bit hard at the beginning. Guix uses an email based approach, like many other GNU projects do. Email b= ased approach relies on sending commits as patches that can be later applied by = commiters and maintainers. Thee patches are sent via email, in plain text, instead of= using a website for a Pull- or Merge- Request. You don't have to worry about the format of the emails, as git is able to g= enerate them for you: $ git commit ... $ git format-patch ... If you configure git properly (link to how to do it), git can send those em= ails to guix automatically (see Using Git Send Mail). If you prefer, you can copy t= he content of the file `format-patch` generates in a plain text email, or attach it an= d send it to `guix-patches`. When that email is received a bug report will be opened in guix's issue sys= tem, where you can further discuss, as you would do in any other issue board or merge-= or pull- -request discussion. The discussion is available at `URL` and looks like `s= creenshot`. If you want to share a series of patches... ------ Something like that (done with more care and attention than what I just did= ), might help newcomers. It's mostly the same our documentation says, but our docume= ntation currently (I think) relies too much on the people knowing what everything m= eans. Maybe a deeper contribution guide might be an interesting thing to write do= wn... Also including some introduction to the internals and how to write a build-= system... Stuff like that is always useful. It has to be properly maintained though, but even if it is out of date, it'= s still a valuable resource to have some info about the *concepts*. (we can always = put the date of the latest change and a note: this documentation is designed to exp= lain the concepts, the specific details might be out of date, but the concepts remai= n). Or something, I don't know. But I'm open to try it :) The case of the Changelog commits has been discussed and its important too. We need to be able to make contributors learn how much they need to write d= own in the commit messages. I tend to write too much, and I don't think any of my = patches have been applied without changes in the commit message. For example, in guix we often do (I just invented the name):=20 gnu: Add lolo * gnu/packages/engineering.scm(lolo): New variable. Is that enough to describe the addition of a new package? If you know what = you are looking for it might be, but it looks like an automatism commiters have tha= t is not communicated properly. What if there's something in a `let` i changed? I ha= ve to list that too? What if...? Some help on that might be useful. And also, explaining how important it is= to follow the jargon we use in the commit messages. Or how long should our explanatio= ns be... Just to help people don't feel overwhelmed about it, nothing more than that= (and=20 nothing less!). I don't know if this adds anything new to the conversation. Cheers!