From patchwork Wed Jul 26 03:04:57 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Arver X-Patchwork-Id: 13327384 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7D35EC001DF for ; Wed, 26 Jul 2023 03:05:17 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231152AbjGZDFQ (ORCPT ); Tue, 25 Jul 2023 23:05:16 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37312 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229755AbjGZDFL (ORCPT ); Tue, 25 Jul 2023 23:05:11 -0400 Received: from mail-wr1-x434.google.com (mail-wr1-x434.google.com [IPv6:2a00:1450:4864:20::434]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 786431BD1 for ; Tue, 25 Jul 2023 20:05:05 -0700 (PDT) Received: by mail-wr1-x434.google.com with SMTP id ffacd0b85a97d-3177163aa97so780088f8f.0 for ; Tue, 25 Jul 2023 20:05:05 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1690340704; x=1690945504; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=fUOGi/S8harMIkeMlwlGX4B7j1x/qNSxJP2y5l0vrds=; b=XnIgbLR+S22jjMncSse4OjVwy7sXvX/HprrKCbN78UjQl+FRb7IsUZ12NcuWY0+yzT 88jG2Is40vdiftxXfi9VZIoPpOTBXnWt6CybLSOvvVpiuqtoR4XpCPe+EAgItvjdwkKX dfAOofnE5B7pAvsX2YWprsOZ/1vJLNCpy3R9VhVx5bHQ3i2XvcqtsCt6bJvC45VQ4Q+U y+CKB6ogrkp6V1DP6utpcSLwe+Ok7jcSGwPtiXM6RCFMn7GSDa2ERxMF/rErcKcb6ySU mFJgODxJQ7e8pKqdAio3eMKxaMX6N4QWZbXw1wkHP91QoW3sSWTkVY0UXvK0zknkTu2H 2yPA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1690340704; x=1690945504; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=fUOGi/S8harMIkeMlwlGX4B7j1x/qNSxJP2y5l0vrds=; b=VjBzlIJ9b9eNAzUfc0P+shSvW5EBW/ffb4Wgd5m7ipE7uISM6BjEQhE+g+R016bBmu MJ6YbsS22eqX46FhttxsQjaIDMlxO9JZJQgGpg39Vi/U77Gm2JDFCFeftL5odtg9Ce+2 tM86jkm/SQJLSvbM1n7irlQA6l73z2T02zeBsHdchQs5VP3T6MIRRyR7hi4puAKMXfU5 pv6i5o46jdRUL1Szf7YWAKwkTQn4PQy+BoNsRYJOeAsdRYquuguHWNUCToShHm+Jp/X0 6aicT+OZdF5JoVQXaNN2LNCdCIkPUaPffGV38gseUH2mlg6g714+UU7Ojs5dEgzyf5Re tumQ== X-Gm-Message-State: ABy/qLZvFT5dCf/4GM1+CTPDO3x8Lp9wL4rH/POQnQ0iH/eVur+/BweB jgHghagw0A3LFXIqWEidaaCnggX7kYk= X-Google-Smtp-Source: APBJJlGuiGLYVjcgzfR2xBdUKTGrI1gFKlEaGBZvzy7m1ShgUU4vNyWmzq+ZWg81kiZUkr8+KmgXnw== X-Received: by 2002:adf:dec2:0:b0:314:2f5b:2ce with SMTP id i2-20020adfdec2000000b003142f5b02cemr461648wrn.12.1690340703564; Tue, 25 Jul 2023 20:05:03 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id i7-20020a05600011c700b00313fd294d6csm18204693wrx.7.2023.07.25.20.05.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Jul 2023 20:05:03 -0700 (PDT) Message-ID: <08deed14d960b0b7de56a023a1da6ab5280e04bb.1690340701.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 26 Jul 2023 03:04:57 +0000 Subject: [PATCH v3 1/5] SubmittingPatches: reword awkward phrasing Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Linus Arver , Linus Arver Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Linus Arver From: Linus Arver Signed-off-by: Linus Arver --- Documentation/SubmittingPatches | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index b218e273570..b89678cedc3 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -3,8 +3,8 @@ Submitting Patches == Guidelines -Here are some guidelines for people who want to contribute their code to this -software. There is also a link:MyFirstContribution.html[step-by-step tutorial] +Here are some guidelines for contributing back to this +project. There is also a link:MyFirstContribution.html[step-by-step tutorial] available which covers many of these same guidelines. [[base-branch]] From patchwork Wed Jul 26 03:04:58 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Arver X-Patchwork-Id: 13327386 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 7F67DEB64DD for ; Wed, 26 Jul 2023 03:05:24 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231182AbjGZDFW (ORCPT ); Tue, 25 Jul 2023 23:05:22 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37314 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231145AbjGZDFP (ORCPT ); Tue, 25 Jul 2023 23:05:15 -0400 Received: from mail-wr1-x42b.google.com (mail-wr1-x42b.google.com [IPv6:2a00:1450:4864:20::42b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 0AC5A1BDA for ; Tue, 25 Jul 2023 20:05:06 -0700 (PDT) Received: by mail-wr1-x42b.google.com with SMTP id ffacd0b85a97d-307d58b3efbso4897667f8f.0 for ; Tue, 25 Jul 2023 20:05:05 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1690340704; x=1690945504; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=kgE7BCdrkdi3NO+bbFytp6LnhzOcx40qeHgu/9tv0lg=; b=B9X2vTqUzsNZg37m5rNyvlpUuhEFupD4TbIoEfQZBT2nmpQgHqRB8GnE3SGyg49GQy cbqwHLePLxN12Tbxs5fWH5+FjpxbikkcQKefabtWTC1uZiPzYvUCQoziG641f0WyfBLC pb2guNcR6UA8mwPqkkDob27Tu7EdYAk5sK6vlfAaV+7jTZYZl2Tpprn0w6UUdsIuw3iF UgdWGh3rUH2RPew+5OSdF7ixrz4hGwW/iNilHNJyBF56khcgKqVEZxcxQH/o7R5umciN MsV3dMQ0uodfr754TOP7zfm/nibiVWhw/CbHKAjNvMrrfC4AsiFo2en1EJ8Pw6jKI1gx t1Hg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1690340704; x=1690945504; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=kgE7BCdrkdi3NO+bbFytp6LnhzOcx40qeHgu/9tv0lg=; b=IgJkgLmU9FIzoe/14GKrvKxKYW7l0KQ5+vUxXtXzA+tWx2e+dNiAtTAf8+CKZ/jI0H EEgoNocwWxSx2xzOY5P8wi9UEQSuVpBhYA3ARsjTeId3G0tSj2m54Mgr/TIB3NCQ0hyu b/YN81aZAiXdeVDwgFowoPxi3N2Dp3aojsGZlINcwMEo3Yu/Q8gaf0fYQ8enzd9BpNjc VEMJXUh/8kj8lwVGHdAYDjQMyEhuSBwHPVBP9KrE+3oZm4M8qTy6Tv7bmtWK2fqtlNg7 MIwRt1Q1PEy2fndeeIlxR0eZyd9FlBUyxh915J5AS1XgMiKeOd0TqtYTBWaFk95EYHas Gluw== X-Gm-Message-State: ABy/qLYRBcFiSSyciZdD1Ze9Xns0V5TcUgS0gxZM37kKFWf8DQkbCBse 1dQAzN7RqL+VIHbXEbYs10BdEaqgEek= X-Google-Smtp-Source: APBJJlEMEUZ9dVk1VNaEYwiGq8iMeNA+h8HFibpOjhPd0KEahqbohuXLEAokd/t5yZwN9bj2Jx8IXg== X-Received: by 2002:a5d:4405:0:b0:317:5cfb:714c with SMTP id z5-20020a5d4405000000b003175cfb714cmr337403wrq.25.1690340704015; Tue, 25 Jul 2023 20:05:04 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id q17-20020adff511000000b0031272fced4dsm18130659wro.52.2023.07.25.20.05.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Jul 2023 20:05:03 -0700 (PDT) Message-ID: <8d4b57a8704b658e5b4fd0d5e78a53e9bc327d22.1690340701.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 26 Jul 2023 03:04:58 +0000 Subject: [PATCH v3 2/5] SubmittingPatches: discuss subsystems separately from git.git Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Linus Arver , Linus Arver Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Linus Arver From: Linus Arver The discussion around subsystems disrupts the flow of discussion in the surrounding area, which only deals with starting points used for the git.git project. So move this bullet point out to the end. Signed-off-by: Linus Arver --- Documentation/SubmittingPatches | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index b89678cedc3..7919a362e31 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -35,14 +35,14 @@ change is relevant to. to stabilize, you would have to rebase it (see the "depends on other topics" above). -* Some parts of the system have dedicated maintainers with their own - repositories (see the section "Subsystems" below). Changes to - these parts should be based on their trees. - To find the tip of a topic branch, run `git log --first-parent master..seen` and look for the merge commit. The second parent of this commit is the tip of the topic branch. +Finally, note that some parts of the system have dedicated maintainers +with their own separate source code repositories (see the section +"Subsystems" below). + [[separate-commits]] === Make separate commits for logically separate changes. From patchwork Wed Jul 26 03:04:59 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Arver X-Patchwork-Id: 13327388 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id A4713C001DE for ; Wed, 26 Jul 2023 03:05:30 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231213AbjGZDF2 (ORCPT ); Tue, 25 Jul 2023 23:05:28 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37316 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231129AbjGZDFP (ORCPT ); Tue, 25 Jul 2023 23:05:15 -0400 Received: from mail-wm1-x331.google.com (mail-wm1-x331.google.com [IPv6:2a00:1450:4864:20::331]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 4C6A11BE8 for ; Tue, 25 Jul 2023 20:05:06 -0700 (PDT) Received: by mail-wm1-x331.google.com with SMTP id 5b1f17b1804b1-3fbc63c2e84so63328805e9.3 for ; Tue, 25 Jul 2023 20:05:06 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1690340704; x=1690945504; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=L5fOw66Oz/l74QmvF25VG2PF3rAhwtQYaMAuXKwfkGw=; b=cgnkNUOEt98/ydwJRzs9GFu5xpyoaw+5IJVl9IuWsW8ofiyPDpZDmU1BbDRY7bAZhA RK63ytB3X60jpoGZL9PNeJ0KC1dFL4NKzkoWiJpupXiTfaW7VdQCFftQmpxh7LLlku+m XWo2JOaq8WHfw4zYGqa3zoNyllQlJau56nrI/SoOe7vFawkbGdO2iNuvzIkHBzaZF75e GP4iGJE8R2+uOG8eQXse9NfcLKOsrpv2Uf9sOZx+sp6H1e8Ul+ZCLLgGSD6CnySBrHud ZNL9/ADQr12oZx1MzBPsLCEodb5Fv5TJ//jxszO3PVaA1s6xhbUsXOciyEZrLChB/5zS m/tg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1690340704; x=1690945504; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=L5fOw66Oz/l74QmvF25VG2PF3rAhwtQYaMAuXKwfkGw=; b=AGAW8GPT4KMs6cLwZ1xEoRuMb2SGDcGhNAljJoA5IBftZAV2Oq6d4QSb6UgD13NRst T0IXlQL/Ghv4nBIP38RjrvjXRZP3BBIBUImNoMAoy1+TvSDja+X/GOR0uSTF1gqdCAmr wLixnrGD0KlwH04XdwFbiWGLoNMm/QK75MPTmv7KEuI2RiBIjaTS+paAJhlW19PNVvaX +dVmSxZskwwKjI9up+E5urv8Q5d1SomJ0EE3X9PxWeYhB7T1RutpiQxSlpMSipd/DFKW qp12iPqu1IHj94c0G/yshpFskJldRlltSZdDbJYLM/mV0p88hJGPhS/KnCy+wJ4X62e1 xYyQ== X-Gm-Message-State: ABy/qLYk96GEFSJkjQBJCKjCo1xp6/AObdcHDRl/lpnznLMTitx7RaaM Hb8zZCoMz2z7bnJD3XCETNxhvff/4a4= X-Google-Smtp-Source: APBJJlHJoupCIvEscdPPinIZ8nG3rnMLn/3/dPLo8F9zFWOrnz1+xkl/5VLhgxiV+1M+jFaDQeSMrA== X-Received: by 2002:adf:fc05:0:b0:314:36c5:e4c0 with SMTP id i5-20020adffc05000000b0031436c5e4c0mr466515wrr.11.1690340704540; Tue, 25 Jul 2023 20:05:04 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id y19-20020a7bcd93000000b003fc06169ab3sm660629wmj.20.2023.07.25.20.05.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Jul 2023 20:05:04 -0700 (PDT) Message-ID: <69fef8afe64156a1f54e9e1b7bbcc73d2867695c.1690340701.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 26 Jul 2023 03:04:59 +0000 Subject: [PATCH v3 3/5] SubmittingPatches: de-emphasize branches as starting points Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Linus Arver , Linus Arver Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Linus Arver From: Linus Arver It could be that a suitable branch does not exist, so instead just use the phrase "starting point". Technically speaking the starting point would be a commit (not a branch) anyway. Helped-by: Junio C Hamano Signed-off-by: Linus Arver --- Documentation/SubmittingPatches | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 7919a362e31..f1d1446764b 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -7,8 +7,8 @@ Here are some guidelines for contributing back to this project. There is also a link:MyFirstContribution.html[step-by-step tutorial] available which covers many of these same guidelines. -[[base-branch]] -=== Decide what to base your work on. +[[choose-starting-point]] +=== Choose a starting point. In general, always base your work on the oldest branch that your change is relevant to. @@ -317,8 +317,8 @@ Please make sure your patch does not add commented out debugging code, or include any extra files which do not relate to what your patch is trying to achieve. Make sure to review your patch after generating it, to ensure accuracy. Before -sending out, please make sure it cleanly applies to the base you -have chosen in the "Decide what to base your work on" section, +sending out, please make sure it cleanly applies to the starting point you +have chosen in the "Choose a starting point" section, and unless it targets the `master` branch (which is the default), mark your patches as such. From patchwork Wed Jul 26 03:05:00 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Arver X-Patchwork-Id: 13327385 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 18B1FEB64DD for ; Wed, 26 Jul 2023 03:05:21 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231164AbjGZDFS (ORCPT ); Tue, 25 Jul 2023 23:05:18 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37318 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231131AbjGZDFP (ORCPT ); Tue, 25 Jul 2023 23:05:15 -0400 Received: from mail-wr1-x429.google.com (mail-wr1-x429.google.com [IPv6:2a00:1450:4864:20::429]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 077F41BF8 for ; Tue, 25 Jul 2023 20:05:07 -0700 (PDT) Received: by mail-wr1-x429.google.com with SMTP id ffacd0b85a97d-316feb137a7so5697662f8f.1 for ; Tue, 25 Jul 2023 20:05:06 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1690340705; x=1690945505; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=IbgEM1HQh+zxc0NneZWWB9vEKt28mfOkzWftFKcSRCg=; b=TWokkl11Di5dpHp4RVdGNNbW2sNiLzGqpKrVT+bRnKFjdwrDhXwHDc34XhJs+ofHXJ 7jrySwcn8AqH8RVRlszkBcZQ8VS+lzVkGBcEw68hK/xeWjMkWpP2pMjKQCAnVwwJn8Hf GvJOp0dj+vDsiJ/cxLd2tDU7awtZKzh+Z+peL1pL10JYIEgiVcYj1VISQ7DikdRmkm73 3Tp13F0nELGoz99UhhHpYfd0YGVgZnMI5hinPyMvwtQtjIBwrCxjikw4UUUgEdkgmtWY 4aTfZbdK7Cd7dSsWK6d958ywQxxRoTP+3+LBtCkKQqsi+279ZHymlk//fV3FSsdpIKtr DYgg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1690340705; x=1690945505; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=IbgEM1HQh+zxc0NneZWWB9vEKt28mfOkzWftFKcSRCg=; b=VR/JqC2dC/9G9qFF+5TZNhh8dieWqXAb64djJUHidMuuVdIsaIQFUC7AtaG9gLIFh6 ljouwYk6/RQcLdv31r5K9dh6IFCUeUe/P/zdAfXzw4SRCNY+Ta0ivDtFr3f1sGv778Nj LZ7oBPXIPmGpJDY5OAvyE5OXMa8k5s8Vb6iwYmO4GsRs7rZp1HYNAxUCFgh/z7+ODwtA nhJD462FmyDgzBnD4UduvJfozgPmq/rN2GAxYAXn/7kEJRvrGYaSU6Gmx+yWqsTGkKdK aLAX81SIKR/J762LIWEfm6Wthf4oMFqi+/phU+GcpAe2YWTOpdkMrP5fUBhyr88oZAAV xqrQ== X-Gm-Message-State: ABy/qLZ4tHGFmJEtTKf8MmNMDWPvW+B3z2Qv6VYaHh9spiXZLlhEDoPj nPMxoSaqaPzfoPBfhf8O8cItzP3l6kA= X-Google-Smtp-Source: APBJJlElB1C+KNQs7cc5LGsvoZazcITCcmiQNhItW78N21xB7IGqR1HCrAlVf0PmjCeN4B0Qh2Eqvg== X-Received: by 2002:a5d:444f:0:b0:30f:d218:584a with SMTP id x15-20020a5d444f000000b0030fd218584amr371559wrr.23.1690340705284; Tue, 25 Jul 2023 20:05:05 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id s11-20020a5d4ecb000000b003144b50034esm18170926wrv.110.2023.07.25.20.05.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Jul 2023 20:05:04 -0700 (PDT) Message-ID: In-Reply-To: References: Date: Wed, 26 Jul 2023 03:05:00 +0000 Subject: [PATCH v3 4/5] SubmittingPatches: emphasize need to communicate non-default starting points Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Linus Arver , Linus Arver Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Linus Arver From: Linus Arver The phrase and unless it targets the `master` branch (which is the default), mark your patches as such. is tightly packed with several things happening in just two lines of text. It also feels like it is not that important because of the terse treatment. This is a problem because (1) it has the potential to confuse new contributors, and (2) it may be glossed over for those skimming the docs. Emphasize and elaborate on this guidance by promoting it to its own separate paragraph. Signed-off-by: Linus Arver --- Documentation/SubmittingPatches | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index f1d1446764b..40467372c0d 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -318,9 +318,12 @@ or include any extra files which do not relate to what your patch is trying to achieve. Make sure to review your patch after generating it, to ensure accuracy. Before sending out, please make sure it cleanly applies to the starting point you -have chosen in the "Choose a starting point" section, -and unless it targets the `master` branch (which is the default), -mark your patches as such. +have chosen in the "Choose a starting point" section. + +NOTE: From the perspective of those reviewing your patch, the `master` +branch is the default expected starting point. So if you have chosen a +different starting point, please communicate this choice in your cover +letter. [[send-patches]] From patchwork Wed Jul 26 03:05:01 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Arver X-Patchwork-Id: 13327387 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id D1339C001DE for ; Wed, 26 Jul 2023 03:05:26 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231176AbjGZDFZ (ORCPT ); Tue, 25 Jul 2023 23:05:25 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:37320 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231149AbjGZDFP (ORCPT ); Tue, 25 Jul 2023 23:05:15 -0400 Received: from mail-wm1-x32f.google.com (mail-wm1-x32f.google.com [IPv6:2a00:1450:4864:20::32f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 413991BFA for ; Tue, 25 Jul 2023 20:05:08 -0700 (PDT) Received: by mail-wm1-x32f.google.com with SMTP id 5b1f17b1804b1-3fbc5d5742bso63306735e9.2 for ; Tue, 25 Jul 2023 20:05:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1690340706; x=1690945506; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:from:to:cc:subject:date :message-id:reply-to; bh=hySmWU7x/kfBtFCVeRCwBytWjCDEYpGXg7PK34zGjxg=; b=RxnljFwa1rSdHV5EZr/Ur+JmHqsa0GjA0Fy9FFIbo/5Trqbc3HKQtbg+k9leGLQeSH GBrks+7cI2GpONJLzRCmWzmegdGB+0OODoxvlJcqsR/zqZJOZ6w5UCt2oNom7JdeE3vJ 5/d88w/IaNeuE6EIXlp/4UUu8vBEGLwb+QJHKeeN7tuzcL7IB3zEl8GNKekDe7IVmVzy sAK1DJacKHDQ3t0ZHkgSLRYgQXjDent+Wlccv3lOdG8c2I+oG+3XstDDDd+YzBFb6aua 9tequCCOgdpueZ2PgRxZFVfIgKc594HxIRI6TljKtMmcdvsE+u54hj3uRb+Uv5ONX3+h j1eQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1690340706; x=1690945506; h=cc:to:mime-version:content-transfer-encoding:fcc:subject:date:from :references:in-reply-to:message-id:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=hySmWU7x/kfBtFCVeRCwBytWjCDEYpGXg7PK34zGjxg=; b=Ziia0g8ANfXsMF5qIm+kP7DT1dVDIvqBAZkSmZ4KepTut+LIi+UIgGUGRYfjj/zjtw hCLz3ZgtLkLQMxRzvD0zCqKg0+RjcSPCYJ2Y9GkKJ3SkeM2whvcYskKRHk658qukLyH/ qmEZJ7daPruDYserf0Nz8ATHU/LDuBwXPhvSKskQNmxMCtpm64SDKKJp8XYwgRjYqQ0K o69KCuz+kPPrqj108kEtMSnkqX6IvnW2TN5dWFk2jyV9ekCd/mbrrQZOjcl5zjAakrmn ySDSAJg7x4o87jlImg0REc2cU+UhNFyfE5a11gCqpLm6Aq4hmkVKiNbbaMA0/wPaookc C6sQ== X-Gm-Message-State: ABy/qLb4RXWjQbbF7OSiKI8swVC2ZDImELz9sQTcAOBQuIistKY+yyTU ICemD2SgJWg9Qvp9+/giG8w4UvArmNE= X-Google-Smtp-Source: APBJJlEvTni1PpkQTwcCnJgYgTz31CsRH1pjr3XyN6zAijnPrT7CfenUH/oteXidYZZ+xsDnz/8bzw== X-Received: by 2002:a7b:ca51:0:b0:3fb:b530:a4e4 with SMTP id m17-20020a7bca51000000b003fbb530a4e4mr492029wml.8.1690340706027; Tue, 25 Jul 2023 20:05:06 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id k5-20020a5d6285000000b0031455482d1fsm18308425wru.47.2023.07.25.20.05.05 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Jul 2023 20:05:05 -0700 (PDT) Message-ID: <1273f50c8a884e6afc5be6cb10fe178ed8efbede.1690340701.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Wed, 26 Jul 2023 03:05:01 +0000 Subject: [PATCH v3 5/5] SubmittingPatches: simplify guidance for choosing a starting point Fcc: Sent MIME-Version: 1.0 To: git@vger.kernel.org Cc: Linus Arver , Linus Arver Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org From: Linus Arver From: Linus Arver Background: The guidance to "base your work on the oldest branch that your change is relevant to" was added in d0c26f0f56 (SubmittingPatches: Add new section about what to base work on, 2010-04-19). That commit also added the bullet points which describe the scenarios where one would use one of the following named branches: "maint", "master", "next", and "seen" ("pu" in the original as that was the name of this branch before it was renamed, per 828197de8f (docs: adjust for the recent rename of `pu` to `seen`, 2020-06-25)). The guidance was probably taken from existing similar language introduced in the "Merge upwards" section of gitworkflows in f948dd8992 (Documentation: add manpage about workflows, 2008-10-19). Summary: This change simplifies the guidance by pointing users to just "maint" or "master" for most cases. But it also gives an explanation of why that is preferred and what is meant by preferring "older" branches (which might be confusing to some because "old" here is meant in relative terms between these named branches, not in terms of the age of the branches themselves). We also explain in detail why it would be a bad idea to use "next" or "seen" as starting points, which may not be so obvious to new contributors. Helped-by: Jonathan Nieder Helped-by: Junio C Hamano Signed-off-by: Linus Arver --- Documentation/SubmittingPatches | 105 +++++++++++++++++++++++--------- 1 file changed, 77 insertions(+), 28 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 40467372c0d..559c02c90c5 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,34 +10,83 @@ available which covers many of these same guidelines. [[choose-starting-point]] === Choose a starting point. -In general, always base your work on the oldest branch that your -change is relevant to. - -* A bugfix should be based on `maint` in general. If the bug is not - present in `maint`, base it on `master`. For a bug that's not yet - in `master`, find the topic that introduces the regression, and - base your work on the tip of the topic. - -* A new feature should be based on `master` in general. If the new - feature depends on other topics that are in `next`, but not in - `master`, fork a branch from the tip of `master`, merge these topics - to the branch, and work on that branch. You can remind yourself of - how you prepared the base with `git log --first-parent master..`. - -* Corrections and enhancements to a topic not yet in `master` should - be based on the tip of that topic. If the topic has not been merged - to `next`, it's alright to add a note to squash minor corrections - into the series. - -* In the exceptional case that a new feature depends on several topics - not in `master`, start working on `next` or `seen` privately and - send out patches only for discussion. Once your new feature starts - to stabilize, you would have to rebase it (see the "depends on other - topics" above). - -To find the tip of a topic branch, run `git log --first-parent -master..seen` and look for the merge commit. The second parent of this -commit is the tip of the topic branch. +As a preliminary step, you must first choose a starting point for your +work. Typically this means choosing a branch, although technically +speaking it is actually a particular commit (typically the HEAD, or tip, +of the branch). + +There are several important branches to be aware of. Namely, there are +four integration branches as discussed in linkgit:gitworkflows[7]: + +* maint +* master +* next +* seen + +The branches lower on the list are typically descendants of the ones +that come before it. For example, `maint` is an "older" branch than +`master` because `master` usually has patches (commits) on top of +`maint`. + +There are also "topic" branches, which contain work from other +contributors. Topic branches are created by the Git maintainer (in +their fork) to organize the current set of incoming contributions on +the mailing list, and are itemized in the regular "What's cooking in +git.git" announcements. To find the tip of a topic branch, run `git log +--first-parent master..seen` and look for the merge commit. The second +parent of this commit is the tip of the topic branch. + +There is one guiding principle for choosing the right starting point: in +general, always base your work on the oldest integration branch that +your change is relevant to (see "Merge upwards" in +linkgit:gitworkflows[7]). What this principle means is that for the +vast majority of cases, the starting point for new work should be the +latest HEAD commit of `maint` or `master` based on the following cases: + +* If you are fixing bugs in the released version, use `maint` as the + starting point (which may mean you have to fix things without using + new API features on the cutting edge that recently appeared in + `master` but were not available in the released version). If the bug + exists in an older version (e.g., commit `X` introduced the bug, and + `git describe --containx X` says `v2.30.0-rc2-gXXXXXX` has it), then + use the tip of the maintenance branch for the 2.30.x versions in the + `maint-2.30` branch in https://github.com/gitster/git[the maintainer's + repo]. + +* Otherwise (such as if you are adding new features) use `master`. + +This also means that `next` or `seen` are inappropriate starting points +for your work, if you want your work to have a realistic chance of +graduating to `master`. They are simply not designed to be used as a +base for new work; they are only there to make sure that topics in +flight work well together. This is why both `next` and `seen` are +frequently re-integrated with incoming patches on the mailing list and +force-pushed to replace previous versions of themselves. A topic that is +literally built on top of `next` cannot be merged to 'master' without +dragging in all the other topics in `next`, some of which may not be +ready. + +For example, if you are making tree-wide changes, while somebody else is +also making their own tree-wide changes, your work may have severe +overlap with the other person's work. This situation may tempt you to +use `next` as your starting point (because it would have the other +person's work included in it), but doing so would mean you'll not only +depend on the other person's work, but all the other random things from +other contributors that are already integrated into `next`. And as soon +as `next` is updated with a new version, all of your work will need to +be rebased anyway in order for them to be cleanly applied by the +maintainer. + +Under truly exceptional circumstances where you absolutely must depend +on a select few topic branches that are already in `next` but not in +`master`, you may want to create your own custom base-branch by forking +`master` and merging the required topic branches to it. You could then +work on top of this base-branch. But keep in mind that this base-branch +would only be known privately to you. So when you are ready to send +your patches to the list, be sure to communicate how you created it in +your cover letter. This critical piece of information would allow +others to recreate your base-branch on their end in order for them to +try out your work. Finally, note that some parts of the system have dedicated maintainers with their own separate source code repositories (see the section From patchwork Wed Jul 26 05:16:49 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Junio C Hamano X-Patchwork-Id: 13327495 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 45A35C001DC for ; Wed, 26 Jul 2023 05:16:57 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231221AbjGZFQ4 (ORCPT ); Wed, 26 Jul 2023 01:16:56 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:56158 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229939AbjGZFQz (ORCPT ); Wed, 26 Jul 2023 01:16:55 -0400 Received: from pb-smtp20.pobox.com (pb-smtp20.pobox.com [173.228.157.52]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id ADB4A1FEF for ; Tue, 25 Jul 2023 22:16:54 -0700 (PDT) Received: from pb-smtp20.pobox.com (unknown [127.0.0.1]) by pb-smtp20.pobox.com (Postfix) with ESMTP id 4E9203593C; Wed, 26 Jul 2023 01:16:54 -0400 (EDT) (envelope-from junio@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; s=sasl; bh=Rww6tjc0mCUkrQWJqOsjP+MxEXwkBstCE5OWlM pHIUc=; b=ew6WxNKP/PCrIdaGky9tRsnQdhsB65J2SEHtAzAOYj9b+uJwfoPPxN v76CGNCAzqc0hKkPPxDmHeCF7jtXcavGvWWfRW/LEzEDxkcj+1Eekfha92/saXSn oj7yqLA09euzvzvcYFp4pmXsenEbYE81nrkz1r0yhXvkWjtufXsrM= Received: from pb-smtp20.sea.icgroup.com (unknown [127.0.0.1]) by pb-smtp20.pobox.com (Postfix) with ESMTP id 47ABD3593B; Wed, 26 Jul 2023 01:16:54 -0400 (EDT) (envelope-from junio@pobox.com) Received: from pobox.com (unknown [34.168.215.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp20.pobox.com (Postfix) with ESMTPSA id D7F563593A; Wed, 26 Jul 2023 01:16:50 -0400 (EDT) (envelope-from junio@pobox.com) From: Junio C Hamano To: "Linus Arver via GitGitGadget" Cc: git@vger.kernel.org, Linus Arver Subject: [PATCH v3 6/5] SubmittingPatches: choice of base for fixing an older maintenance track References: Date: Tue, 25 Jul 2023 22:16:49 -0700 In-Reply-To: (Linus Arver via GitGitGadget's message of "Wed, 26 Jul 2023 03:04:56 +0000") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.2 (gnu/linux) MIME-Version: 1.0 X-Pobox-Relay-ID: A07F7EE6-2B73-11EE-8C42-C2DA088D43B2-77302942!pb-smtp20.pobox.com Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org When working on an high-value bugfix that must be given to ancient maintenance tracks, a starting point that is older than `maint` may have to be chosen. Helped-by: Linus Arver Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index f1774c91e9..d1e3783978 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -46,7 +46,12 @@ latest HEAD commit of `maint` or `master` based on the following cases: * If you are fixing bugs in the released version, use `maint` as the starting point (which may mean you have to fix things without using new API features on the cutting edge that recently appeared in - `master` but were not available in the released version). + `master` but were not available in the released version). If the bug + exists in an older version (e.g., commit `X` introduced the bug, and + `git describe --containx X` says `v2.30.0-rc2-gXXXXXX` has it), then + use the tip of the maintenance branch for the 2.30.x versions in the + `maint-2.30` branch in https://github.com/gitster/git[the maintainer's + repo]. * Otherwise (such as if you are adding new features) use `master`. From patchwork Wed Jul 26 05:17:31 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Junio C Hamano X-Patchwork-Id: 13327496 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 496A8C001DE for ; Wed, 26 Jul 2023 05:17:39 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231547AbjGZFRh (ORCPT ); Wed, 26 Jul 2023 01:17:37 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:56586 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230119AbjGZFRf (ORCPT ); Wed, 26 Jul 2023 01:17:35 -0400 Received: from pb-smtp1.pobox.com (pb-smtp1.pobox.com [64.147.108.70]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 952B51FEF for ; Tue, 25 Jul 2023 22:17:34 -0700 (PDT) Received: from pb-smtp1.pobox.com (unknown [127.0.0.1]) by pb-smtp1.pobox.com (Postfix) with ESMTP id 9B147194272; Wed, 26 Jul 2023 01:17:33 -0400 (EDT) (envelope-from junio@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; s=sasl; bh=JZfBDq9spURqZIx7Qx7/7lojV32Zo7YOW/NAET yIhDc=; b=qdcUjvQ2lbSShk1+ofhChxV/WXgjpY4InmlsPFoX4aO9E/w88rkhNn CvsiYj5oqRdmMn7gsLEIv53LP+R/gf53qr2IIK51Q6cF6rdiULxy9OIDrgsGEl20 JIm7W1Sb0YxV5DAxogRHWgHhb2A/mojlJPvRBs0amTi/LV8kZ2Hjo= Received: from pb-smtp1.nyi.icgroup.com (unknown [127.0.0.1]) by pb-smtp1.pobox.com (Postfix) with ESMTP id 939A8194270; Wed, 26 Jul 2023 01:17:33 -0400 (EDT) (envelope-from junio@pobox.com) Received: from pobox.com (unknown [34.168.215.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp1.pobox.com (Postfix) with ESMTPSA id 0807D19426E; Wed, 26 Jul 2023 01:17:32 -0400 (EDT) (envelope-from junio@pobox.com) From: Junio C Hamano To: "Linus Arver via GitGitGadget" Cc: git@vger.kernel.org, Linus Arver Subject: [PATCH 7/5] SubmittingPatches: explain why 'next' and above are inappropriate base References: Date: Tue, 25 Jul 2023 22:17:31 -0700 In-Reply-To: (Linus Arver via GitGitGadget's message of "Wed, 26 Jul 2023 03:04:56 +0000") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.2 (gnu/linux) MIME-Version: 1.0 X-Pobox-Relay-ID: B99ED39A-2B73-11EE-B3F1-C65BE52EC81B-77302942!pb-smtp1.pobox.com Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org The 'next' branch is primarily meant to be a testing ground to make sure that topics that are reasonably well done work well together. Building a new work on it would mean everything that was already in 'next' must have graduated to 'master' before the new work can also be merged to 'master', and that is why we do not encourage basing new work on 'next'. Helped-by: Linus Arver Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index d1e3783978..559c02c90c 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -57,10 +57,14 @@ latest HEAD commit of `maint` or `master` based on the following cases: This also means that `next` or `seen` are inappropriate starting points for your work, if you want your work to have a realistic chance of -graduating to `master`. They are simply not designed to provide a -stable base for new work, because they are (by design) frequently -re-integrated with incoming patches on the mailing list and force-pushed -to replace previous versions of these branches. +graduating to `master`. They are simply not designed to be used as a +base for new work; they are only there to make sure that topics in +flight work well together. This is why both `next` and `seen` are +frequently re-integrated with incoming patches on the mailing list and +force-pushed to replace previous versions of themselves. A topic that is +literally built on top of `next` cannot be merged to 'master' without +dragging in all the other topics in `next`, some of which may not be +ready. For example, if you are making tree-wide changes, while somebody else is also making their own tree-wide changes, your work may have severe From patchwork Wed Jul 26 05:21:12 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Junio C Hamano X-Patchwork-Id: 13327497 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id ED861C001DC for ; Wed, 26 Jul 2023 05:21:20 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231755AbjGZFVU (ORCPT ); Wed, 26 Jul 2023 01:21:20 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:58028 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231537AbjGZFVQ (ORCPT ); Wed, 26 Jul 2023 01:21:16 -0400 Received: from pb-smtp2.pobox.com (pb-smtp2.pobox.com [64.147.108.71]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id AF56B212A for ; Tue, 25 Jul 2023 22:21:14 -0700 (PDT) Received: from pb-smtp2.pobox.com (unknown [127.0.0.1]) by pb-smtp2.pobox.com (Postfix) with ESMTP id C081518D170; Wed, 26 Jul 2023 01:21:13 -0400 (EDT) (envelope-from junio@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to:cc :subject:references:date:in-reply-to:message-id:mime-version :content-type; s=sasl; bh=feGVh5+VPKCNMdgjZrajPyz5wu8ot2dQ+x8tRA qV5YQ=; b=A9qdX+ZNKnSOL7pd1xEyjG3DIKyacWoVTFzLqmMisZNw04214ae/Hz flEm17AEDsYStwdBttLvaZ+G5YYy3BYP1nOI9G9ZTFPurYCbI0cb2z/BXoJBIigC JADYyLEVdzIkmyMUkhS19dt3nhiNtexisjtICjKdTTvY41v6upp+I= Received: from pb-smtp2.nyi.icgroup.com (unknown [127.0.0.1]) by pb-smtp2.pobox.com (Postfix) with ESMTP id B80ED18D16F; Wed, 26 Jul 2023 01:21:13 -0400 (EDT) (envelope-from junio@pobox.com) Received: from pobox.com (unknown [34.168.215.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp2.pobox.com (Postfix) with ESMTPSA id 26FD118D16E; Wed, 26 Jul 2023 01:21:13 -0400 (EDT) (envelope-from junio@pobox.com) From: Junio C Hamano To: "Linus Arver via GitGitGadget" Cc: git@vger.kernel.org, Linus Arver Subject: [PATCH 8/5] SubmittingPatches: use of older maintenance tracks is an exception References: Date: Tue, 25 Jul 2023 22:21:12 -0700 In-Reply-To: (Linus Arver via GitGitGadget's message of "Wed, 26 Jul 2023 03:04:56 +0000") Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.2 (gnu/linux) MIME-Version: 1.0 X-Pobox-Relay-ID: 3CD426C0-2B74-11EE-85C2-307A8E0A682E-77302942!pb-smtp2.pobox.com Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org While we could technically fix each and every bug on top of the commit that introduced it, it is not necessarily practical. For trivial and low-value bugfixes, it often is simpler to just fix it in the current maintenance track, leaving the bug unfixed in the older maintenance tracks. Demote the "use older maintenance track" as a side note, and explain that the choice is used only in exceptional cases. Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 559c02c90c..0d1b53d4e5 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -46,15 +46,22 @@ latest HEAD commit of `maint` or `master` based on the following cases: * If you are fixing bugs in the released version, use `maint` as the starting point (which may mean you have to fix things without using new API features on the cutting edge that recently appeared in - `master` but were not available in the released version). If the bug - exists in an older version (e.g., commit `X` introduced the bug, and - `git describe --containx X` says `v2.30.0-rc2-gXXXXXX` has it), then - use the tip of the maintenance branch for the 2.30.x versions in the - `maint-2.30` branch in https://github.com/gitster/git[the maintainer's - repo]. + `master` but were not available in the released version). * Otherwise (such as if you are adding new features) use `master`. + +NOTE: In an exceptional case, a bug that was introduced in an old +version may have to be fixed for users of releases that are much older +than the recent releases. `git describe --contains X` may describe +`X` as `v2.30.0-rc2-gXXXXXX` for the commit `X` that introduced the +bug, and the bug may be so high-impact that we may need to issue a new +maintenance release for Git 2.30.x series, when "Git 2.41.0" is the +current release. In such a case, you may want to use the tip of the +maintenance branch for the 2.30.x series, which may be available as +`maint-2.30` branch in https://github.com/gitster/git[the maintainer's +"broken out" repo]. + This also means that `next` or `seen` are inappropriate starting points for your work, if you want your work to have a realistic chance of graduating to `master`. They are simply not designed to be used as a