From patchwork Fri Jul 14 06:01:29 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Arver X-Patchwork-Id: 13312969 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 928A7EB64DA for ; Fri, 14 Jul 2023 06:01:51 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234937AbjGNGBs (ORCPT ); Fri, 14 Jul 2023 02:01:48 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:43896 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234676AbjGNGBk (ORCPT ); Fri, 14 Jul 2023 02:01:40 -0400 Received: from mail-wm1-x32b.google.com (mail-wm1-x32b.google.com [IPv6:2a00:1450:4864:20::32b]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 8F91D2D43 for ; Thu, 13 Jul 2023 23:01:39 -0700 (PDT) Received: by mail-wm1-x32b.google.com with SMTP id 5b1f17b1804b1-3fc03aa6e04so14072075e9.2 for ; Thu, 13 Jul 2023 23:01:39 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1689314498; x=1691906498; 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=nfr35yMklnU6PAVEx5zZcn8m07NqyGyICtLgYZjr/NCQbnLR14TPfXfhTGvOnj6QId ylY3ZTDRfupwBINnxo791GMq1UcCTN7t7zljXnK1UZAcBbyvE9Wz3n1y8h6sKGreFQx0 tGewUR9HGjDN/6sTKorIg2O/85q357YzVfNpQPfr0BNnuna05Li6+wVqkdYQW4jIhlvV QpnNRgk/FYYgDOAY7/z2gA4fxoVFlPtH1nvB4XqVxW/pxckNipMLBUUwi71A3tEwTFaC oExRfRmDU1CxPu5IGx3QnUbxB/nV3tN/AKFjSBaz986WzAh2BAGrOLvijQ0/K9xT6Kw4 K0dw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1689314498; x=1691906498; 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=SK7tOFtHaxNgpw180TpmwqH6l2YJL6x/2SdRpZB34ipVWP2JxuOkKLZ+UdiWrz81q6 nUUYzDmmrWh1/5claHqPn4MkDdcDeKrUeC6cye9URp1P5FWxHHooE28ySwTz/PKFh3Ue mEnOhohbgwMe//TN+YK+NM7SrYUKH2su5+1qxi2K/1rbB/JkiB+MDafhOoOgOjUF3cDv jB54ifncFkkMPx3zpRsGZaItp+NbeNSvSHRvnAuSI+qwjnE98FURms2Oi69nGU0R1Cgm 9hz5N44rP5Es2RpKoTu9R58IxLg2S30KRTayHJpH5FlPrjectKb4cP2jn2MU53lDT5Tz U5sA== X-Gm-Message-State: ABy/qLYn09ViO3vG78NAkg80IQPgjVK1HPvM/YXxH0WJfUHgRrzR5vdf JSpZODnL6PGBwohH2B5IQJ6G5q6CLiE= X-Google-Smtp-Source: APBJJlGqmsQ1cSYBVc9Zfqmq1Df+wFWeY+ZVF5TbQvvYgYyYr4TaPzdUxXOE6+y474vBXYIN2zcP8Q== X-Received: by 2002:a1c:4b11:0:b0:3fa:962e:e8f4 with SMTP id y17-20020a1c4b11000000b003fa962ee8f4mr2969963wma.26.1689314497680; Thu, 13 Jul 2023 23:01:37 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id p17-20020a05600c205100b003fc01f7b415sm587834wmg.39.2023.07.13.23.01.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 13 Jul 2023 23:01:37 -0700 (PDT) Message-ID: <08deed14d960b0b7de56a023a1da6ab5280e04bb.1689314493.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Fri, 14 Jul 2023 06:01:29 +0000 Subject: [PATCH v2 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 Fri Jul 14 06:01:30 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Arver X-Patchwork-Id: 13312968 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 C2234C001B0 for ; Fri, 14 Jul 2023 06:01:46 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S234780AbjGNGBo (ORCPT ); Fri, 14 Jul 2023 02:01:44 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:43678 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234552AbjGNGBl (ORCPT ); Fri, 14 Jul 2023 02:01:41 -0400 Received: from mail-lf1-x132.google.com (mail-lf1-x132.google.com [IPv6:2a00:1450:4864:20::132]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id A302B2D46 for ; Thu, 13 Jul 2023 23:01:40 -0700 (PDT) Received: by mail-lf1-x132.google.com with SMTP id 2adb3069b0e04-4fb5bcb9a28so2512377e87.3 for ; Thu, 13 Jul 2023 23:01:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1689314499; x=1691906499; 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=YFqkUoblgoSiajWLoicZWNkoqHurAah+K/vxBHbtCXXxfOnnnUgWL6UeQZhsvu7/rM ZCoub2Mir9sbObRAyrQIXp0zWQQ1bm0o3qmQajC473sYkhmecQN/Tf2WGt1AH7qRd/87 ANXWkZ+NhdWTwYEMtfJAconOvXFkrVsbaJ6FFCuRB1DgKlqZu5hTvOpXqtnvLMNHWY7L mbqoyo4ZlOKCXDj+08lvdzQLsKLEoRnIC4v238u2Se7x0HZUBoFG936RREg5YwixVpF3 0lzsVbZd5QP2j15VOIG+OBaOMDiO7QyXvzRqoELm2tSRyQqMOMo/E8g98GqPnmdisZFO vDuw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1689314499; x=1691906499; 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=PtvFYmvYHB4JeyfbeEECsmr07ohcWS0DsorwuDY9F0U+GUD4Av9Epzp48ZCYPVwNDX 6TyZ5STABeksBcoWwVYlxZbuQhID8h2Ld9dz5Npeuf3qpLESmoIfr1e9JpX9YstU8HCC btRiSDwDni0w7cdL7mNTfiqk4aRF9Cxf+7SMkqDgFuzIBofySDM7AKAbf5li2j2vwt1k O0K8ARKN7L0FwhDbm0sicTG4bH+XrPckI/Iabb0O9p010NJhDWeNoseTH6KwCCOruHEt oZxXLe/xoav5+3UthLkZ0ty4obTTYAdMrPOgIxuAXsc63Codg6CaxNnA/yB6M4g5SBFk XUxw== X-Gm-Message-State: ABy/qLaB4R+1xnRdxY2kwsG/yrYUTnyPVS8sgLFwe5XohMp7VniFIkn8 i60H3dD0ijtYf/XvpuUvCc9btqSEKd8= X-Google-Smtp-Source: APBJJlGRj0kqgKNEboNWNJspqRky8uvGUFkBtIY7HaKhKcPfNyDVdHBzpd8BgBUDVLZJo4C/HnbJFA== X-Received: by 2002:a2e:9c93:0:b0:2b6:c16a:db06 with SMTP id x19-20020a2e9c93000000b002b6c16adb06mr3302417lji.39.1689314498678; Thu, 13 Jul 2023 23:01:38 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id n23-20020a1c7217000000b003fc0505be19sm587713wmc.37.2023.07.13.23.01.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 13 Jul 2023 23:01:38 -0700 (PDT) Message-ID: <8d4b57a8704b658e5b4fd0d5e78a53e9bc327d22.1689314493.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Fri, 14 Jul 2023 06:01:30 +0000 Subject: [PATCH v2 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 Fri Jul 14 06:01:31 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Arver X-Patchwork-Id: 13312970 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 52378EB64DC for ; Fri, 14 Jul 2023 06:01:53 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S235002AbjGNGBv (ORCPT ); Fri, 14 Jul 2023 02:01:51 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44504 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234710AbjGNGBm (ORCPT ); Fri, 14 Jul 2023 02:01:42 -0400 Received: from mail-wr1-x433.google.com (mail-wr1-x433.google.com [IPv6:2a00:1450:4864:20::433]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id ACAB92D45 for ; Thu, 13 Jul 2023 23:01:41 -0700 (PDT) Received: by mail-wr1-x433.google.com with SMTP id ffacd0b85a97d-31441dfbf97so1725882f8f.1 for ; Thu, 13 Jul 2023 23:01:41 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1689314500; x=1691906500; 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=M0CgdJnP8BkiAaulQWz7QV6xT3eU9317PAN3uoxoi8qbdkFIzepZH8NvAaOxX6xEEi X/uoplFhIT8d2CH7wmQQj4Zv6WYWlCRXn6iAP1vhRhGowQN6j/yZyZZW6EromXrrK2fS cz7FWZ7m6a+z6UUIaShxIaNJBXpCNOCJrOXEnEVh7Ry/XfbukxHWcVWUeoQjJqQ5AX30 hZMhA9U7EJMAG3OGLjDSjz/S4LSW74hDFrJPQ7EGJbTXzmKusjkZ21XCeOTCdJmshoG6 BXQCti9KLqnbQcye5/6K9jYT3ZCGe2Vox7z2++odSzJOpWIbl3m3YPw12BLpZDPlRo6j Hk5g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1689314500; x=1691906500; 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=fo+dw4DIAV80BKVGVFhlyOubSfI4sbVrnikSceFhxSjW1f2mffshitrpFs86ywV27Y Thx0C+2weSf06Kzmiocsnd/+rQHXzJwNXbE9M48QGclkCdU5FOnxRS4znSGUbPDrB3iu Xwrko8+pKytFjZ3YYQzlxg/sXWaNfO06Ii0UJ8/A1DrQ9g4e4Cz0C7aU4dytExig9jxt V49l9YMx8eZhQIv73C+p0787gleBIjwOYX/NKZspVxpCWdnPnmBMDY5eFI4sPi0DLSwq FHgLGbs6rEWShLC120MOMSMvY09yIHSu8TwWetJ7MrAGdjTaTlZFuVQc7EcVp/BKddTw 24Vw== X-Gm-Message-State: ABy/qLY6ezgy9SAQWihAC+7A8oafV767CL/koXXmb/dmFCF2bPnUAoCT WhD31xXdBwqTS3MwohbtZJh1Vk0EyJc= X-Google-Smtp-Source: APBJJlFkfA0ogaIWA0QsRE4tV2EiHH7Gq3Aqg7Jdo65vHyHmKUtoTNl9FLSMKFGcElwrowyc/9sVLg== X-Received: by 2002:a05:6000:18d:b0:314:4ba7:b024 with SMTP id p13-20020a056000018d00b003144ba7b024mr3765334wrx.9.1689314499847; Thu, 13 Jul 2023 23:01:39 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id v16-20020a5d6790000000b003112ab916cdsm9937434wru.73.2023.07.13.23.01.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 13 Jul 2023 23:01:39 -0700 (PDT) Message-ID: <69fef8afe64156a1f54e9e1b7bbcc73d2867695c.1689314493.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Fri, 14 Jul 2023 06:01:31 +0000 Subject: [PATCH v2 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 Fri Jul 14 06:01:32 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Arver X-Patchwork-Id: 13312971 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 41DD7EB64DC for ; Fri, 14 Jul 2023 06:02:02 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S235015AbjGNGB6 (ORCPT ); Fri, 14 Jul 2023 02:01:58 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44510 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234775AbjGNGBn (ORCPT ); Fri, 14 Jul 2023 02:01:43 -0400 Received: from mail-wm1-x32c.google.com (mail-wm1-x32c.google.com [IPv6:2a00:1450:4864:20::32c]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 836F32D43 for ; Thu, 13 Jul 2023 23:01:42 -0700 (PDT) Received: by mail-wm1-x32c.google.com with SMTP id 5b1f17b1804b1-3fbc5d5746cso14183425e9.2 for ; Thu, 13 Jul 2023 23:01:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1689314501; x=1691906501; 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=YyCzzsfuaNQng95+LskkSrluycAfe3jE+/nDdT3k0Nu7SGJeq/eUz8HZpJkd5Eiu6k AtBklGqz6AYr7jSoTrzd1vb8yFid3e2FXY0Ap4sydgLotIJM8feQJ9TSdto0HEQKOuA6 6VL/5cBPJI/WdNiRxNDPqc1hJ63G8yy/kMC2hRslfCy67a/nDiQHbjL4A/ONwm+R71L4 qvw/cpOKDMXZZJUFb1KnSDzstpgk3r7o0z/VDlaNbEEkISL+0T4aAtBjLQWFUcyu7pbs PoExHYncQ5fnoaisiobgkdNeuKQaBZw/rjlN4HeIwCzCl8O2MtQA2tB0tFdjvhj36mBW dwCA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1689314501; x=1691906501; 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=TFT/spgd61awizTIsF6lJVgUwCPTUarRmUjdh4xfYwFjn24HJDS+EsD0R9D21ov1WS APEczQhkc096J9as3Wbjd/glZgeyhJ/xzZybQo3yz/fAOpA9MrN83KaCivWQgeaNAIKC b6VyqF8GUTdUL6Hty0c9oC6fvzeLOEHur2ipvOiKXP0e2kzYGed8oxRUrPUJEwafhb8D QUifFTSMLfF1BKeb8nB2u1hJC5rt14IGMcbptQ8kZF8B9StNTql0woO9dcFmPNYNCj8M D772gOmiiDmLmX7SPCymUlZDdLd/zIE02t7FE72TN5HCvYZaOgG04bRGeNfWRxJ/JpqT UQDA== X-Gm-Message-State: ABy/qLbnO4IqBryIFxyIn/RcIWMMF2gUT1P/D2H4mZwFkqAwkgDdCN4t Gtn7UMs8aDlEqkAYJZ4XlkVsszyA3QM= X-Google-Smtp-Source: APBJJlHZZTZGjgxSKUqSMxc53sBemQ3/X1+yg6P7ik5gdfS535NIRA4x1FMGrIzhTGHvWOj4sw7k4g== X-Received: by 2002:a05:600c:b57:b0:3f9:b17a:cb61 with SMTP id k23-20020a05600c0b5700b003f9b17acb61mr3236353wmr.13.1689314500843; Thu, 13 Jul 2023 23:01:40 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id b16-20020a5d5510000000b0031417b0d338sm9840861wrv.87.2023.07.13.23.01.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 13 Jul 2023 23:01:40 -0700 (PDT) Message-ID: In-Reply-To: References: Date: Fri, 14 Jul 2023 06:01:32 +0000 Subject: [PATCH v2 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 Fri Jul 14 06:01:33 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Linus Arver X-Patchwork-Id: 13312972 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 34807EB64DC for ; Fri, 14 Jul 2023 06:02:05 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S232666AbjGNGCE (ORCPT ); Fri, 14 Jul 2023 02:02:04 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:44520 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S234843AbjGNGBp (ORCPT ); Fri, 14 Jul 2023 02:01:45 -0400 Received: from mail-wm1-x333.google.com (mail-wm1-x333.google.com [IPv6:2a00:1450:4864:20::333]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id C58802D45 for ; Thu, 13 Jul 2023 23:01:43 -0700 (PDT) Received: by mail-wm1-x333.google.com with SMTP id 5b1f17b1804b1-3fbc12181b6so14837565e9.2 for ; Thu, 13 Jul 2023 23:01:43 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1689314502; x=1691906502; 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=Od1fD7yLr8jKEtZ3kaTZ6Ig2iw/IIdNioHnxhqZ3/vA=; b=KC4bz2l3i62NKotqWiCeQ5IhU9rOHv2X/LcSMwyQjPp8jCQ6ivjZNCt6F5bxfMIVza H/eDA8fZ8gbCx92H6XiZBb5mfX2PNAsJIspPhpj4xDGgfZzsn0sfvHdf0959Meqf17V8 e7SlAZ0xEJhZdM4Tj7A+9vJiKTNkfSAACJok74immvjeS+vxLkv3GszDFNeS7yCQy0UT y+FgZcUWtTZA5sNXmtKGT4lRHxaoKEkbVKsDDLccxM73kRjYgKud09yt2WzSOZ8EirnD IXkNV0Ex+HS4qDce4xDKXs/OSHOYayylbaJoDdsxBLnt91Qc9euvOcuUk737SFLNj9// fMVQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1689314502; x=1691906502; 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=Od1fD7yLr8jKEtZ3kaTZ6Ig2iw/IIdNioHnxhqZ3/vA=; b=OcWAm4pPqyEqfvAYWt9qbd7oAiRISu2UBZBoibIXds/ZYm03MoKcnm2zKC3L3h/6n7 XOMharfw8mVB1VR9tGF7oDpMVMiDYfYbcwQccaN//VFzOPy90NLZjmvb4+ot1Ljm4t+g Lf2NgZxx4ZSKpWx8F59wN/QYNP/RA9Z//jzz4MjHLp+DKeBtVRSPeM/KeJ8m0mTeaQxk A4ZahRsUVJzL/jMKv49ZKtXK/eTo703t5UdVZ3FGYjfxeu1R+fxUCUA7zAaIIHvBTNVB TiEEefhOdLLa07WcePpU0GYv6gSkQPdTnDOXmnMzI0wWKu8GuVDgVdgR1ka7RVZ4AkHi iS4Q== X-Gm-Message-State: ABy/qLZa0AKHdPwXs1H8Ddc9M7aim6MYAIUymVwOxLDzCUMDTZD5b/Bm RSxRTxADzQy5PozxeAclTPRKx/1yyvI= X-Google-Smtp-Source: APBJJlExtY15RnlxqVZ0zbBdTP7ngsCD9//bOkKzN0f1WkE7hxtAj/0C6+ow3ZhBn3ZI0t7UjZP37Q== X-Received: by 2002:a05:600c:22d7:b0:3fb:e2af:49f6 with SMTP id 23-20020a05600c22d700b003fbe2af49f6mr2920056wmg.39.1689314501890; Thu, 13 Jul 2023 23:01:41 -0700 (PDT) Received: from [127.0.0.1] ([13.74.141.28]) by smtp.gmail.com with ESMTPSA id 5-20020a05600c024500b003fba6709c68sm590617wmj.47.2023.07.13.23.01.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 13 Jul 2023 23:01:41 -0700 (PDT) Message-ID: <5ec91d02b7ae767cc9b2395e1c0fa10e1424c0c5.1689314493.git.gitgitgadget@gmail.com> In-Reply-To: References: Date: Fri, 14 Jul 2023 06:01:33 +0000 Subject: [PATCH v2 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". 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 add an example to illustrate why it would be a bad idea to use "next" as a starting point, 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 | 96 +++++++++++++++++++++++---------- 1 file changed, 68 insertions(+), 28 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 40467372c0d..f1774c91e9c 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,34 +10,74 @@ 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). + +* 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 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. + +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