Re: changelog format

[Ludovic Courtès]

Hi Stefano,

Stefano Lattarini <address@hidden> skribis:

> On 05/25/2012 04:48 PM, Ludovic Courtès wrote:

[...]

>> Now, sure, that’s not enough.  You also want to know the rationale
>> for a change, and that’s typically discussed on the mailing list,
>>
> And why would condensing the consensus/rationales reached on the list
> into an extra paragraph in the ChangeLog entry be a bad idea exactly?

Mind you, I’m not saying it’s always a bad idea.  However, I find it
more convenient to have a one-sentence summary and a link to the
discussion, to avoid duplication and go “straight to the point.”

[...]

> I absolutely disagree.  Again, I want to refer you to what Samuel wrote here:
> in <http://gcc.gnu.org/ml/gcc/2007-12/msg00016.html>, with which I heartily
> agree.

My feeling is that he’s expecting ChangeLog files to be more than change
logs.  Namely, he expects to find explanations in them, which often
belong in the code.

>> in addition, it should be obvious in this case, since the
>> thing had been deprecated for ages.
>>
> But it took me ten/fifteen minutes to make sure of that (remember, I wasn't
> around here when the original deprecation took place, so I wasn't sure since
> since how long that usage had been deprecated, and how truly obsolete it
> was).  Why force a future developer to waste the same time in case he wants
> to double check the removal is warranted?

I agree that it’s good that this commit log contains references to the
commit ID and discussions, precisely because they allow current and
future developers to quickly find out why this decision was made.

I think it could be shorter than two paragraphs, though; I also think
anything non-obvious changes should be discussed on the list, because
that’s also helpful to the understanding of current and future developers.

[...]

>> I would not write any rationale such as “wouldn’t be needed anyway”.  I
>> would really make it a diff of the abstract syntax trees (that’s what I
>> meant by “semantic patch”.)
>>
> Than I don't understand what you mean, sorry.  Care to elaborate?

If you look at the ChangeLog examples in the GCS, some of them are just
that: a description of the changes made to the abstract syntax tree of
the code (“New function”, “return nil”, “New arg SPECIAL; all callers
changed”, etc.)  Others provide a higher-level description (“Restart the
tex shell if process is gone or stopped.”, etc.)

But in all cases, these are just descriptions of the changes, no more,
no less.

Thanks,
Ludo’.