Hi Maxim,
Maxim Cournoyer <maxim.courno...@gmail.com> writes:
> Hi Hilton,
>
> Hilton Chain <hako@ultrarare.space> writes:
>
> [...]
>
>> But according to GNU Coding Standards, the following might be used instead:
>>
>> --8<---------------cut here---------------start------------->8---
>> * gnu/packages/package-management.scm (guix) <#:phases> [(target-riscv64?)]:
>> Use
>> correct Guile version for tests.
>> --8<---------------cut here---------------end--------------->8---
>>
>> convention:
>> - * changed file
>> - () changed function or variable
>> - [] conditional change
>> - <> indicating the part changed
>
> Indeed. That's something I had noticed when I first read carefully the
> GNU ChangeLog style examples a long item ago. The parts we used
> differently are often:
>
> []: More often than not used to denote object fields instead of
> conditionals, e.g. [inputs]: Add x.
>
> <>: It's gotten used more, but initially {} was used in place of it. I
> still sometimes prefer {}, simply because Emacs allows me to
> auto-complete inside curly braces and not inside <> (I'm sure that's
> configurable though; it must be treating { as a word boundary and not <
> or something).
If we ask new contributors to learn from the commit history, they are likely to
find the inconsistency and feel confused. It would be better to have a style in
the contribution documentation, the following for example:
--8<---------------cut here---------------start------------->8---
scope: [changed module, procedure, variable etc. :] summary
optional overview
* file (variable) [changed part] {changed part, when [] is not sufficient}:
change.
metadata (Fixes: , Reviewed-by: etc.)
--8<---------------cut here---------------end--------------->8---
With short explanations and link to the coding standards for how to express
changes.
>> [] is added after <> because the condition happens within that part.
>>
>> Should this documented convention be followed instead, or we documenting the
>> one
>> currently used?
>
> I'm not sure. The GNU ChangeLog itself is not too formally defined; it
> seems the important part is matching it in spirit, not exact form.
