From: Karthik Nayak <karthik.188@gmail.com>
To: Junio C Hamano <gitster@pobox.com>, git@vger.kernel.org
Subject: Re: [PATCH 2/2] SubmittingPatches: extend the "flow" section
Date: Fri, 10 May 2024 03:08:59 -0700 [thread overview]
Message-ID: <CAOLa=ZS_5+x7_xxppD8BE7RA0X+BFHPm=ffWg4JDgORqR5=sqQ@mail.gmail.com> (raw)
In-Reply-To: <20240509211318.641896-3-gitster@pobox.com>
[-- Attachment #1: Type: text/plain, Size: 7866 bytes --]
Junio C Hamano <gitster@pobox.com> writes:
> Explain a full lifecycle of a patch series upfront, so that it is
> clear when key decisions to "accept" a series is made and how a new
> patch series becomes a part of a new release.
>
> Earlier, we described an idealized patch flow that nobody followed
> in practice. Instead, describe what flow was used in practice for
> the past decade that worked well for us.
>
> Fold the "you need to monitor the progress of your topic" section
> into the primary "patch lifecycle" section, as that is one of the
> things the patch submitter is responsible for.
>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> Documentation/SubmittingPatches | 112 +++++++++++++++++++-------------
> 1 file changed, 68 insertions(+), 44 deletions(-)
>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 142b82a71b..8922aae4a5 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -8,53 +8,76 @@ project. There is also a link:MyFirstContribution.html[step-by-step tutorial]
> available which covers many of these same guidelines.
>
> [[patch-flow]]
> -=== An ideal patch flow
> -
> -Here is an ideal patch flow for this project the current maintainer
> -suggests to the contributors:
> -
> -. You come up with an itch. You code it up.
> -
> -. Send it to the list and cc people who may need to know about
> - the change.
> +=== A not-so ideal patch flow
> +
> +To help us understand the reason behind various guidelines given later
> +in the document, first lets understand how the lifecycle of a typical
> +patch series for this project goes.
> +
> +. You come up with an itch. You code it up. You do not need any
> + pre-authorization from the project to do so. Your patches will be
Wouldn't it be better to have the following sentences after the next
para?
So the flow would be
- Have an itch. Code it up.
- Send patches to list.
- Get reviews.
> + reviewed by other contributors on the mailing list, and the reviews
> + will be done to assess the merit of various things, like the general
> + idea behind your patch (including "is it solving a problem worth
> + solving in the first place?"), the reason behind the design of the
> + solution, and the actual implementation.
> +
> +. You send the patches to the list and cc people who may need to know
> + about the change. Your goal is *not* necessarily to convince others
> + that what you are building is a good idea. Your goal is to get help
> + in coming up with a solution for the "itch" that is better than what
> + you can build alone.
> +
> -The people who may need to know are the ones whose code you
> -are butchering. These people happen to be the ones who are
> +The people who may need to know are the ones who worked on the code
> +you are touching. These people happen to be the ones who are
This reads much _nicer_.
> most likely to be knowledgeable enough to help you, but
> -they have no obligation to help you (i.e. you ask for help,
> -don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would
> +they have no obligation to help you (i.e. you ask them for help,
> +you don't demand). +git log -p {litdd} _$area_you_are_modifying_+ would
> help you find out who they are.
>
> -. You get comments and suggestions for improvements. You may
> - even get them in an "on top of your change" patch form.
> -
> -. Polish, refine, and re-send to the list and the people who
> - spend their time to improve your patch. Go back to step (2).
> -
> -. The list forms consensus that the last round of your patch is
> - good. Send it to the maintainer and cc the list.
> -
> -. A topic branch is created with the patch and is merged to `next`,
> - and cooked further and eventually graduates to `master`.
> -
> -In any time between the (2)-(3) cycle, the maintainer may pick it up
> -from the list and queue it to `seen`, in order to make it easier for
> -people to play with it without having to pick up and apply the patch to
> -their trees themselves.
> -
> -[[patch-status]]
> -=== Know the status of your patch after submission
> -
> -* You can use Git itself to find out when your patch is merged in
> - master. `git pull --rebase` will automatically skip already-applied
> - patches, and will let you know. This works only if you rebase on top
> - of the branch in which your patch has been merged (i.e. it will not
> - tell you if your patch is merged in `seen` if you rebase on top of
> - master).
> +. You get comments and suggestions for improvements. You may even get
> + them in an "on top of your change" patch form. You are expected to
> + respond to them with "Reply-All" on the mailing list, while taking
> + them into account while preparing an updated set of patches.
> +
> +. Polish, refine, and re-send your patches to the list and the people who
> + spent their time to improve your patch. Go back to step (2).
> +
> +. While the above iterations improve your patches, the maintainer may
> + pick the patches up from the list and queue them to the `seen`
> + branch, in order to make it easier for people to play with it
> + without having to pick up and apply the patches to their trees
> + themselves. Being in `seen` has no other meaning. Specifically, it
> + does not mean the patch was "accepted" in any way.
> +
> +. When the discussion reaches a consensus that the latest iteration of
> + the patches are in good enough shape, the maintainer includes the
> + topic in the "What's cooking" report that are sent out a few times a
> + week to the mailing list, marked as "Will merge to 'next'." This
> + decision is primarily made by the maintainer with the help from
> + reviewers.
> +
> +. Once the patches hit 'next', the discussion can still continue to
> + further improve them by adding more patches on top, but by the time
> + a topic gets merged to 'next', it is expected that everybody agreed
> + that the scope and the basic direction of the topic are appropriate,
> + so such an incremental updates are expected to be limited to small
> + corrections and polishing. After a topic cooks for some time (like
> + 7 calendar days) in 'next' without further tweaks on top, it gets
> + merged to the 'master' branch and wait to become part of the next
> + major release.
> +
> +Earlier versions of this document outlined a slightly different patch
> +flow in an idealized world, where the original submitter gathered
> +agreements from the participants of the discussion and sent the final
> +"we all agreed that this is the good version--please apply" patches
> +to the maintainer. In practice, this almost never happened. The flow
> +described above reflects the reality much better and can be considered
> +the "canonical" procedure to get the patch accepted to the project.
> +
> +In the following sections, many techniques and conventions are listed
> +to help your patches get reviewed effectively.
>
> -* Read the Git mailing list, the maintainer regularly posts messages
> - entitled "What's cooking in git.git" giving
> - the status of various proposed changes.
>
> [[choose-starting-point]]
> === Choose a starting point.
> @@ -241,8 +264,9 @@ reasons:
> which case, they can explain why they extend your code to cover
> files, too).
>
> -The goal of your log message is to convey the _why_ behind your
> -change to help future developers.
> +The goal of your log message is to convey the _why_ behind your change
> +to help future developers. The reviewers will also make sure that
> +your proposed log message will serve this purpose well.
>
> The first line of the commit message should be a short description (50
> characters is the soft limit, see DISCUSSION in linkgit:git-commit[1]),
> --
> 2.45.0-119-g0f3415f1f8
Thanks, this is great improvement.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]
next prev parent reply other threads:[~2024-05-10 10:09 UTC|newest]
Thread overview: 44+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-04-15 23:20 [RFC PATCH] doc: describe the project's decision-making process Josh Steadmon
2024-04-16 0:24 ` Junio C Hamano
2024-04-22 21:10 ` Josh Steadmon
2024-04-22 21:30 ` Junio C Hamano
2024-04-23 22:41 ` Junio C Hamano
2024-04-17 16:32 ` Enrico Mrass
2024-04-17 16:58 ` Junio C Hamano
2024-05-03 14:45 ` Junio C Hamano
2024-05-03 15:48 ` Josh Steadmon
2024-05-03 18:08 ` Junio C Hamano
2024-05-03 19:29 ` Taylor Blau
2024-05-06 7:12 ` Patrick Steinhardt
2024-05-06 20:14 ` Taylor Blau
2024-05-06 19:36 ` Josh Steadmon
2024-05-06 20:17 ` Taylor Blau
2024-04-22 18:41 ` Emily Shaffer
2024-04-22 19:18 ` Junio C Hamano
2024-04-22 21:12 ` Emily Shaffer
2024-04-23 1:10 ` Junio C Hamano
2024-05-09 0:01 ` [PATCH v2] " Josh Steadmon
2024-05-09 18:10 ` Junio C Hamano
2024-05-09 19:20 ` Junio C Hamano
2024-05-09 21:13 ` [PATCH 0/2] Describe patch-flow better in SubmittingPatches Junio C Hamano
2024-05-09 21:13 ` [PATCH 1/2] SubmittingPatches: move the patch-flow section earlier Junio C Hamano
2024-05-09 21:13 ` [PATCH 2/2] SubmittingPatches: extend the "flow" section Junio C Hamano
2024-05-10 10:08 ` Karthik Nayak [this message]
2024-05-10 15:59 ` Junio C Hamano
2024-05-10 19:09 ` Karthik Nayak
2024-05-10 16:55 ` [PATCH v2 0/2] Describe life cycle of a patch series Junio C Hamano
2024-05-10 16:55 ` [PATCH v2 1/2] SubmittingPatches: move the patch-flow section earlier Junio C Hamano
2024-05-10 16:55 ` [PATCH v2 2/2] SubmittingPatches: extend the "flow" section Junio C Hamano
2024-05-10 16:56 ` [PATCH] decisions: focus on larger scale issues Junio C Hamano
2024-05-15 20:36 ` Josh Steadmon
2024-05-15 20:50 ` Junio C Hamano
2024-05-15 20:35 ` [PATCH v2 0/2] Describe life cycle of a patch series Josh Steadmon
2024-05-16 21:20 ` [PATCH v3] doc: describe the project's decision-making process Josh Steadmon
2024-05-16 22:01 ` Junio C Hamano
2024-05-17 20:18 ` Josh Steadmon
2024-05-17 6:29 ` Patrick Steinhardt
2024-05-17 16:40 ` Junio C Hamano
2024-05-21 5:56 ` Patrick Steinhardt
2024-05-17 20:35 ` [PATCH v4] " Josh Steadmon
2024-05-17 22:12 ` Junio C Hamano
2024-05-21 5:58 ` Patrick Steinhardt
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to='CAOLa=ZS_5+x7_xxppD8BE7RA0X+BFHPm=ffWg4JDgORqR5=sqQ@mail.gmail.com' \
--to=karthik.188@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).