From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.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 8E7AN6Lm+mQgSQAA9RJhRA:P1 (envelope-from ) for ; Fri, 08 Sep 2023 11:17:23 +0200 Received: from aspmx1.migadu.com ([2001:41d0:403:478a::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id 8E7AN6Lm+mQgSQAA9RJhRA (envelope-from ) for ; Fri, 08 Sep 2023 11:17:23 +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 AC21643B08 for ; Fri, 8 Sep 2023 11:17:22 +0200 (CEST) Authentication-Results: aspmx1.migadu.com; dkim=none; 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=none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1694164642; 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; bh=bmwUsveFkdox/bLsCHE0OBYiU6/EANAgApZ8qeiFofo=; b=hJ+WhQnFpy2XbVyTITA6NCpRpIpjy1KVZQK4jxQ0NT1tAbbwwV3UGJGBq1Ui4jfF97GWTM 7BV5DlaHs3FZVObU8iOlci1C6wemB5Q+Xxq5KoysUzjDlem50jHNLHHM3le2rXjJuewNjV OoMb8xjS7vKS6dt2RElnliTapbWwThReyHMr7V4voxM8pUy03/ePIbsxK6KZHbF7mdBdkR poxfJHDoF5lyyHj2Ywq4RYicC16kDbKhpHpkgwdrwianEiY8W+quLQi7uGhNPE8vqlTnHj +p8IE3DJQE3oYm6h5zLnIIwRPkAgGlT2N4zHa/aoDrrWRl0GwpW9EoevnEyGdw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1694164642; a=rsa-sha256; cv=none; b=g+gPyj6dIgYfmkRUgI5D4HeTdbGJq3GKjyy8W8tB6bf8jBFUmYPgWYC1+wM3maYIDNWCH2 g4TtvQ/iCHJezXM4G/sumO2Wfy/NrCtccsWcnQ1SP1OB7J5Z9oNJ4mCTlKc3uEO3Pduo83 7EzNlhwOzrXhpZMOpTU70KZ3Qd7az9Y+PgBoLdJY8RXfsViecaB+YZgywCaLvHD2i0kPZi HLA7h93/bwLxn9eCBOM1BnwrHb08OZhmFymcbXlOz+o9MLWbjsCiB8ByQOD179nhRRP/QQ GLaFZjWzjopG3pC7bXl4CX91vYP+lK6eWcWAKevnEybeQuaxx4vIs8aU4GZOOg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none; 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=none Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qeXbD-0004wM-NO; Fri, 08 Sep 2023 05:16:23 -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 1qeXb5-0004sD-P4 for guix-devel@gnu.org; Fri, 08 Sep 2023 05:16:16 -0400 Received: from ns13.heimat.it ([46.4.214.66]) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qeXb2-0001tt-2E for guix-devel@gnu.org; Fri, 08 Sep 2023 05:16:15 -0400 Received: from localhost (ip6-localhost [127.0.0.1]) by ns13.heimat.it (Postfix) with ESMTP id 0858E30081A; Fri, 8 Sep 2023 09:16:09 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at ns13.heimat.it Received: from ns13.heimat.it ([127.0.0.1]) by localhost (ns13.heimat.it [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id SXv8oVwwLMAJ; Fri, 8 Sep 2023 09:16:01 +0000 (UTC) Received: from bourrache.mug.xelera.it (unknown [93.56.171.217]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by ns13.heimat.it (Postfix) with ESMTPSA id CED2A30080B; Fri, 8 Sep 2023 09:16:01 +0000 (UTC) Received: from roquette.mug.biscuolo.net (roquette [10.38.2.14]) by bourrache.mug.xelera.it (Postfix) with SMTP id 652672994C59; Fri, 8 Sep 2023 11:16:01 +0200 (CEST) Received: (nullmailer pid 10586 invoked by uid 1000); Fri, 08 Sep 2023 09:16:00 -0000 From: Giovanni Biscuolo To: guix-devel@gnu.org Cc: Liliana Marie Prikler , Simon Tournier , Maxim Cournoyer Subject: Re: How can we decrease the cognitive overhead for contributors? In-Reply-To: <87sf7rqhqw.fsf@gmail.com> Organization: Xelera.eu References: <20230827135726.y33t55w4cvq6zsvb@X-kone> <874jkift8v.fsf@gmail.com> <867cp4sj7k.fsf@gmail.com> <38242808-2f06-4674-3842-aea1a5378d05@gmail.com> <87a5u0o3z2.fsf@disroot.org> <87sf7s9oi9.fsf@spork.org> <67115f26712acbb1d83b71f4418c682a5e9762a4.camel@gmail.com> <87h6o7mbo2.fsf@wireframe> <87sf7rqhqw.fsf@gmail.com> Date: Fri, 08 Sep 2023 11:16:00 +0200 Message-ID: <87y1hhdnzj.fsf@xelera.eu> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha512; protocol="application/pgp-signature" Received-SPF: pass client-ip=46.4.214.66; envelope-from=g@xelera.eu; helo=ns13.heimat.it X-Spam_score_int: -18 X-Spam_score: -1.9 X-Spam_bar: - X-Spam_report: (-1.9 / 5.0 requ) BAYES_00=-1.9, SPF_HELO_NONE=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-Country: US X-Migadu-Flow: FLOW_IN X-Migadu-Scanner: mx0.migadu.com X-Migadu-Spam-Score: -7.33 X-Spam-Score: -7.33 X-Migadu-Queue-Id: AC21643B08 X-TUID: fn/nIucZ3csq --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Hi all! I think the discussion about ChangeLog Style shows we probably need to: 1. enhance the manual section "22.6 Submitting Patches" https://guix.gnu.org/en/manual/devel/en/html_node/Submitting-Patches.html =2D-8<---------------cut here---------------start------------->8--- Please write commit logs in the ChangeLog format (see Change Logs in GNU Co= ding Standards); you can check the commit history for examples. You can help make the review process more efficient, and increase the chanc= e that your patch will be reviewed quickly, by describing the context of yo= ur patch and the impact you expect it to have. For example, if your patch i= s fixing something that is broken, describe the problem and how your patch = fixes it. Tell us how you have tested your patch. Will users of the code ch= anged by your patch have to adjust their workflow at all? If so, tell us ho= w. In general, try to imagine what questions a reviewer will ask, and answe= r those questions in advance. =2D-8<---------------cut here---------------end--------------->8--- IMO we should move the above paragraphs to a new subsection "22.6.N Change Logs" and add some rationale (summarized from the GNU Standards section and maybe with some specific Guix ratio expressed in this section), a general rule (to be interpreted by humans, see below) and some examples taken by one or two relevant commits recently made. 2. enhance the section section "22.3 The Perfect Setup"=20 The proposed new "22.6.N Change Logs" subsection above should also provide a link to the relevant information about the snippets documented in section "22.3 The Perfect Setup"... and /vice versa/: the "snippets section" should reference the "Change Log" section, since snippets are made to automate the general rules provided in "Change Log"; I'd also separate the paragraph related to snippets in a "22.3.1 Emacs snippets" section 3. wellcome snippets for different IDEs Somewhere=E2=84=A2 in our manual we should say that we are very glad to acc= ept patches (alco to documentation) to add snippets for free software IDEs templating systems other than Emacs Yasnippet or Tempel, like vim-neosnippet for vim or the native templating system of Kate [1], for example. Other examples? 4. add a git commit message template https://www.git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#_commi= t_template =2D-8<---------------cut here---------------start------------->8--- If your team has a commit-message policy, then putting a template for that = policy on your system and configuring Git to use it by default can help inc= rease the chance of that policy being followed regularly. =2D-8<---------------cut here---------------end--------------->8--- I'd write a template with a very short explanation on the commit message *basics* (first line is Subject max 50 chars, blank line, body) and some https and info link to the relevant section of the manual about Change Log format. Suggestions for other git template content are very wellcome. This template will be added to the git config file etc/git/gitconfig, that is automatically configured when building the project as stated in "22.6.1 Configuring Git". I'll try to send a patchset for 1., 2. and 3; a separate one for 4. WDYT? Maxim Cournoyer writes: [...] >> On 2023-09-06, Liliana Marie Prikler wrote: [...] >>> It's=20 >>> >>> * file (variable)[field]{do you need 4 levels?} The general form of a ChangeLog Style format for Guix code (Guile with gexp) could be rewrote as: * relative-path-of-changed-file (variable) [field] : Description = of change. I never saw a {4th level} so AFAIU is not needed, unless someone have a good example plz: in this case we could add a 4th level to the general description. [...] > Here's an example in the Guix "dialect": > > --8<---------------cut here---------------start------------->8--- > * gnu/packages/file.scm (package-symbol) > [arguments] <#:phases>: New patch-paths phase. > --8<---------------cut here---------------end--------------->8--- > > It could also have been: > > --8<---------------cut here---------------start------------->8--- > * gnu/packages/file.scm (package-symbol) [arguments]: Add patch-paths > phase. > --8<---------------cut here---------------end--------------->8--- Those are good general examples: I'd use them in the manual section descibed in 1. WDYT? > It doesn't really matter, as long as it's clear and you did the exercise > of reviewing the code you touched and writing down the changes summary > for the reviewer (and yourself). This is a good example of ratio, I'd use that also :-) Happy hacking! Gio' [1] https://docs.kde.org/stable5/en/kate/kate/kate-application-plugin-snipp= ets.html =2D-=20 Giovanni Biscuolo Xelera IT Infrastructures --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQJABAEBCgAqFiEERcxjuFJYydVfNLI5030Op87MORIFAmT65lAMHGdAeGVsZXJh LmV1AAoJENN9DqfOzDkS82sP/3iAv5cFK1Zr26qqomHu66ZKnZ1ov3QXhB3g8HNK muCQUMxcZLe5/0Zi2pYXNKiioiNCvU/T9LQLbg25+1KwewyIUiPPdytsRjdF4Dc6 JAYyoyaSfyqa2iiVBgsjaqvQXhTyjyciosyA/8Q4qv0fNbEr06QG0cOLKZhsPnIR Xf7RqFGaaNqF3bQ2ZRrqGABOWKiC2xAtnZdgBuhaW+xs7L1l/MDbQmbs7EKrIzpn f7GMiy1mcoTvdJHiFp7L8wJNExN5BW1bpYWUjQS8gA28tbKoihRzFyRu1STeLCqK Z9YvKQ8uqe0VfdXm8nc3NJUqHVXarHwQe7gSpmp3nXfZfa1RUrtmYFpAxOOGiBza jXvn/JAbIZXTklM9vAek1ak/OZXZZXfiEGnPuH0bzFgHF0yvyy1u+xKU9AZTHeql OrSw9wxkb+0WxYaoAAXME8WoTn2ThK7CeW40iLaJF8kN3BLrxYQagW+2MEgtVEwS 7Covkh3Mcl8Zle8oHf7kwnmThpwL+eW0VbtOdofOs67MQ4NjGbSAFWzEvWmQgh4e 4MvSHnzUI2DVRS6UyvXOgqeNF8DgbR34e9khyyuP5CybobLbxwC/LUkcXjma+hLe xjumGvXegrbAJhJ3NBfs29Ha8RuNjoBpOFvRQynkTBODQTXQH8ZiFWZRn/JMtIL3 NgQM =XZAG -----END PGP SIGNATURE----- --=-=-=--