From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id 2HaRKWvwfWZ2gQEA62LTzQ:P1 (envelope-from ) for ; Thu, 27 Jun 2024 23:06:19 +0000 Received: from aspmx1.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1.migadu.com with LMTPS id 2HaRKWvwfWZ2gQEA62LTzQ (envelope-from ) for ; Fri, 28 Jun 2024 01:06:19 +0200 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=none ("invalid DKIM record") header.d=freakingpenguin.com header.s=x header.b=rEZj8aq2; 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=1719529579; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=wGXDm6/yRxC0oLGD9AzhLegcCN9POwQtDq4y4LdU2V0=; b=FUf/+FW+4DT6C/EE/6SJ7X54E4H16ixY/7KG5dbqaKaWtbUS6e8p6S6tDpqZqL2jr6eIK3 Ft05TR8h89FPcA04je1Z3qj0zOe8KlfcONrPJAKWB7enwuX8hpyvf5y6GKiPoxBF2KlUSJ VbXrnr+vTA2n23o6HLMwD9gx3dPtr2u7mQRqvA1NBPhUQHt780nvwfuVl4Q+UP0UKSQj5E kVzLV+cRRz3SumUFtePmyYzsi7UXb3ZNeX4/8JrvaESjRz23fM6w8loSv9ahqoEpMBZ3wS UlHp80sXlksRHq7oEWf/zDmwIGvWjRcKjKLkMbOVUIWhm1Fto2KB41ARWgGXFA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=none ("invalid DKIM record") header.d=freakingpenguin.com header.s=x header.b=rEZj8aq2; 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-Seal: i=1; s=key1; d=yhetil.org; t=1719529579; a=rsa-sha256; cv=none; b=kfwuKdgeviVbEytLw50O3jugs6f28ZWzJepmmzEUt/JmJNReUe0FtSoI6EWb/FZURb/F8Q 1kVOVzNOWU2jINnm8cbVWm857Nqw3zu0AQ8ga3Op9uvXIZzCxnYqAMk4I7HgHxd1ZNiYuO iG+s4av5fFVsue83gr87+Q3ANU8YHyMNmNH0+flv6pRvbTuLv/BfnGSTJG0ganSfDNMUTS MueYe62ySqmkQo+4DKI2ZxF5isi6GdBc3U07uRTNj0MO3Cr+0le+ZiSFUzRZIqYQbzSR7q ywbwuy8xPikxBzVUJPnQ2F5UvDMc/Gfu6bz7Pyrv6yuWIhv41wJLP7MLB3Klkg== 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 56732EE94 for ; Fri, 28 Jun 2024 01:06:18 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sMyB0-0002qT-Q2; Thu, 27 Jun 2024 19:05:14 -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 1sMyAw-0002qJ-VC for guix-devel@gnu.org; Thu, 27 Jun 2024 19:05:10 -0400 Received: from mail-108-mta173.mxroute.com ([136.175.108.173]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1sMyAu-0001Qz-4D for guix-devel@gnu.org; Thu, 27 Jun 2024 19:05:10 -0400 Received: from filter006.mxroute.com ([136.175.111.3] filter006.mxroute.com) (Authenticated sender: mN4UYu2MZsgR) by mail-108-mta173.mxroute.com (ZoneMTA) with ESMTPSA id 1905bf1f23100017a3.001 for (version=TLSv1.3 cipher=TLS_AES_256_GCM_SHA384); Thu, 27 Jun 2024 23:05:01 +0000 X-Zone-Loop: 3dd13131925583dff2922cf38a962d0fa855f4bcd2b0 X-Originating-IP: [136.175.111.3] DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=freakingpenguin.com; s=x; h=Content-Transfer-Encoding:Content-Type: MIME-Version:Message-ID:Date:Subject:To:From:Sender:Reply-To:Cc:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:In-Reply-To:References:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=wGXDm6/yRxC0oLGD9AzhLegcCN9POwQtDq4y4LdU2V0=; b=rEZj8aq2VAWi8DThS8lgRbw3kf isYSVY6mFhGvp+MvDQyz1KiMhSnc7AHP/oZhRYuIpvL8+P9fbw6KvV/dTpQ8Ensg/k/yUhVxYmAVa uQtZHbZmgmvKYKIgmv09y5K2OH84sKGb9IgPfTbt1bHro45ZMUYY0otFocLa+lIJW4dqVimCDZGsG fuunl9nojNdCiA2MYgXRWr9WVSJyW9JpoDTJBCvgrq+iObnch7cfMFLM80vavumR5379AvRYW6Cpw E84iYvqZZAICFqDG6QhWj/ZRaJZ2dZKqatGfChdk8cZ7wDG31TWiJvawoeud1WS4Xu1zysl9vGsxu dBwk+Fog==; From: Richard Sent To: guix-devel@gnu.org Subject: Codifying/Documenting Guix commit message conventions? Date: Thu, 27 Jun 2024 19:04:49 -0400 Message-ID: <87bk3mvvfy.fsf@freakingpenguin.com> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Authenticated-Id: richard@freakingpenguin.com Received-SPF: pass client-ip=136.175.108.173; envelope-from=richard@freakingpenguin.com; helo=mail-108-mta173.mxroute.com 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, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 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: , 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-Spam-Score: -5.37 X-Migadu-Queue-Id: 56732EE94 X-Migadu-Scanner: mx10.migadu.com X-Migadu-Spam-Score: -5.37 X-TUID: az4SdhIbQSVC 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 regarding > 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. 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 mention = 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 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. 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'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. [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. [1]: (standards) Conditional Changes [2]: Guix commit 398393187cc48f449215b14cf18b13fefb228558 [3]: (standards) Indicating the Part Changed [4]: (guix) Submitting Patches [5]: 62881ad61c [6]: a9ca7998f7 [7]: cd0a8950e4 [8]: 77d949c812 --=20 Take it easy, Richard Sent Making my computer weirder one commit at a time.