« Return to Thread: changelog format
Re: changelog format
by Stefano Lattarini
::
Rate this Message:
Hi Thien, thanks for not giving up on this. Just a couple of minor
observations ...
On 04/28/2012 02:13 PM, Thien-Thi Nguyen wrote:
> () ams@... (Alfred M. Szmidt)
> () Tue, 17 Jan 2012 14:44:05 -0500
>
> - There's no need to describe the full purpose of the
> [...]
> - function definition to explain what it does.
>
> Why is this section removed?
>
> Because it mixes concepts and style (the "however, sometimes
> ... batch of changes"), and because the advice on writing comments
> is no longer fully applicable (to non-software files, mentioned
> first in the following paragraph). Such advice is now an
> "implementation detail", dependent on the kind of change to be
> logged.
>
> + Each group of related entries should have a @dfn{title}, a
> + one line description or summary of the change, and
> + optionally a short paragraph to:
>
> I find the wording confusing here, and don't really understand
> what is optional, or mandatory.
>
> OK.
>
> Making the description line (title is confusing)
>
> To me, "title" suggests succinctness and overall applicability,
> and is itself succinct. What would you suggest instead?
>"Summary" perhaps?
> mandatory is bad. Many changes don't require it.
>
> I'm ambivalent, but only because i still use RCS, for which it
> does seem overkill to require TITLE (though, i have developed a
> habit of including one, anyway).
>
And tomorrow you might convert your RCS repository to git, in which
case you'll indeed be grateful to this habit of yours ;-)
Thanks,
Stefano
observations ...
On 04/28/2012 02:13 PM, Thien-Thi Nguyen wrote:
> () ams@... (Alfred M. Szmidt)
> () Tue, 17 Jan 2012 14:44:05 -0500
>
> - There's no need to describe the full purpose of the
> [...]
> - function definition to explain what it does.
>
> Why is this section removed?
>
> Because it mixes concepts and style (the "however, sometimes
> ... batch of changes"), and because the advice on writing comments
> is no longer fully applicable (to non-software files, mentioned
> first in the following paragraph). Such advice is now an
> "implementation detail", dependent on the kind of change to be
> logged.
>
> + Each group of related entries should have a @dfn{title}, a
> + one line description or summary of the change, and
> + optionally a short paragraph to:
>
> I find the wording confusing here, and don't really understand
> what is optional, or mandatory.
>
> OK.
>
> Making the description line (title is confusing)
>
> To me, "title" suggests succinctness and overall applicability,
> and is itself succinct. What would you suggest instead?
>
> mandatory is bad. Many changes don't require it.
>
> I'm ambivalent, but only because i still use RCS, for which it
> does seem overkill to require TITLE (though, i have developed a
> habit of including one, anyway).
>
And tomorrow you might convert your RCS repository to git, in which
case you'll indeed be grateful to this habit of yours ;-)
Thanks,
Stefano
« Return to Thread: changelog format
| Free embeddable forum powered by Nabble | Forum Help |
