[PATCH] Add pyramid style rule to CONTRIBUTING.md

[PATCH] Add pyramid style rule to CONTRIBUTING.md

[Yumei Huang]

Also fix the copyright line.

Suggested-by: Stefano Brivio <sbrivio@redhat.com>
Signed-off-by: Yumei Huang <yuhuang@redhat.com>
---
 CONTRIBUTING.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 75ad2a7..451cdd7 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,6 +1,6 @@
 <!---
 SPDX-License-Identifier: GPL-2.0-or-later
-Copyright (c) 2025 Red Hat
+Copyright Red Hat
 Author: Yumei Huang <yuhuang@redhat.com>
 -->
 
@@ -24,6 +24,8 @@ to prepare patches and participate in the email-based review process.
 
 * Edit the source code or documentation following the
   [Linux kernel coding style](https://www.kernel.org/doc/html/latest/process/coding-style.html).
+  When adding or editing lists of similar items, please format in the pyramid
+  style as described [here](https://hisham.hm/2018/06/16/when-listing-repeated-things-make-pyramids/).
 
 * Stage your changes:
 
-- 
2.47.0

Re: [PATCH] Add pyramid style rule to CONTRIBUTING.md

[David Gibson]

[-- Attachment #1: Type: text/plain, Size: 1437 bytes --]

On Wed, Oct 22, 2025 at 12:30:54PM +0800, Yumei Huang wrote:
> Also fix the copyright line.
> 
> Suggested-by: Stefano Brivio <sbrivio@redhat.com>
> Signed-off-by: Yumei Huang <yuhuang@redhat.com>

Stefano, do we actually encourage that style for any "list of similar
items"?  Or just for local variable declarations?

> ---
>  CONTRIBUTING.md | 4 +++-
>  1 file changed, 3 insertions(+), 1 deletion(-)
> 
> diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
> index 75ad2a7..451cdd7 100644
> --- a/CONTRIBUTING.md
> +++ b/CONTRIBUTING.md
> @@ -1,6 +1,6 @@
>  <!---
>  SPDX-License-Identifier: GPL-2.0-or-later
> -Copyright (c) 2025 Red Hat
> +Copyright Red Hat
>  Author: Yumei Huang <yuhuang@redhat.com>
>  -->
>  
> @@ -24,6 +24,8 @@ to prepare patches and participate in the email-based review process.
>  
>  * Edit the source code or documentation following the
>    [Linux kernel coding style](https://www.kernel.org/doc/html/latest/process/coding-style.html).
> +  When adding or editing lists of similar items, please format in the pyramid
> +  style as described [here](https://hisham.hm/2018/06/16/when-listing-repeated-things-make-pyramids/).
>  
>  * Stage your changes:
>  
> -- 
> 2.47.0
> 

-- 
David Gibson (he or they)	| I'll have my music baroque, and my code
david AT gibson.dropbear.id.au	| minimalist, thank you, not the other way
				| around.
http://www.ozlabs.org/~dgibson

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] Add pyramid style rule to CONTRIBUTING.md

[Stefano Brivio]

On Thu, 23 Oct 2025 11:40:10 +1100
David Gibson <david@gibson.dropbear.id.au> wrote:

> On Wed, Oct 22, 2025 at 12:30:54PM +0800, Yumei Huang wrote:
> > Also fix the copyright line.
> > 
> > Suggested-by: Stefano Brivio <sbrivio@redhat.com>
> > Signed-off-by: Yumei Huang <yuhuang@redhat.com>  
> 
> Stefano, do we actually encourage that style for any "list of similar
> items"?  Or just for local variable declarations?

Just for local variable declarations, thanks for noticing.

I was rather focusing on the fact (https://lwn.net/Articles/758552/)
that it's actually called "Reverse Christmas tree", not pyramid style.

I can't find a convenient reference right now, maybe it's hidden
somewhere in https://lore.kernel.org/netdev/?q=reverse+christmas+tree,
...or maybe it's actually "documented" in checkpatch.pl?

Or prehaps just trust us/me on that, sorry, I know it's not ideal :(
...but I can absolutely guarantee it's called Reverse Christmas tree.

-- 
Stefano

Re: [PATCH] Add pyramid style rule to CONTRIBUTING.md

[Yumei Huang]

On Thu, Oct 23, 2025 at 10:28 AM Stefano Brivio <sbrivio@redhat.com> wrote:
>
> On Thu, 23 Oct 2025 11:40:10 +1100
> David Gibson <david@gibson.dropbear.id.au> wrote:
>
> > On Wed, Oct 22, 2025 at 12:30:54PM +0800, Yumei Huang wrote:
> > > Also fix the copyright line.
> > >
> > > Suggested-by: Stefano Brivio <sbrivio@redhat.com>
> > > Signed-off-by: Yumei Huang <yuhuang@redhat.com>
> >
> > Stefano, do we actually encourage that style for any "list of similar
> > items"?  Or just for local variable declarations?
>
> Just for local variable declarations, thanks for noticing.
>
> I was rather focusing on the fact (https://lwn.net/Articles/758552/)
> that it's actually called "Reverse Christmas tree", not pyramid style.
>
> I can't find a convenient reference right now, maybe it's hidden
> somewhere in https://lore.kernel.org/netdev/?q=reverse+christmas+tree,
> ...or maybe it's actually "documented" in checkpatch.pl?

I found it in Documentation/process/maintainer-kvm-x86.rst as below:

"
Using reverse fir tree, a.k.a. reverse Christmas tree or reverse XMAS tree, for
variable declarations isn't strictly required, though it is still preferred.
"

I will update the name and make it only for local variable declarations.

Do I need to update the reference link as well? The name would be
different from the current pyramids link
(https://hisham.hm/2018/06/16/when-listing-repeated-things-make-pyramids/).
Not sure if it would be a little bit confusing if not.

>
> Or prehaps just trust us/me on that, sorry, I know it's not ideal :(
> ...but I can absolutely guarantee it's called Reverse Christmas tree.
>
> --
> Stefano
>


-- 
Thanks,

Yumei Huang

Re: [PATCH] Add pyramid style rule to CONTRIBUTING.md

[Stefano Brivio]

On Mon, 27 Oct 2025 11:05:09 +0800
Yumei Huang <yuhuang@redhat.com> wrote:

> On Thu, Oct 23, 2025 at 10:28 AM Stefano Brivio <sbrivio@redhat.com> wrote:
> >
> > On Thu, 23 Oct 2025 11:40:10 +1100
> > David Gibson <david@gibson.dropbear.id.au> wrote:
> >  
> > > On Wed, Oct 22, 2025 at 12:30:54PM +0800, Yumei Huang wrote:  
> > > > Also fix the copyright line.
> > > >
> > > > Suggested-by: Stefano Brivio <sbrivio@redhat.com>
> > > > Signed-off-by: Yumei Huang <yuhuang@redhat.com>  
> > >
> > > Stefano, do we actually encourage that style for any "list of similar
> > > items"?  Or just for local variable declarations?  
> >
> > Just for local variable declarations, thanks for noticing.
> >
> > I was rather focusing on the fact (https://lwn.net/Articles/758552/)
> > that it's actually called "Reverse Christmas tree", not pyramid style.
> >
> > I can't find a convenient reference right now, maybe it's hidden
> > somewhere in https://lore.kernel.org/netdev/?q=reverse+christmas+tree,
> > ...or maybe it's actually "documented" in checkpatch.pl?  
> 
> I found it in Documentation/process/maintainer-kvm-x86.rst as below:
> 
> "
> Using reverse fir tree, a.k.a. reverse Christmas tree or reverse XMAS tree, for
> variable declarations isn't strictly required, though it is still preferred.
> "
> 
> I will update the name and make it only for local variable declarations.

Ah, thanks.

> Do I need to update the reference link as well? The name would be
> different from the current pyramids link
> (https://hisham.hm/2018/06/16/when-listing-repeated-things-make-pyramids/).
> Not sure if it would be a little bit confusing if not.

The "pyramid" link explains the reason why, it just uses a different
name.

Maybe we should mention both: the kernel link calls it that way, and the
pyramid link explains the rationale why it's used / preferred.

-- 
Stefano