From patchwork Wed Nov 1 19:23:23 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Maxim Cournoyer X-Patchwork-Id: 55805 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 2B8F727BBE9; Wed, 1 Nov 2023 19:24:47 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-2.7 required=5.0 tests=BAYES_00,DKIM_ADSP_CUSTOM_MED, DKIM_INVALID,DKIM_SIGNED,FREEMAIL_FROM,MAILING_LIST_MULTI, SPF_HELO_PASS,URIBL_BLOCKED autolearn=unavailable autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id EC30627BBE2 for ; Wed, 1 Nov 2023 19:24:44 +0000 (GMT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qyGpM-00073B-KR; Wed, 01 Nov 2023 15:24:32 -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 1qyGpH-00072q-LH for guix-patches@gnu.org; Wed, 01 Nov 2023 15:24:27 -0400 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qyGpH-00016W-DW for guix-patches@gnu.org; Wed, 01 Nov 2023 15:24:27 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qyGpp-00086p-RS for guix-patches@gnu.org; Wed, 01 Nov 2023 15:25:01 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#66436] [PATCH v3] doc: Add some guidelines for reviewing. References: <19f82d9bbef649c750ad067d23ebbaee6f9ae494.1696942467.git.maxim.cournoyer@gmail.com> In-Reply-To: <19f82d9bbef649c750ad067d23ebbaee6f9ae494.1696942467.git.maxim.cournoyer@gmail.com> Resent-From: Maxim Cournoyer Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Wed, 01 Nov 2023 19:25:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 66436 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 66436@debbugs.gnu.org Cc: dev@jpoiret.xyz, ludo@gnu.org, Maxim Cournoyer , zimon.toutoune@gmail.com Received: via spool by 66436-submit@debbugs.gnu.org id=B66436.169886669731157 (code B ref 66436); Wed, 01 Nov 2023 19:25:01 +0000 Received: (at 66436) by debbugs.gnu.org; 1 Nov 2023 19:24:57 +0000 Received: from localhost ([127.0.0.1]:52631 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qyGph-00086P-0V for submit@debbugs.gnu.org; Wed, 01 Nov 2023 15:24:57 -0400 Received: from mail-oi1-x232.google.com ([2607:f8b0:4864:20::232]:58626) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qyGpb-000861-7K for 66436@debbugs.gnu.org; Wed, 01 Nov 2023 15:24:51 -0400 Received: by mail-oi1-x232.google.com with SMTP id 5614622812f47-3b2e22f1937so102256b6e.1 for <66436@debbugs.gnu.org>; Wed, 01 Nov 2023 12:24:12 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1698866645; x=1699471445; darn=debbugs.gnu.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=MT+IFg4AWRv1indXPxhlaNjkH1oet2eprYbXtuE6ekM=; b=nplUeaQsCzb8STk2LaB3Fdts5kZhy/qmstR7zt1nxEl0JEYUj8mS8uB3CTZHdXiZHn uU5L8NsvvUl8Ki+OT+uZRM26EDevPgRCfX5tVYXwqSage370vSqHV0CxiZ0zX4kIogCV /FjHl1OztiZnS1bQpjl4U9uDW4JXVH8X54uz+Cmh+ibqhkkJHr63qKUTx0sXvVJHp4aL kwkYRVshvUsrP+M/Ek9UQQjAEyuWDRorN244kpBDf8yPRL/UMye2umrr58J1jFkmI16o 8Fujl4ZfUREvaPQWxS4jQHPlSR1VAFrznCe2q5BiPl2451EahUgFzSSPVjFIyhrgAY4Z InuA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1698866645; x=1699471445; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=MT+IFg4AWRv1indXPxhlaNjkH1oet2eprYbXtuE6ekM=; b=k6i21nNmaRWO3wjY40C1TvygDCdCZ++JOZ4WGku0NXyCtLbgahsUMpP8sRa5SdOTy+ xNNZPYrWPn7+hfjliH/Hdp4qkTU1KyPnDBnGA/Sz5wUTSwRJCC1U9r+YLPXQhl/GtoT6 eKEuhdOyWkxVu3oOc33RnD09nd5SyHPDMACCPkocFeZ+JmBFxuRyMUKmieYiNfyA1/AQ 0C77vts4NiYpJ0q1SzZ+LaYWsmf7+CqESxYI+3OmH3VrqmA0AYC+CzEgj9mtJUJIqkSS MEMhND1Rjv+ylMIdD5vTUYpgD9/t+1M/GCuiZxTkpjWKIxHdJkW2Llgzugb7PR2LtEQ+ Jxxg== X-Gm-Message-State: AOJu0Yzmju3M+v1MBqKTS/lurUCJxA2losUFU5cmw8/BSO8AfBx6ptR/ CBPWv3f5emsjbVGhgK9q3nXewFg1AIKGoQ== X-Google-Smtp-Source: AGHT+IECKeayhCkcCdWN4HLvLYVNpa41isQzRz650PuyKRNfPnb8sTe21MBJ2lI4DcBuDHiBo81UUA== X-Received: by 2002:a05:6808:1a02:b0:3ae:5c48:6f42 with SMTP id bk2-20020a0568081a0200b003ae5c486f42mr21875136oib.5.1698866644965; Wed, 01 Nov 2023 12:24:04 -0700 (PDT) Received: from localhost.localdomain (dsl-10-128-239.b2b2c.ca. [72.10.128.239]) by smtp.gmail.com with ESMTPSA id u29-20020a05620a085d00b00775afce4235sm1677940qku.131.2023.11.01.12.24.02 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 01 Nov 2023 12:24:03 -0700 (PDT) From: Maxim Cournoyer Date: Wed, 1 Nov 2023 15:23:23 -0400 Message-ID: X-Mailer: git-send-email 2.41.0 MIME-Version: 1.0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches * doc/contributing.texi (Contributing) [Reviewing the Work of Others]: New section. (Debbugs Usertags): Expound with Emacs Debbugs information and document the 'reviewed-looks-good' usertag. Change-Id: I56630b15ec4fbc5c67e5420dbf2838556a005d6b --- Changes in v3: - Replace LGTM with Reviewed-by Git tag - Add b4 config - Link to the Submitting Patches section for check list - Fuse further suggestions by both Ludovic and Simon doc/contributing.texi | 111 ++++++++++++++++++++++++++++++++++++++++-- etc/git/gitconfig | 7 +++ 2 files changed, 114 insertions(+), 4 deletions(-) base-commit: a96f1c1bc0fa186414359890025e8acacbb1de02 diff --git a/doc/contributing.texi b/doc/contributing.texi index 30876447d4..023478c98d 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -29,6 +29,7 @@ Contributing * Submitting Patches:: Share your work. * Tracking Bugs and Changes:: Keeping it all organized. * Commit Access:: Pushing to the official repository. +* Reviewing the Work of Others:: Some guidelines for sharing reviews. * Updating the Guix Package:: Updating the Guix package definition. * Writing Documentation:: Improving documentation in GNU Guix. * Translating Guix:: Make Guix speak your native language. @@ -1981,7 +1982,12 @@ Debbugs Usertags tag any bug with an arbitrary label. Bugs can be searched by usertag, so this is a handy way to organize bugs@footnote{The list of usertags is public information, and anyone can modify any user's list of usertags, -so keep that in mind if you choose to use this feature.}. +so keep that in mind if you choose to use this feature.}. If you use +Emacs Debbugs, the entry-point to consult existing usertags is the +@samp{C-u M-x debbugs-gnu-usertags} procedure. To set a usertag, press +@samp{C} while consulting a bug within the *Guix-Patches* buffer opened +with @samp{C-u M-x debbugs-gnu-bugs} buffer, then select @code{usertag} +and follow the instructions. For example, to view all the bug reports (or patches, in the case of @code{guix-patches}) tagged with the usertag @code{powerpc64le-linux} @@ -1994,9 +2000,9 @@ Debbugs Usertags to interact with Debbugs. In Guix, we are experimenting with usertags to keep track of -architecture-specific issues. To facilitate collaboration, all our -usertags are associated with the single user @code{guix}. The following -usertags currently exist for that user: +architecture-specific issues, as well as reviewed ones. To facilitate +collaboration, all our usertags are associated with the single user +@code{guix}. The following usertags currently exist for that user: @table @code @@ -2014,6 +2020,9 @@ Debbugs Usertags appropriate to assign this usertag to a bug report for a package that fails to build reproducibly. +@item reviewed-looks-good +You have reviewed the series and it looks good to you (LGTM). + @end table If you're a committer and you want to add a usertag, just start using it @@ -2283,6 +2292,100 @@ Commit Access you're welcome to use your expertise and commit rights to help other contributors, too! +@node Reviewing the Work of Others +@section Reviewing the Work of Others + +Perhaps the biggest action you can do to help GNU Guix grow as a project +is to review the work contributed by others. You do not need to be a +committer to do so; applying, reading the source, building, linting and +running other people's series and sharing your comments about your +experience will give some confidence to committers. Basically, you gmust +ensure the check list found in the @ref{Submitting Patches} section has +been correctly followed. A reviewed patch series should give the best +chances for the proposed change to be merged faster, so if a change you +would like to see merged hasn't yet been reviewed, this is the most +appropriate thing to do! + +@cindex reviewing, guidelines +Review comments should be unambiguous; be as clear and explicit as you +can about what you think should be changed, ensuring the author can take +action on it. Please try to keep the following guidelines in mind +during review: + +@enumerate +@item +@emph{Be clear and explicit about changes you are suggesting}, ensuring +the author can take action on it. In particular, it is a good idea to +explicitly ask for new revisions when you want it. + +@item +@emph{Remain focused: do not change the scope of the work being +reviewed.} For example, if the contribution touches code that follows a +pattern deemed unwieldy, it would be unfair to ask the submitter to fix +all occurrences of that pattern in the code; to put it simply, if a +problem unrelated to the patch at hand was already there, do not ask the +submitter to fix it. + +@item +@emph{Ensure progress.} As they respond to review, submitters may +submit new revisions of their changes; avoid requesting changes that you +did not request in the previous round of comments. Overall, the +submitter should get a clear sense of progress; the number of items open +for discussion should clearly decrease over time. + +@item +@emph{Aim for finalization.} Reviewing code is time-consuming. Your +goal as a reviewer is to put the process on a clear path towards +integration, possibly with agreed-upon changes, or rejection, with a +clear and mutually-understood reasoning. Avoid leaving the review +process in a lingering state with no clear way out. + +@item +@emph{Review is a discussion.} The submitter's and reviewer's views on +how to achieve a particular change may not always be aligned. To lead +the discussion, remain focused, ensure progress and aim for +finalization, spending time proportional to the stakes@footnote{The +tendency to discuss minute details at length is often referred to as +``bikeshedding'', where much time is spent discussing each one's +preference for the color of the shed at the expense of progress made on +the project to keep bikes dry.}. As a reviewer, try hard to explain the +rationale for suggestions you make, and to understand and take into +account the submitter's motivation for doing things in a certain way. +@end enumerate + +@cindex LGTM, Looks Good To Me +@cindex review tags +@cindex Reviewed-by, git trailer +When you deem the proposed change adequate and ready for inclusion +within Guix, the following well understood/codified +@samp{Reviewed-by:@tie{}Your@tie{}Name} +@footnote{The @samp{Reviewed-by} Git trailer is used by other projects +such as Linux, and is understood by third-party tools such as the +@samp{b4 am} sub-command, which is able to retrieve the complete +submission email thread from a public-inbox instance and add the Git +trailers found in replies to the commit patches.} line should be used to +sign off as a reviewer, meaning you have reviewed the change and that it +looks good to you: + +@itemize +@item +If the @emph{whole} series (containing multiple commits) looks good to +you, reply with @samp{Reviewed-by:@tie{}Your@tie{}Name} +to the cover page if it has one, or to the last patch of the series +otherwise, adding another @samp{(for the whole series)} comment on the +line below to explicit this fact. + +@item +If you instead want to mark a @emph{single commit} as reviewed (but not +the whole series), simply reply with +@samp{Reviewed-by:@tie{}Your@tie{}Name} to that +commit message. +@end itemize + +If you are not a committer, you can help others find a @emph{series} you +have reviewed more easily by adding a @code{reviewed-looks-good} usertag +for the @code{guix} user (@pxref{Debbugs Usertags}). + @node Updating the Guix Package @section Updating the Guix Package diff --git a/etc/git/gitconfig b/etc/git/gitconfig index 907ad01804..654a630b18 100644 --- a/etc/git/gitconfig +++ b/etc/git/gitconfig @@ -16,3 +16,10 @@ to = guix-patches@gnu.org headerCmd = etc/teams.scm cc-members-header-cmd thread = no + +[b4] + attestation-check-dkim = off + attestation-policy = off + linkmask = https://yhetil.org/guix/%s + linktrailermask = https://yhetil.org/guix/%s + midmask = https://yhetil.org/guix/%s