From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id uP++H3dff2YEJgAA62LTzQ:P1 (envelope-from ) for ; Sat, 29 Jun 2024 01:12:23 +0000 Received: from aspmx1.migadu.com ([2001:41d0:303:e224::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1.migadu.com with LMTPS id uP++H3dff2YEJgAA62LTzQ (envelope-from ) for ; Sat, 29 Jun 2024 03:12:23 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b="RWw/Ydb1"; 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" ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1719623543; 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=kC8xEzRFfiixsNZ7PJ2+uwqj886uf8zd8XD34+Zt5bI=; b=b23KDDwkJu5OHJl4YEhaigGxPnTa02GM8L9xKOYFRoEFFJpmw7jBiFnwjyX0KOVJ2IWvM0 pDV+an8715iFPJyF6IpUZZSdlyqqtskEgluuWT320oXKJpBQVMs0CPFzLgzoMvpLESFRgb ERgDujDJFCfMb28FRwGmeFj4mpUK1fIAZwU4rGjplrjyvAVRqdZzOykfoQqZkaxCu9MjKN CckTtCxTPA/IHldgpgeF49ygow7tOuM2OCoUIFk8clsnhxPSDmgsIXpll/bCWNebULVzea hRKI3u3EvoIT6Sg3QbBNkiH84eZsp/ZtQuusr0uZEChe1dDnOqjbaBuFWJ12WA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1719623543; a=rsa-sha256; cv=none; b=OXrH4LjGcLeohLURIaxBcyFTaRZfJxmLbnDM1zInJb0wxPaOZPSQ+pvIzDXBiSOvtjtLoA XK6ZcpR1tU8yUa/kB3SeDoafvgLNWm4Nmp/fzSJ7/8BoEqtneDofkf1zcCJqtA+8vxhIEA somE1hkbQ5o7uxtvdxLPfmPkLP/o4JfqqmpFCxjl7vGNSVHT1wdBeePdOBj0J8g7bzh0U6 /fda5GZ0vhx7pmoPAk6xbxbr1JhDtjmyvJ+lKmbYPcZX6/zyNv0IAOrySJETKezhU7c3FU iFT/sFHhzbFKntdUax0Dh+ZrxxZ1QIKzkvgtWBSCCLGQ9UdEP16PRK1dw3/OjQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20230601 header.b="RWw/Ydb1"; 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" 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 235F11258D for ; Sat, 29 Jun 2024 03:12:23 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sNMcz-00044T-5c; Fri, 28 Jun 2024 21:11:45 -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 1sNMcw-00043v-Vr for guix-devel@gnu.org; Fri, 28 Jun 2024 21:11:43 -0400 Received: from mail-qv1-xf33.google.com ([2607:f8b0:4864:20::f33]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1sNMcv-000775-1S for guix-devel@gnu.org; Fri, 28 Jun 2024 21:11:42 -0400 Received: by mail-qv1-xf33.google.com with SMTP id 6a1803df08f44-6b4fec3a1a7so6055366d6.2 for ; Fri, 28 Jun 2024 18:11:39 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1719623497; x=1720228297; darn=gnu.org; h=content-transfer-encoding:mime-version:user-agent:message-id:date :references:in-reply-to:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=kC8xEzRFfiixsNZ7PJ2+uwqj886uf8zd8XD34+Zt5bI=; b=RWw/Ydb1+4fgYIo5mncoOZ1+19l2uFlK6QQ1p73cA+6gAuwmNZYwwwFToNL0mc/1ax oDZ0xmuhCNiKLTUM7yq+K6cD4n9/pXMBsP8faDTh8Z5YeTrZaSk0ItVsUkiQFzCp9QuJ qrfEnlxiievAi7b8rCPaHT5PpRIdVSdg2FneFW9IE2sy1PEq99pu3r6+TZrbKHcEoRe/ RLwFoNDLMm9FuLiqIMnuiIo4J12ygYGywyYCK/mRYulShwo/Hsze8YtrTZjIpnbapixQ txc+ZpsKUe4Ib1HcQmfhVCWub11o276v4qwyWF3uIm/naZvueW/HodTOKBjb0f29szh4 gvkA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1719623497; x=1720228297; h=content-transfer-encoding:mime-version:user-agent:message-id:date :references:in-reply-to:subject:cc:to:from:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to; bh=kC8xEzRFfiixsNZ7PJ2+uwqj886uf8zd8XD34+Zt5bI=; b=tzgcsJOSd8ubQAUx5vWoGXC0RNo918ggdXRAlYTFKTOnDfLR8G/kpS+YRSz0wr0RJI 3/t+pQV8gzfaJkj3ejrDYbXlq3xQyqI0Obfa5Hc3LF3ln93Kk361HlFScH+im08E+DiX KcZqg2b7eE35ttCCsWC6OvPpqr/byEs/6/WBJNaHooDVdJvECtk2zWi0ewLkR1i3TJn4 ZLK4xmr++Pk3P9uJLlCn0Fr5ZB8InoYFFfIOcrTUBCo8uZ8ThpiTwXkZ2b3U/LU7f/xH /iiAO0B9xSWP6fBI+nF3a15jZIY3qcN5CmhZgz5NWoXx1zBB/YLFDvT6Xrcsnta9wEGp fltQ== X-Gm-Message-State: AOJu0YwLo9K8HdIcjOoDtuSw/HD/eaxB1feqIRNFgpVZTVvHG2/6srMk Mzw8CykNRIqJo9pFTA9hhMfH7176ll8bT0q9fGfwI6VfVIpwrwGmRfBGxg== X-Google-Smtp-Source: AGHT+IHgsrLaH0st864np/5lhuyule38fedvidq/VOE8tGWwSUS83D64GOT8VtkzE9QfvZ9pneUUJw== X-Received: by 2002:a05:6214:8b:b0:6b5:4573:4ac5 with SMTP id 6a1803df08f44-6b545734d10mr190913376d6.45.1719623496571; Fri, 28 Jun 2024 18:11:36 -0700 (PDT) Received: from hurd ([204.48.95.10]) by smtp.gmail.com with ESMTPSA id 6a1803df08f44-6b59e368b42sm12455096d6.24.2024.06.28.18.11.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 28 Jun 2024 18:11:36 -0700 (PDT) From: Maxim Cournoyer To: Richard Sent Cc: guix-devel@gnu.org Subject: Re: Codifying/Documenting Guix commit message conventions? In-Reply-To: <87bk3mvvfy.fsf@freakingpenguin.com> (Richard Sent's message of "Thu, 27 Jun 2024 19:04:49 -0400") References: <87bk3mvvfy.fsf@freakingpenguin.com> Date: Fri, 28 Jun 2024 21:11:34 -0400 Message-ID: <877ce8a6yh.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=2607:f8b0:4864:20::f33; envelope-from=maxim.cournoyer@gmail.com; helo=mail-qv1-xf33.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 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-Queue-Id: 235F11258D X-Migadu-Scanner: mx12.migadu.com X-Migadu-Spam-Score: -8.72 X-Spam-Score: -8.72 X-TUID: GaepPMkInOcE Hi Richard, Richard Sent writes: > Hi Guix, > > I noticed that there seems to be discrepencies between the GNU Changelog > format and Guix's commit message convention. For example, see these > lines from [1]. > >> Our convention for indicating conditional changes is to use _square >> brackets around the name of the condition_. >>=20 >> Conditional changes can happen in numerous scenarios and with many >> variations, so here are some examples to help clarify. This first >> example describes changes in C, Perl, and Python files which are >> conditional but do not have an associated function or entity name: >>=20 >> * xterm.c [SOLARIS2]: Include . > > Meanwhile in Guix commit messages, [foo] seems to be used to refer to a > subset of a larger part [2]: > >> * doc/guix.texi (Base Services)[extra-special-file]: Add warning regardi= ng >> files in /etc. > > From what I'm seeing, the GNU Changelog convention is to indicate > subsets using <> [3]. > >> * progmodes/sh-script.el (sh-while-getopts) : Handle case that >> user-specified option string is empty. > Brackets ([]) are often used in our ChangeLog commit messages to specify the field of a record. Arguably that should be enclosed in <>, perhaps. One gripe I have with <> is that Emacs/company-mode treat it as part of some symbol which makes completion (M-/) useless. That may be fixable with some configuration for commit message buffers. Another Emacs tip for those who don't know it yet: pressing 'C' (capital C) on a diff hunk while authoring a commit message using Magit will create some ChangeLog entry stub in the commit message buffer, which saves a lot of typing. Perhaps we should mention this in our doc, as it makes writing GNU ChangeLog less painful. > Guix states that commit messages should follow the ChangeLog format > and=E2=80=94as far as I can tell=E2=80=94leaves it at that with no mentio= n of > discrepencies or quirks [4]. > >> Please write commit logs in the ChangeLog format (*note >> (standards)Change Logs::); you can check the commit history for >> examples. > > My questions to the group are thus: > > 1. Is this in fact a discrepency between the GNU ChangeLog format and > Guix convention or am I missing something? > > 2. Are there other discrepencies out there that people know of? > > 3. How should we go about documenting Guix-specific conventions? I think we shouldn't create our own dialect of GNU ChangeLog if possible. Ideally we'd adopt it as-is and be able to simply continue pointing people to it. One problem is that it evolved through the years, so someone who read it 10 years ago may be doing it a bit differently. > I suspect another discrepency not mentioned is Guix's tendency to prefix > header lines with e.g. "doc:" or "gnu:". I haven't found a better way to > identify what to put for those besides viewing commits touching X file. > And if a commit evenly spans multiple categories it can sometimes be > blurry determining what fits best. These are "domain" prefixes; it denotes the part of the code base where the change occurred. Some are more obvious, some others less so. Documentation is tagged with a 'doc' prefix. Packages are tagged with 'gnu' as they form the GNU system distribution. Someone may use 'maint' to denote maintenance work or 'build' for build-system related changes, etc. These unfortunately no science behind these so it can be difficult for newcomers to learn what to use. It'd be nice to document a few of the most used ones in our contributing section. > Another one seems to be the [security fixes], [fixes CVE-...], and > [fixes TROVE-...] blocks added to certain header lines. What other tags > exist? There seems to be inconsistency here when referring to multiple > CVEs. For example, when a fixes tag references multiple CVEs you can > find. > > [fixes CVE-2020-10700, CVE-2020-10704] [5] > [fixes CVE-2020-3898 & CVE-2019-8842] [6] > [fixes CVE-2023-{28755, 28756}] [7] I think these are likely to bust the 70 characters limit for a git commit summary line, so perhaps we could standardize on [fixes CVE-XXX] for single CVEs or [security fixes] when there are more than one (listing the CVEs in the commit message body instead then). > I'm happy to write up documentation on best practices, but I figure a > general post on guix-devel is a good idea to make sure nothing's missed. > I'm not advocating for a new French revolution to overthrow the > ChangeLog aristocracy. That sounds like a good, incremental, non-controversial approach to the issues found (good observation, by the way!); I encourage you to pursue it. > [8] seems like a very interesting commit to analyze in terms of Guix > conventions since it deals with a dense, nontrivial package change and > refers to "sub-sub elements", which don't seem to be a thing in GNU > ChangeLog land. Eh, except for the duplicated Change-Id git trailer which slipped in (my bad!). --=20 Thanks, Maxim