On 12/25/2012 7:39 AM, Leandro Lucarella wrote:
> Lots of projects take the changelog from the SCM log instead, which is the REAL
> changelog. Of course to do that you have to write good commit messages...

There's an awful lot of irrelevant detail in that log. One bug fix, for example, may consist of numerous "changes" like spelling corrections, incremental progress, etc.

Far better to have a bugzilla list, with clickable links on them to the relevant bugzilla discussion.

On Tuesday, December 25, 2012 04:19:20 Walter Bright wrote:
> On 12/23/2012 8:18 PM, Jonathan M Davis wrote:
> > On Sunday, December 23, 2012 23:13:53 Andrei Alexandrescu wrote:
> >> On 12/23/12 11:08 PM, Jonathan M Davis wrote:
> >>> It's just the WHATSNEW section that makes no sense to automate.
> >> 
> >> Enhancement requests may fill most of the bill...
> > 
> > They definitely don't fill all of it though. We need to be able to put specific messages in the changelog separate from bugzilla entries.
> 
> An example would be helpful, as I'm not seeing the rationale.

I already did. The message about the std.format changes wouldn't make any sense in bugzilla. Not to mention, what are you going to do to get that in the changelog, try and create a bug report with that as its title (assuming that bugzilla will let you create one that long) so that it'll pop up in the changelog? Not to mention, that would put it in the middle of the changelog when we wanted that at the top because of its importance.

Also, I don't think that notices about stuff being deprecated would make any sense in bugzilla. They're not bugs. And I see no reason to try and put notices for new functionality in bugzilla (e.g. module std.x has been added which does XYZZY). In general, what goes in the WHATSNEW section just doesn't make sense in bugzilla. The only exception might be stuff that was enhancement requests which have been implemented.

I'm all for automating the list of bug fixes, but I see zero reason to try and automate what goes in the WHATSNEW section.

- Jonathan M Davis

On Tuesday, December 25, 2012 04:18:10 Walter Bright wrote:
> On 12/25/2012 3:41 AM, Jonathan M Davis wrote:
> > I think that that's what most of us are agreed upon at this point. What is currently the WHATSNEW section will continue to be done by hand, but the LIBBUGSFIXED section will be autogenerated.
> 
> WHATSNEW is a list of new features, which are (or should be) in bugzilla as
> enhancement requests.

So, if we put a new module through the review process, we're going to go and create an ehancement request for it after the fact just so that it's in bugzilla and shows up in the automatically generated changelog? That seems off to me. Bugzilla is for reporting bugs or requesting that things be added to the language or library, not for reporting everything that we do. The SCM log is for that.

Also, some of those sorts of changes should probably get more prominence than they're likely to get in the middle of a list of bugzilla issues, or they may require further explanation.

And it's not like it takes much time or effort to maintain the the WHATSNEW section, as it's much smaller than the bug fix section.

> Various musings, rationales, future changes, etc., should go in a separate document called releasenotes.
> 
> I don't think it's viable to have a document half-generated automatically and half-editted by humans.

I really don't see why not. The section with new stuff gets written by hand and the bug fix section gets created with a bugzilla query. What's so hard about that? I don't think that we've been having any problems whatsoever dealing with the WHATSNEW section. It's the bug fix section that desperately needs automation in order to reduce the amount of human error in it and eliminate the tedium in having to make sure that it's up-to-date.

- Jonathan M Davis

On 12/25/2012 11:19 AM, Jonathan M Davis wrote:
> On Tuesday, December 25, 2012 04:18:10 Walter Bright wrote:
>> On 12/25/2012 3:41 AM, Jonathan M Davis wrote:
>>> I think that that's what most of us are agreed upon at this point. What is
>>> currently the WHATSNEW section will continue to be done by hand, but the
>>> LIBBUGSFIXED section will be autogenerated.
>>
>> WHATSNEW is a list of new features, which are (or should be) in bugzilla as
>> enhancement requests.
>
> So, if we put a new module through the review process, we're going to go and
> create an ehancement request for it after the fact just so that it's in
> bugzilla and shows up in the automatically generated changelog?

Yes. Recall that there are a pretty small number of these, so it's fair to compromise on this.

> That seems off
> to me. Bugzilla is for reporting bugs or requesting that things be added to
> the language or library, not for reporting everything that we do.
> The SCM log is for that.

That log is pretty useless for anyone who wants a list of bug fixes and new features, as it is full of commits that are irrelevant to users.


> Also, some of those sorts of changes should probably get more prominence than
> they're likely to get in the middle of a list of bugzilla issues, or they may
> require further explanation.

Full explanations were never what the changelog was for, that's why it is a list of clickable links.

> And it's not like it takes much time or effort to maintain the the WHATSNEW
> section, as it's much smaller than the bug fix section.

Nor does it take much time or effort to add 3 enhancement requests to Bugzilla for new modules.


>> Various musings, rationales, future changes, etc., should go in a separate
>> document called releasenotes.
>>
>> I don't think it's viable to have a document half-generated automatically
>> and half-editted by humans.
>
> I really don't see why not. The section with new stuff gets written by hand and
> the bug fix section gets created with a bugzilla query. What's so hard about
> that?

Sure it's possible, but I prefer to keep the complexity down of generating the site. Also, releasenotes and changelog serve different purposes, it makes sense to have them be separate documents. (A future change is NOT a change to the current release.)


> I don't think that we've been having any problems whatsoever dealing
> with the WHATSNEW section.

Yes, we have. Things have frequently been omitted.

On 12/25/2012 11:13 AM, Jonathan M Davis wrote:
> I already did. The message about the std.format changes wouldn't make any
> sense in bugzilla.

Such changes would be an enhancement request.

> Not to mention, what are you going to do to get that in the
> changelog, try and create a bug report with that as its title (assuming that
> bugzilla will let you create one that long) so that it'll pop up in the
> changelog? Not to mention, that would put it in the middle of the changelog
> when we wanted that at the top because of its importance.

Bugzilla title: "Changes to std.format". Being a clickable link, one clicks on it to get details listed in the bugzilla entry.

Bugzilla allows issues to be marked as "enhancement requests". Such can then automatically be placed in WHATSNEW.

> Also, I don't think that notices about stuff being deprecated would make any
> sense in bugzilla. They're not bugs.

Bugzilla is more than just bugs, that's why there's a category called enhancement requests.

On Tuesday, 25 December 2012 at 15:39:40 UTC, Leandro Lucarella wrote:
> Lots of projects take the changelog from the SCM log instead, which is the REAL changelog. Of course to do that you have to write good commit messages...

Most of them are irrelevant implementation details that completely defeat the usefulness of a changelog.

On 12/25/12 2:13 PM, Jonathan M Davis wrote:
> I already did. The message about the std.format changes wouldn't make any
> sense in bugzilla.

Would that be appropriate for the release notes?

> I'm all for automating the list of bug fixes, but I see zero reason to try and
> automate what goes in the WHATSNEW section.

Would release notes float your boat?


Andrei

On 12/25/12 2:19 PM, Jonathan M Davis wrote:
> On Tuesday, December 25, 2012 04:18:10 Walter Bright wrote:
>> On 12/25/2012 3:41 AM, Jonathan M Davis wrote:
>>> I think that that's what most of us are agreed upon at this point. What is
>>> currently the WHATSNEW section will continue to be done by hand, but the
>>> LIBBUGSFIXED section will be autogenerated.
>>
>> WHATSNEW is a list of new features, which are (or should be) in bugzilla as
>> enhancement requests.
>
> So, if we put a new module through the review process, we're going to go and
> create an ehancement request for it after the fact just so that it's in
> bugzilla and shows up in the automatically generated changelog? That seems off
> to me. Bugzilla is for reporting bugs or requesting that things be added to
> the language or library, not for reporting everything that we do. The SCM log
> is for that.

It's not all that far-fetched as bugzilla is also a place for enhancement requests. There's really no reason to fight about this. I think s/WHATSNEW/release notes/g pretty much draws an isomorphism between your argument and ours.


Andrei

On Tuesday, December 25, 2012 15:27:42 Andrei Alexandrescu wrote:
> On 12/25/12 2:13 PM, Jonathan M Davis wrote:
> > I already did. The message about the std.format changes wouldn't make any sense in bugzilla.
> 
> Would that be appropriate for the release notes?

Yes. That note in particular is specifically a note for programmers. It's not really a change to the codebase, so if we want to be particular about the meanings of changelog and release notes, it definitely fits in release notes rather than the changelog.

> > I'm all for automating the list of bug fixes, but I see zero reason to try and automate what goes in the WHATSNEW section.
> 
> Would release notes float your boat?

Yes. I think so.

- Jonathan M Davis

On Tuesday, 25 December 2012 at 18:03:38 UTC, Walter Bright wrote:
> On 12/25/2012 7:39 AM, Leandro Lucarella wrote:
>> Lots of projects take the changelog from the SCM log instead, which is the REAL
>> changelog. Of course to do that you have to write good commit messages...
>
> There's an awful lot of irrelevant detail in that log. One bug fix, for example, may consist of numerous "changes" like spelling corrections, incremental progress, etc.

This is only because commits are not done as they should. With git there is no need to do "fix previous commit" because you have rebase -i/amend.

Anyway, is true that even then, there are changes (like refactoring) that's completely irrelevant to users, so you still need to do some filtering to have something useful for the user (not impossible though).

And I want to clarify that I know is not realistic to use the git log now as a changelog, I'm just saying it might be worthwhile to pay some attention on improving the commits to move in that direction, so doing that becomes an option in a distant future.

> Far better to have a bugzilla list, with clickable links on them to the relevant bugzilla discussion.

This is the same if you put a proper comment (fix #N) in the commit message, you get the automatic linking anyway.

Finally, I would love to see improved release notes in DMD, a higher level description of the major changes without having to go through the large (and growing fortunately!) list of bugfixes in each release. I find current changelog to be too verbose about "bugfixes" (bugzilla entries) and too succint about new features (at least including one example would make a big difference).