| Message ID | d50c0f22c41ec36b574e1ff67e68485d9a6f2a84.1710258538.git.dsimic@manjaro.org (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | Improve the documentation and test coverage for whitespace and comments | expand |
Dragan Simic <dsimic@manjaro.org> writes: > Reformat a few lines a bit, to utilize the available horizontal space better. > There are no changes to the actual contents of the documentation. I was a bit surprised to see such a "preliminary clean-up" step to come before the main change, not after, but separating this from the change to the next paragraph, which is the main change in this series, is nevertheless a very good idea. > > Signed-off-by: Dragan Simic <dsimic@manjaro.org> > --- > Documentation/config.txt | 10 +++++----- > 1 file changed, 5 insertions(+), 5 deletions(-) > > diff --git a/Documentation/config.txt b/Documentation/config.txt > index 4480bb44203b..2fc4a52d8d76 100644 > --- a/Documentation/config.txt > +++ b/Documentation/config.txt > @@ -58,11 +58,11 @@ compared case sensitively. These subsection names follow the same > restrictions as section names. > > All the other lines (and the remainder of the line after the section > -header) are recognized as setting variables, in the form > -'name = value' (or just 'name', which is a short-hand to say that > -the variable is the boolean "true"). > -The variable names are case-insensitive, allow only alphanumeric characters > -and `-`, and must start with an alphabetic character. > +header) are recognized as setting variables, in the form 'name = value' > +(or just 'name', which is a short-hand to say that the variable is the > +boolean "true"). The variable names are case-insensitive, allow only > +alphanumeric characters and `-`, and must start with an alphabetic > +character. > > A line that defines a value can be continued to the next line by > ending it with a `\`; the backslash and the end-of-line are stripped.
On 2024-03-14 02:58, Junio C Hamano wrote: > Dragan Simic <dsimic@manjaro.org> writes: > >> Reformat a few lines a bit, to utilize the available horizontal space >> better. >> There are no changes to the actual contents of the documentation. > > I was a bit surprised to see such a "preliminary clean-up" step to > come before the main change, not after, but separating this from the > change to the next paragraph, which is the main change in this series, > is nevertheless a very good idea. The reason why this patch went as the second in the series was simply because it's a somewhat unrelated cleanup that performs no actual changes to the contents of the documentation. Thus, the first patch in the series brings the changes, the second patch stays in the same domain but only as a cleanup, and the third patch moves to another domain. I find it quite logical.
Dragan Simic <dsimic@manjaro.org> writes: >> I was a bit surprised to see such a "preliminary clean-up" step to >> come before the main change, not after, but separating this from the >> change to the next paragraph, which is the main change in this series, >> is nevertheless a very good idea. > > The reason why this patch went as the second in the series was simply > because it's a somewhat unrelated cleanup that performs no actual > changes > to the contents of the documentation. It would have been understandable if it were left at the end, as "after the dust settles". It would made even more sense if it were at the front, "before doing anything else, let's clean up the mess--we do not intend to change the behaviour with this change at all". Having it in the middle was what made me surprised. Generally, the order of preference is to do "preliminary clean-up" first, followed by the real change. That way, trivial clean-up that is designed not to change any behaviour can go ahead and merged down even before the real change solidifies. Unrelated changes has no place in a series with a real purpose. Unless the series is about "assorted clean-ups that are not related with each other", that is. Thanks.
On 2024-03-14 17:22, Junio C Hamano wrote: > Dragan Simic <dsimic@manjaro.org> writes: > >>> I was a bit surprised to see such a "preliminary clean-up" step to >>> come before the main change, not after, but separating this from the >>> change to the next paragraph, which is the main change in this >>> series, >>> is nevertheless a very good idea. >> >> The reason why this patch went as the second in the series was simply >> because it's a somewhat unrelated cleanup that performs no actual >> changes >> to the contents of the documentation. > > It would have been understandable if it were left at the end, as > "after the dust settles". It would made even more sense if it were > at the front, "before doing anything else, let's clean up the > mess--we do not intend to change the behaviour with this change at > all". Having it in the middle was what made me surprised. > > Generally, the order of preference is to do "preliminary clean-up" > first, followed by the real change. That way, trivial clean-up that > is designed not to change any behaviour can go ahead and merged down > even before the real change solidifies. After thinking a bit more about it, I'd agree, especially because such an approach makes accepting patches easier. Thank you for pointing that out! > Unrelated changes has no place in a series with a real purpose. > Unless the series is about "assorted clean-ups that are not related > with each other", that is. Having all in mind, especially the addition of a bugfix for the value parsing into the series, I think it's the best if I take the cleanup patch out of the series and send it separately.
diff --git a/Documentation/config.txt b/Documentation/config.txt index 4480bb44203b..2fc4a52d8d76 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -58,11 +58,11 @@ compared case sensitively. These subsection names follow the same restrictions as section names. All the other lines (and the remainder of the line after the section -header) are recognized as setting variables, in the form -'name = value' (or just 'name', which is a short-hand to say that -the variable is the boolean "true"). -The variable names are case-insensitive, allow only alphanumeric characters -and `-`, and must start with an alphabetic character. +header) are recognized as setting variables, in the form 'name = value' +(or just 'name', which is a short-hand to say that the variable is the +boolean "true"). The variable names are case-insensitive, allow only +alphanumeric characters and `-`, and must start with an alphabetic +character. A line that defines a value can be continued to the next line by ending it with a `\`; the backslash and the end-of-line are stripped.
Reformat a few lines a bit, to utilize the available horizontal space better. There are no changes to the actual contents of the documentation. Signed-off-by: Dragan Simic <dsimic@manjaro.org> --- Documentation/config.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)