| Message ID | 20250303220029.10716-1-lucasseikioshiro@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | Add --subject-extra-prefix flag to format-patch | expand |
Lucas Seiki Oshiro <lucasseikioshiro@gmail.com> writes:
> Subject: Re: [GSoC][RFC PATCH 0/6] Add --subject-extra-prefix flag to format-patch
Hmph, instead use "--rfc=GSoC" to do [GSoC PATCH n/m] and please do
not pile more "extra" on top?
On Mon, Mar 03, 2025 at 03:08:43PM -0800, Junio C Hamano wrote: > Lucas Seiki Oshiro <lucasseikioshiro@gmail.com> writes: > > > Subject: Re: [GSoC][RFC PATCH 0/6] Add --subject-extra-prefix flag to format-patch > > Hmph, instead use "--rfc=GSoC" to do [GSoC PATCH n/m] and please do > not pile more "extra" on top? I do understand though that `--rfc=GSoC` is not exactly discoverable for a newcomer. Maybe a simpler fix would be to introduce an alias for that option that is more discoverable? I don't have a great idea for how to name it -- the best that comes to mind is `--patch-prefix`, which mirrors `--subject-prefix`. --patch-prefix=<prefix> --rfc Prepends the string `<prefix>` to the subject prefix. As the subject prefix defaults to "PATCH", you’ll get "<prefix> PATCH" by default. When `--rfc` is given, the prefix will be set to "RFC" . RFC means "Request For Comments"; use this when sending an experimental patch for discussion rather than application. "--rfc=WIP" may also be a useful way to indicate that a patch is not complete yet ("WIP" stands for "Work In Progress"). If the convention of the receiving community for a particular extra string is to have it after the subject prefix, the string <prefix> can be prefixed with a dash ("-") to signal that the rest of the <prefix> string should be appended to the subject prefix instead, e.g., --patch-prefix='-(WIP)' results in "PATCH (WIP)". We would hide away the optional value `[=<rfc>]` of the `--rfc` option and instead advertise `--patch-prefix=<prefix>`. This would of course only be a cosmetic change, we'd still accept the optional argument so that we don't break backwards compatibility. Patrick
Junio C Hamano <gitster@pobox.com> writes: > Lucas Seiki Oshiro <lucasseikioshiro@gmail.com> writes: > >> Subject: Re: [GSoC][RFC PATCH 0/6] Add --subject-extra-prefix flag to format-patch > > Hmph, instead use "--rfc=GSoC" to do [GSoC PATCH n/m] and please do > not pile more "extra" on top? Or even --subject-prefix="GSoC PATCH". Once you stop treating [GSoC] as if it is an independent prefix, everything will fall into place naturally without adding anything extra. To put it differently, which one wastes more precious horizontal screen estate on the Subject line, where practically only 50 or so columns are usable? Subject: [A][B][C][D][PATCH 0/6] This is my first contribution Subject: [A B C D PATCH 0/6] This is my first contribution
Patrick Steinhardt <ps@pks.im> writes: > I do understand though that `--rfc=GSoC` is not exactly discoverable for > a newcomer. Maybe a simpler fix would be to introduce an alias for that > option that is more discoverable? I don't have a great idea for how to > name it -- the best that comes to mind is `--patch-prefix`, which > mirrors `--subject-prefix`. The problem with it is that having "patch" vs "subject" prefix will make it confusing which one is which. Let's step back and examine what we already have. * The "--subject-prefix" is configurable and format.subjectPrefix is meant to go to .git/config for repositories that work with projects with special needs (they tell you to use not [PATCH] but subproject specific moniker like [PATCH rcu] instead). * The "--rfc[=<word>]" has no configuration and it is deliberately so, as it is meant to be used as needed, on occasions that call for it, pretty much decided per invocation. Are these two points above not clear in our documentation? If so, we should fix it, but I do not think giving a synonym to --rfc is a good way to clarify it. If it is a GSoC topic sent to this list, it _will_ be GSoC topic for the entire iterations of the same topic. So it would be good to use --subject-prefix="GSoC PATCH" (or configure format.subjectPrefix in the repository to use that, if a student works with us only on GSoC topics during the Summer-of-Code program duration), and on occasion, when students are not so sure about their patches (yet), use of --rfc would be a good way, which would give us "[RFC GSoC PATCH 0/6]", to mark the patches as such. Another problem with --patch-prefix synonym is that --rfc is not necessarily a prefix. With git format-patch --rfc='-WIP' --subject-prefix='GSoC PATCH' you would get "[GSoC PATCH WIP 0/6]" instead. In any case, I think it is the root cause of this disease to treat GSoC mark as something extra that requires a new marker that is separate from the usual PATCH marker. Using whatever mechanism you would use your string in place for the standard PATCH mark to make it say "GSoC PATCH" would be the most appropriate, without mucking with an extra option, be it '--rfc' or '--subject-extra-prefix', I would say. Thanks.
> Once you stop treating [GSoC] as if it is an independent prefix, > everything will fall into place naturally without adding anything > extra. So, instead of changing the behavior of format-patch, would it be better if we changed the documentation to ask these patches to be sent with `[GSoC PATCH]` or similar instead of `[GSoC][PATCH]`? I mean, in https://git.github.io/General-Microproject-Information/ : """ When you submit your patch, please mention that you plan to apply for the GSoC or Outreachy. You can use "[GSoC][PATCH ...]" or "[Outreachy][PATCH ...]" in the subject of the emails you send for that purpose. """
Lucas Seiki Oshiro <lucasseikioshiro@gmail.com> writes: >> Once you stop treating [GSoC] as if it is an independent prefix, >> everything will fall into place naturally without adding anything >> extra. > > So, instead of changing the behavior of format-patch, would it be > better if we changed the documentation to ask these patches to be > sent with `[GSoC PATCH]` or similar instead of `[GSoC][PATCH]`? Yup, I do not know offhand who are managing these descriptions, but having extra moniker in the same [square bracket] as PATCH is a more common practice, and we should follow suit. Thanks.
> Yup, I do not know offhand who are managing these descriptions, but > having extra moniker in the same [square bracket] as PATCH is a more > common practice, and we should follow suit. Ok, thanks! I just created a PR in git.github.io <http://git.github.io/> replacing the mentions of `[GSoC][PATCH]` by `[GSoC PATCH]`: https://github.com/git/git.github.io/pull/756