The recommendation is based on the following rationale:
- it makes the commit messages much cleaner and easy to read, especially
on the screens of the mobile devices;
- it reduces resources (memory, time, energy) to retrieve all these
headers, which are barely needed by a mere user, as for automation
they will be still available via mail archives, such as
https://lore.kernel.org, assuming the Link: or Message-ID tag is
provided.
Let's be environment friendly and save the planet!
Signed-off-by: Andy Shevchenko <[email protected]>
---
Documentation/process/5.Posting.rst | 4 ++++
Documentation/process/submitting-patches.rst | 5 +++++
2 files changed, 9 insertions(+)
diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
index 90a7fe2a85f2..157b3fc0087a 100644
--- a/Documentation/process/5.Posting.rst
+++ b/Documentation/process/5.Posting.rst
@@ -276,6 +276,10 @@ for addition without the explicit permission of the person named; using
Reported-by: is fine most of the time as well, but ask for permission if
the bug was reported in private.
+It's recommended to locate the additional Cc: tags after the cutter '---' line
+in the patches as it makes sure the commit message won't be polluted with them.
+At the same time they will be available via email headers on the mail archives,
+such as https://lore.kernel.org.
Sending the patch
-----------------
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 6775f0698136..0c898d9e00f5 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -491,6 +491,11 @@ automatically converted to the Cc: email header and you do not need to
have an explicit ``Cc:`` tag, if the person is already mentioned by another
tag.
+It's recommended to locate the additional ``Cc:`` tags after the cutter '---' line
+in the patches as it makes sure the commit message won't be polluted with them.
+At the same time they will be available via email headers on the mail archives,
+such as https://lore.kernel.org.
+
Co-developed-by: states that the patch was co-created by multiple developers;
it is used to give attribution to co-authors (in addition to the author
attributed by the From: tag) when several people work on a single patch. Since
--
2.43.0.rc1.1336.g36b5255a03ac
On Tue, 23 Apr 2024, Andy Shevchenko <[email protected]> wrote:
> The recommendation is based on the following rationale:
>
> - it makes the commit messages much cleaner and easy to read, especially
> on the screens of the mobile devices;
>
> - it reduces resources (memory, time, energy) to retrieve all these
> headers, which are barely needed by a mere user, as for automation
> they will be still available via mail archives, such as
> https://lore.kernel.org, assuming the Link: or Message-ID tag is
> provided.
I find the information in the commit message useful, and it tells me who
were explicitly included in the discussion.
For example when fixing a regression I'd like to Cc everyone who was
Cc'd in the regressing commit. The drm subsystem maintainer tool
actually has a helper for doing just that. 'dim fixes <sha1>' digs up
all the relevant info.
The Cc's on the mailing list archive are harder to dig up, and do not
accurately reflect the same information. A lot of patches get sent with
more Cc's in the mail message than in the commit message.
BR,
Jani.
> Let's be environment friendly and save the planet!
>
> Signed-off-by: Andy Shevchenko <[email protected]>
> ---
> Documentation/process/5.Posting.rst | 4 ++++
> Documentation/process/submitting-patches.rst | 5 +++++
> 2 files changed, 9 insertions(+)
>
> diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
> index 90a7fe2a85f2..157b3fc0087a 100644
> --- a/Documentation/process/5.Posting.rst
> +++ b/Documentation/process/5.Posting.rst
> @@ -276,6 +276,10 @@ for addition without the explicit permission of the person named; using
> Reported-by: is fine most of the time as well, but ask for permission if
> the bug was reported in private.
>
> +It's recommended to locate the additional Cc: tags after the cutter '---' line
> +in the patches as it makes sure the commit message won't be polluted with them.
> +At the same time they will be available via email headers on the mail archives,
> +such as https://lore.kernel.org.
>
> Sending the patch
> -----------------
> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> index 6775f0698136..0c898d9e00f5 100644
> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -491,6 +491,11 @@ automatically converted to the Cc: email header and you do not need to
> have an explicit ``Cc:`` tag, if the person is already mentioned by another
> tag.
>
> +It's recommended to locate the additional ``Cc:`` tags after the cutter '---' line
> +in the patches as it makes sure the commit message won't be polluted with them.
> +At the same time they will be available via email headers on the mail archives,
> +such as https://lore.kernel.org.
> +
> Co-developed-by: states that the patch was co-created by multiple developers;
> it is used to give attribution to co-authors (in addition to the author
> attributed by the From: tag) when several people work on a single patch. Since
--
Jani Nikula, Intel
Andy Shevchenko <[email protected]> writes:
>> A lot of patches get sent with
>> more Cc's in the mail message than in the commit message.
>
> Note, this is the recommendation as it's stated. You can continue polluting
> the environment on your wish.
The environmental case here is ... not strong.
I, too, have my doubts about this recommendation; responding this way is
not going to change a lot of minds, IMO.
Thanks,
jon
On Tue, Apr 23, 2024 at 04:19:38PM +0300, Andy Shevchenko wrote:
> The recommendation is based on the following rationale:
>
> - it makes the commit messages much cleaner and easy to read, especially
> on the screens of the mobile devices;
Reading commits on a mobile device is not what kernel development is
optimized for, sorry.
> - it reduces resources (memory, time, energy) to retrieve all these
> headers, which are barely needed by a mere user, as for automation
> they will be still available via mail archives, such as
> https://lore.kernel.org, assuming the Link: or Message-ID tag is
> provided.
>
> Let's be environment friendly and save the planet!
>
> Signed-off-by: Andy Shevchenko <[email protected]>
> ---
> Documentation/process/5.Posting.rst | 4 ++++
> Documentation/process/submitting-patches.rst | 5 +++++
> 2 files changed, 9 insertions(+)
This breaks my existing workflow, sorry. I can't track cc: below the
--- line because obviously, git cuts that off. So I put them above
where git send-email can see them, AND where git can handle them when I
rebase/revise/etc.
Also, as Jon points out, the "environmental" argument seems very odd,
it's not like bits cost more to send around (they keep getting cheaper
in power and money), and processing power is pretty constant for servers
handling email, so I don't understand the power consumption argument.
Without some sort of data to back that up, I'd be loath to repeat it.
thanks,
greg k-h
Hi Jani,
On Tue, Apr 23, 2024 at 4:31 PM Jani Nikula <[email protected]> wrote:
> On Tue, 23 Apr 2024, Andy Shevchenko <[email protected]> wrote:
> > The recommendation is based on the following rationale:
> >
> > - it makes the commit messages much cleaner and easy to read, especially
> > on the screens of the mobile devices;
> >
> > - it reduces resources (memory, time, energy) to retrieve all these
> > headers, which are barely needed by a mere user, as for automation
> > they will be still available via mail archives, such as
> > https://lore.kernel.org, assuming the Link: or Message-ID tag is
> > provided.
>
> I find the information in the commit message useful, and it tells me who
> were explicitly included in the discussion.
Contrary to popular belief, it does not tell you who was explicitly
included in the discussion. Git history has lots of commits that
state I was CCed on a patch, while I had no active participation in
the discussion, or even any interest in the patch in the first place
(scripts/get_mainter.pl considered harmful).
Gr{oetje,eeting}s,
Geert
--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68korg
In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
On Tue, Apr 23, 2024 at 08:13:37AM -0700, Greg KH wrote:
> On Tue, Apr 23, 2024 at 04:19:38PM +0300, Andy Shevchenko wrote:
> > The recommendation is based on the following rationale:
> >
> > - it makes the commit messages much cleaner and easy to read, especially
> > on the screens of the mobile devices;
>
> Reading commits on a mobile device is not what kernel development is
> optimized for, sorry.
The commit messages not always for the kernel development, some people may read
them in order to understand code better or many other reasons. I.o.w. it's not
the point.
> > - it reduces resources (memory, time, energy) to retrieve all these
> > headers, which are barely needed by a mere user, as for automation
> > they will be still available via mail archives, such as
> > https://lore.kernel.org, assuming the Link: or Message-ID tag is
> > provided.
> >
> > Let's be environment friendly and save the planet!
> >
> > Signed-off-by: Andy Shevchenko <[email protected]>
> > ---
> > Documentation/process/5.Posting.rst | 4 ++++
> > Documentation/process/submitting-patches.rst | 5 +++++
> > 2 files changed, 9 insertions(+)
>
> This breaks my existing workflow, sorry. I can't track cc: below the
> --- line because obviously, git cuts that off. So I put them above
> where git send-email can see them,
git send-email _sees_ them very well there.
> AND where git can handle them when I
> rebase/revise/etc.
> Also, as Jon points out, the "environmental" argument seems very odd,
> it's not like bits cost more to send around (they keep getting cheaper
> in power and money), and processing power is pretty constant for servers
> handling email, so I don't understand the power consumption argument.
> Without some sort of data to back that up, I'd be loath to repeat it.
--
With Best Regards,
Andy Shevchenko
On Tue, Apr 23, 2024 at 06:28:44PM +0300, Andy Shevchenko wrote:
> On Tue, Apr 23, 2024 at 08:13:37AM -0700, Greg KH wrote:
> > On Tue, Apr 23, 2024 at 04:19:38PM +0300, Andy Shevchenko wrote:
> > > The recommendation is based on the following rationale:
> > >
> > > - it makes the commit messages much cleaner and easy to read, especially
> > > on the screens of the mobile devices;
> >
> > Reading commits on a mobile device is not what kernel development is
> > optimized for, sorry.
>
> The commit messages not always for the kernel development, some people may read
> them in order to understand code better or many other reasons. I.o.w. it's not
> the point.
>
> > > - it reduces resources (memory, time, energy) to retrieve all these
> > > headers, which are barely needed by a mere user, as for automation
> > > they will be still available via mail archives, such as
> > > https://lore.kernel.org, assuming the Link: or Message-ID tag is
> > > provided.
> > >
> > > Let's be environment friendly and save the planet!
> > >
> > > Signed-off-by: Andy Shevchenko <[email protected]>
> > > ---
> > > Documentation/process/5.Posting.rst | 4 ++++
> > > Documentation/process/submitting-patches.rst | 5 +++++
> > > 2 files changed, 9 insertions(+)
> >
> > This breaks my existing workflow, sorry. I can't track cc: below the
> > --- line because obviously, git cuts that off. So I put them above
> > where git send-email can see them,
>
> git send-email _sees_ them very well there.
Sorry, yes, but git itself can't track them in the commit when I
rebase/squash/redo/etc. That's the point I was trying to make before my
coffee kicked in...
thanks,
greg k-h
On Tue, Apr 23, 2024 at 09:07:09AM -0700, Greg KH wrote:
> On Tue, Apr 23, 2024 at 06:28:44PM +0300, Andy Shevchenko wrote:
> > On Tue, Apr 23, 2024 at 08:13:37AM -0700, Greg KH wrote:
> > > On Tue, Apr 23, 2024 at 04:19:38PM +0300, Andy Shevchenko wrote:
> > > > The recommendation is based on the following rationale:
> > > >
> > > > - it makes the commit messages much cleaner and easy to read, especially
> > > > on the screens of the mobile devices;
> > >
> > > Reading commits on a mobile device is not what kernel development is
> > > optimized for, sorry.
> >
> > The commit messages not always for the kernel development, some people may read
> > them in order to understand code better or many other reasons. I.o.w. it's not
> > the point.
> >
> > > > - it reduces resources (memory, time, energy) to retrieve all these
> > > > headers, which are barely needed by a mere user, as for automation
> > > > they will be still available via mail archives, such as
> > > > https://lore.kernel.org, assuming the Link: or Message-ID tag is
> > > > provided.
> > > >
> > > > Let's be environment friendly and save the planet!
> > > >
> > > > Signed-off-by: Andy Shevchenko <[email protected]>
> > > > ---
> > > > Documentation/process/5.Posting.rst | 4 ++++
> > > > Documentation/process/submitting-patches.rst | 5 +++++
> > > > 2 files changed, 9 insertions(+)
> > >
> > > This breaks my existing workflow, sorry. I can't track cc: below the
> > > --- line because obviously, git cuts that off. So I put them above
> > > where git send-email can see them,
> >
> > git send-email _sees_ them very well there.
>
> Sorry, yes, but git itself can't track them in the commit when I
> rebase/squash/redo/etc. That's the point I was trying to make before my
> coffee kicked in...
It can in your _local_ repo if you have it as
Signed-off-by:
---
Cc:
Cc:
in the commit message. It won't go to the final commit message if you sending
it out and apply via `git am`, or reapply with the latter locally instead of
cherry-picking.
--
With Best Regards,
Andy Shevchenko
On Tue, 23 Apr 2024, Andy Shevchenko <[email protected]> wrote:
> On Tue, Apr 23, 2024 at 05:30:49PM +0300, Jani Nikula wrote:
>> The Cc's on the mailing list archive are harder to dig up, and do not
>> accurately reflect the same information.
>
> How comes? These Cc: are 1:1 mapped to the Cc: email headers.
Patch Cc's get mapped to email Cc's depending on personal git sendemail
configuration.
People can add more Cc's in the emails when sending.
Mailing list Cc's actually present in the archives depend on mailing
list manager configuration, and, in some cases, even the personal list
preferences of individual subscribers.
BR,
Jani.
--
Jani Nikula, Intel
On Tue, Apr 23, 2024 at 07:37:34PM +0300, Jani Nikula wrote:
> On Tue, 23 Apr 2024, Andy Shevchenko <[email protected]> wrote:
> > On Tue, Apr 23, 2024 at 05:30:49PM +0300, Jani Nikula wrote:
> >> The Cc's on the mailing list archive are harder to dig up, and do not
> >> accurately reflect the same information.
> >
> > How comes? These Cc: are 1:1 mapped to the Cc: email headers.
>
> Patch Cc's get mapped to email Cc's depending on personal git sendemail
> configuration.
>
> People can add more Cc's in the emails when sending.
So, which exactly a proof why email headers are better for that, as they
reflect _reality_.
> Mailing list Cc's actually present in the archives depend on mailing
> list manager configuration, and, in some cases, even the personal list
> preferences of individual subscribers.
--
With Best Regards,
Andy Shevchenko
On Tue, Apr 23, 2024 at 08:44:24AM -0600, Jonathan Corbet wrote:
> Andy Shevchenko <[email protected]> writes:
>
> >> A lot of patches get sent with
> >> more Cc's in the mail message than in the commit message.
> >
> > Note, this is the recommendation as it's stated. You can continue polluting
> > the environment on your wish.
>
> The environmental case here is ... not strong.
>
> I, too, have my doubts about this recommendation; responding this way is
> not going to change a lot of minds, IMO.
Let's see how discussion will go.
Nevertheless, there seem no objections against the first patch in the series.
Can it be applied?
--
With Best Regards,
Andy Shevchenko
On Tue, Apr 23, 2024 at 08:00:16PM +0300, Jani Nikula wrote:
> Imagine the commit message Cc was named "Attn:" and handled
> appropriately. That probably reflects a lot of commit message Cc
> usage.
This is especially the case for get_maintainer.pl purposes. Adding a Cc:
in a commit message means that this person will be included on patches
referencing this commit (e.g. via Fixes:).
-K
On Tue, 23 Apr 2024, Andy Shevchenko <[email protected]> wrote:
> On Tue, Apr 23, 2024 at 07:37:34PM +0300, Jani Nikula wrote:
>> On Tue, 23 Apr 2024, Andy Shevchenko <[email protected]> wrote:
>> > On Tue, Apr 23, 2024 at 05:30:49PM +0300, Jani Nikula wrote:
>> >> The Cc's on the mailing list archive are harder to dig up, and do not
>> >> accurately reflect the same information.
>> >
>> > How comes? These Cc: are 1:1 mapped to the Cc: email headers.
>>
>> Patch Cc's get mapped to email Cc's depending on personal git sendemail
>> configuration.
>>
>> People can add more Cc's in the emails when sending.
>
> So, which exactly a proof why email headers are better for that, as they
> reflect _reality_.
No, I think the point is, commit message Cc != email message Cc, they
just have the same name.
Similar to, say, Reviewed-by, a commit message Cc may turn into an email
message Cc. But you can't make assumptions about it one way or the
other.
Imagine the commit message Cc was named "Attn:" and handled
appropriately. That probably reflects a lot of commit message Cc usage.
BR,
Jani.
>
>> Mailing list Cc's actually present in the archives depend on mailing
>> list manager configuration, and, in some cases, even the personal list
>> preferences of individual subscribers.
--
Jani Nikula, Intel
On Tue, Apr 23, 2024 at 05:30:49PM +0300, Jani Nikula wrote:
> On Tue, 23 Apr 2024, Andy Shevchenko <[email protected]> wrote:
> > The recommendation is based on the following rationale:
> >
> > - it makes the commit messages much cleaner and easy to read, especially
> > on the screens of the mobile devices;
> >
> > - it reduces resources (memory, time, energy) to retrieve all these
> > headers, which are barely needed by a mere user, as for automation
> > they will be still available via mail archives, such as
> > https://lore.kernel.org, assuming the Link: or Message-ID tag is
> > provided.
>
> I find the information in the commit message useful, and it tells me who
> were explicitly included in the discussion.
>
> For example when fixing a regression I'd like to Cc everyone who was
> Cc'd in the regressing commit. The drm subsystem maintainer tool
> actually has a helper for doing just that. 'dim fixes <sha1>' digs up
> all the relevant info.
> The Cc's on the mailing list archive are harder to dig up, and do not
> accurately reflect the same information.
How comes? These Cc: are 1:1 mapped to the Cc: email headers.
> A lot of patches get sent with
> more Cc's in the mail message than in the commit message.
Note, this is the recommendation as it's stated. You can continue polluting
the environment on your wish.
> > Let's be environment friendly and save the planet!
--
With Best Regards,
Andy Shevchenko
On Tue, Apr 23, 2024 at 05:30:49PM +0300, Jani Nikula wrote:
> The Cc's on the mailing list archive are harder to dig up, and do not
> accurately reflect the same information. A lot of patches get sent with
> more Cc's in the mail message than in the commit message.
These days with b4 and lore it's pretty straightforward, especially with
subsystems that include a message ID based link to the discussion when
applying the patch - you can just grab the original discussion with a b4
mbox command.
On 23/04/2024 15:19, Andy Shevchenko wrote:
> The recommendation is based on the following rationale:
>
> - it makes the commit messages much cleaner and easy to read, especially
> on the screens of the mobile devices;
>
> - it reduces resources (memory, time, energy) to retrieve all these
> headers, which are barely needed by a mere user, as for automation
> they will be still available via mail archives, such as
> https://lore.kernel.org, assuming the Link: or Message-ID tag is
> provided.
>
> Let's be environment friendly and save the planet!
>
> Signed-off-by: Andy Shevchenko <[email protected]>
> ---
> Documentation/process/5.Posting.rst | 4 ++++
> Documentation/process/submitting-patches.rst | 5 +++++
> 2 files changed, 9 insertions(+)
>
> diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
> index 90a7fe2a85f2..157b3fc0087a 100644
> --- a/Documentation/process/5.Posting.rst
> +++ b/Documentation/process/5.Posting.rst
> @@ -276,6 +276,10 @@ for addition without the explicit permission of the person named; using
> Reported-by: is fine most of the time as well, but ask for permission if
> the bug was reported in private.
>
> +It's recommended to locate the additional Cc: tags after the cutter '---' line
> +in the patches as it makes sure the commit message won't be polluted with them.
> +At the same time they will be available via email headers on the mail archives,
> +such as https://lore.kernel.org.
Manually added useful Cc-tags should be kept in commit msg, because it
annotates who could be interested in the patch.
The problem is that people put output of get_maintainers.pl as Cc to the
commit list. This is 100% redundant because it can be recreated any
given time with 100% accuracy (for given kernel tree). Therefore I would
propose to rephrase it to something:
====
It is recommended to not add autogenerated scripts/get_maintainer.pl
CC-entries into the commit msg, but keep them under cutter '---'. There
is no single need to store automated output of get_maintainers.pl in the
git log. It can be easily re-created at any given time, thus its
presence in the git history is redundant and obfuscates the log.
====
Best regards,
Krzysztof
On Mon, Apr 29, 2024 at 09:35:18AM +0200, Krzysztof Kozlowski wrote:
> On 23/04/2024 15:19, Andy Shevchenko wrote:
> > The recommendation is based on the following rationale:
> >
> > - it makes the commit messages much cleaner and easy to read, especially
> > on the screens of the mobile devices;
> >
> > - it reduces resources (memory, time, energy) to retrieve all these
> > headers, which are barely needed by a mere user, as for automation
> > they will be still available via mail archives, such as
> > https://lore.kernel.org, assuming the Link: or Message-ID tag is
> > provided.
> >
> > Let's be environment friendly and save the planet!
..
> > +It's recommended to locate the additional Cc: tags after the cutter '---' line
> > +in the patches as it makes sure the commit message won't be polluted with them.
> > +At the same time they will be available via email headers on the mail archives,
> > +such as https://lore.kernel.org.
>
> Manually added useful Cc-tags should be kept in commit msg, because it
> annotates who could be interested in the patch.
>
> The problem is that people put output of get_maintainers.pl as Cc to the
> commit list. This is 100% redundant because it can be recreated any
> given time with 100% accuracy (for given kernel tree). Therefore I would
> propose to rephrase it to something:
>
> ====
> It is recommended to not add autogenerated scripts/get_maintainer.pl
> CC-entries into the commit msg, but keep them under cutter '---'. There
> is no single need to store automated output of get_maintainers.pl in the
> git log. It can be easily re-created at any given time, thus its
> presence in the git history is redundant and obfuscates the log.
Right, but still even for non-automated output it might (may) be redundant,
however I can go for this compromise as most of the Cc indeed duplicate
the output of get_maintainer.pl.
--
With Best Regards,
Andy Shevchenko