www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - moving away from changelog.dd?

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
Hello,


We've discussed this a bit before. It's becoming obvious that 
changelog.dd doesn't scale well: it's difficult to keep in sync, people 
forget to add bugs to it etc.

How about we abolish changelog.dd in favor of bugzilla queries? There's 
a simple rule to follow: all changes should have a corresponding entry 
in bugzilla. This is easy to enforce.


Destroy,

Andrei
Dec 23 2012
next sibling parent reply Jonathan M Davis <jmdavisProg gmx.com> writes:
On Sunday, December 23, 2012 20:55:03 Andrei Alexandrescu wrote:
 Hello,
 
 
 We've discussed this a bit before. It's becoming obvious that
 changelog.dd doesn't scale well: it's difficult to keep in sync, people
 forget to add bugs to it etc.
 
 How about we abolish changelog.dd in favor of bugzilla queries? There's
 a simple rule to follow: all changes should have a corresponding entry
 in bugzilla. This is easy to enforce.
 
 
 Destroy,

It's not enough. We need to be able to add items to the changelog separately from bugzilla. There are pretty much always extra items in the changelog which are not bug reports or enhancement requests, and many of them make no sense as items in bugzilla - especially when the whole point of putting them there is to explain something rather than listing a bug number. So, I fully support doing something to automate the portion of the changelog which contains all of the bugzilla entries, but the portion above that where non-bugzilla stuff is entered still needs to be there. We can handle it in some way other than changelog.dd if we want to, but we still need a way to enter stuff into the changelog by hand. - Jonathan M Davis
Dec 23 2012
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/23/12 10:35 PM, Jonathan M Davis wrote:
 So, I fully support doing something to automate the portion of the changelog
 which contains all of the bugzilla entries, but the portion above that where
 non-bugzilla stuff is entered still needs to be there. We can handle it in some
 way other than changelog.dd if we want to, but we still need a way to enter
 stuff into the changelog by hand.

Some other way may as well be introduce entries in bugzilla. Again, dealing with the changelog has become more costly than beneficial. Andrei
Dec 23 2012
next sibling parent =?UTF-8?B?QWxleCBSw7hubmUgUGV0ZXJzZW4=?= <alex lycus.org> writes:
On 24-12-2012 14:59, SomeDude wrote:
 On Monday, 24 December 2012 at 03:51:37 UTC, Bernard Helyer wrote:
 On Monday, 24 December 2012 at 03:48:47 UTC, Andrei Alexandrescu
 wrote:
 Some other way may as well be introduce entries in bugzilla.

Is adding things that don't belong in bugzilla to bugzilla really a great idea?

Such as what ?

Jonathan gave an example with the std.string.format change. -- Alex Rønne Petersen alex lycus.org http://lycus.org
Dec 24 2012
prev sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/24/12 8:59 AM, SomeDude wrote:
 On Monday, 24 December 2012 at 03:51:37 UTC, Bernard Helyer wrote:
 On Monday, 24 December 2012 at 03:48:47 UTC, Andrei Alexandrescu
 wrote:
 Some other way may as well be introduce entries in bugzilla.

Is adding things that don't belong in bugzilla to bugzilla really a great idea?

Such as what ?

Same question - far as I can tell Bugzilla is meant to track all changes to a software product, so I'd be hard pressed to come with something that's not appropriate for it. Andrei
Dec 24 2012
parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/24/2012 9:03 AM, Jonathan M Davis wrote:
 How about the very example that I gave about specifically providing a note to
 developers about the impending changes to std.format? No bug had been fixed,
 and no enhancement request had been implemented. No code change had even taken
 place yet. It was a note about a future change that developers needed to be
 made aware of.

Well, a future change shouldn't be in a *change* log any more than it should be in bugzilla. What you're talking about should be called "release notes".
Dec 25 2012
next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
On 12/25/2012 3:14 AM, Jonathan M Davis wrote:
 On Tuesday, December 25, 2012 03:07:35 Walter Bright wrote:
 What you're talking about should be called "release notes".

If you want to be pedantic about it, sure. But we don't have release notes separate from the changelog at this point. And while some changes which aren't currently put in bugzilla _could_ be put there (e.g. the addition of a new module), that doesn't necessarily mean that they belong there. So, while automating the list of bug fixes makes good sense, having a section of the changelog or release notes or whatever which is written by humans also makes good sense.

I'd be in favor of a changelog auto-generated from bugzilla, and a human editted releasenotes. Because, as Andrei pointed out, maintaining the changelog is currently tedious and error prone. I know that a number of pull requests have not made it into the current changelog, because the people who pull them do not go through the tedium of doing that, and they shouldn't have to. Automation is the answer.
Dec 25 2012
parent reply Walter Bright <newshound2 digitalmars.com> writes:
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. 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.
Dec 25 2012
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/25/12 7:18 AM, 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. 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.

Yes please. I was about to write something along the same lines - glad I read this first. Andrei
Dec 25 2012
prev sibling next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
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.
Dec 25 2012
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Dec 25 2012
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
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.
Dec 25 2012
parent Walter Bright <newshound2 digitalmars.com> writes:
On 12/25/2012 6:40 PM, Leandro Lucarella wrote:
 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).

To avoid duplication of effort, I'd rather see the changelog (or bugzilla) contain links to the relevant permanent documentation for whatsnew changes.
Dec 25 2012
prev sibling next sibling parent "Bernard Helyer" <b.helyer gmail.com> writes:
On Monday, 24 December 2012 at 03:48:47 UTC, Andrei Alexandrescu
wrote:
 Some other way may as well be introduce entries in bugzilla.

Is adding things that don't belong in bugzilla to bugzilla really a great idea?
Dec 23 2012
prev sibling next sibling parent reply "Maxim Fomin" <maxim maxim-fomin.ru> writes:
On Monday, 24 December 2012 at 01:55:04 UTC, Andrei Alexandrescu 
wrote:
 Hello,


 We've discussed this a bit before. It's becoming obvious that 
 changelog.dd doesn't scale well: it's difficult to keep in 
 sync, people forget to add bugs to it etc.

 How about we abolish changelog.dd in favor of bugzilla queries? 
 There's a simple rule to follow: all changes should have a 
 corresponding entry in bugzilla. This is easy to enforce.


 Destroy,

 Andrei

Why not enforce github pulls to provide updates to changelog?
Dec 23 2012
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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... Andrei
Dec 23 2012
next sibling parent Jacob Carlborg <doob me.com> writes:
On 2012-12-24 05:18, Jonathan M Davis wrote:

 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.

Yeah, we need to put this information manually somewhere anyway. Why not directly into changelog.dd -- /Jacob Carlborg
Dec 24 2012
prev sibling next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/24/12 8:49 AM, monarch_dodra wrote:
 Would it be a crazy idea to move the page to the wiki, and only pack it
 back into dmd when it gets packaged?

 I'd say the problem with changelog.dd is the effort associated with
 modifying it, no? On the wiki, it's basically "edit" "write" "commit"
 "done".

 The fact that you have to do an actual pull just to add an entry to a
 changelog makes something that should be easy as pie a real chore, and
 work grinds to a halt.

That's a nice idea. Is it an issue that anyone can edit that page? Andrei
Dec 24 2012
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
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.
Dec 25 2012
next sibling parent Walter Bright <newshound2 digitalmars.com> writes:
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.
Dec 25 2012
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Dec 25 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Sunday, December 23, 2012 22:48:47 Andrei Alexandrescu wrote:
 On 12/23/12 10:35 PM, Jonathan M Davis wrote:
 So, I fully support doing something to automate the portion of the
 changelog which contains all of the bugzilla entries, but the portion
 above that where non-bugzilla stuff is entered still needs to be there.
 We can handle it in some way other than changelog.dd if we want to, but
 we still need a way to enter stuff into the changelog by hand.

Some other way may as well be introduce entries in bugzilla. Again, dealing with the changelog has become more costly than beneficial.

It's costly because of bugzilla. If you automate that part, then I think we're fine. But i don't think that it makes any sense whatsoever to put the non- bugzilla stuff in bugzilla. For instance, take this line from the top of the 2.060 changelog: $(LI std.string: $(RED The current implementations of std.string.format and string.sformat are scheduled to be replaced in November 2012 with improved implementations which conform to writef. In some, rare cases, this will break code. Please see the documentation for std.string.format and std.string.sformat for details.)) How would you do that with a bugzilla entry? Try and create a bug with that title? Even assuming that bugzilla allows you to create a bug with a title that long, it'll then be buried among all of the bug fixes and have a pointless bug# on it, when it specifically needed to be put at the top. I really think that the WHATSNEW section needs to stay as it is, and I don't think that it's really all that big a deal to maintain it. It would be to automate the LIBBUGSFIXED section, but I don't think that it should be mixed in with the WHATSNEW section, and the WHATSNEW section is very ill-suited to being put in bugzilla. - Jonathan m Davis
Dec 23 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Monday, December 24, 2012 05:04:24 Maxim Fomin wrote:
 Why not enforce github pulls to provide updates to changelog?

Because then you get merge conflicts galore. It makes a _lot_ of sense to automate the bugs section of the changelog. Worst case, it's not all that hard to write a program to grab the data and format it appropriately for changelog.dd, but it should be quite possible to put that query in the changelog html page itself. I think that it would be a mistake to try and enforce more process with regards to changelog.dd in order to get the bug entries in there, especially when it's not all that hard to automate. It's just the WHATSNEW section that makes no sense to automate. - Jonathan M Davis
Dec 23 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
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. I really don't see why it's that big a deal that the WHATSNEW section isn't automated though. It's the LIBBUGSFIXED section that causes all the grief, and that's easily automated. - Jonathan M Davis
Dec 23 2012
prev sibling next sibling parent "Kapps" <opantm2+spam gmail.com> writes:
On Monday, 24 December 2012 at 04:19:44 UTC, 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. I really don't see why it's that big a deal that the WHATSNEW section isn't automated though. It's the LIBBUGSFIXED section that causes all the grief, and that's easily automated. - Jonathan M Davis

Personally I think it nicer that things like What's New would be written out by a human. Instead of just "Enhancement #4713: Add user-defined annotations", you can give a quick explanation of what actually was added and a link to get more info about it. Same for phobos modules and the like.
Dec 23 2012
prev sibling next sibling parent "monarch_dodra" <monarchdodra gmail.com> writes:
On Monday, 24 December 2012 at 04:48:07 UTC, Kapps wrote:
 On Monday, 24 December 2012 at 04:19:44 UTC, 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. I really don't see why it's that big a deal that the WHATSNEW section isn't automated though. It's the LIBBUGSFIXED section that causes all the grief, and that's easily automated. - Jonathan M Davis

Personally I think it nicer that things like What's New would be written out by a human. Instead of just "Enhancement #4713: Add user-defined annotations", you can give a quick explanation of what actually was added and a link to get more info about it. Same for phobos modules and the like.

Would it be a crazy idea to move the page to the wiki, and only pack it back into dmd when it gets packaged? I'd say the problem with changelog.dd is the effort associated with modifying it, no? On the wiki, it's basically "edit" "write" "commit" "done". The fact that you have to do an actual pull just to add an entry to a changelog makes something that should be easy as pie a real chore, and work grinds to a halt.
Dec 24 2012
prev sibling next sibling parent "SomeDude" <lovelydear mailmetrash.com> writes:
On Monday, 24 December 2012 at 03:51:37 UTC, Bernard Helyer wrote:
 On Monday, 24 December 2012 at 03:48:47 UTC, Andrei Alexandrescu
 wrote:
 Some other way may as well be introduce entries in bugzilla.

Is adding things that don't belong in bugzilla to bugzilla really a great idea?

Such as what ?
Dec 24 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Monday, December 24, 2012 11:41:22 Andrei Alexandrescu wrote:
 On 12/24/12 8:59 AM, SomeDude wrote:
 On Monday, 24 December 2012 at 03:51:37 UTC, Bernard Helyer wrote:
 On Monday, 24 December 2012 at 03:48:47 UTC, Andrei Alexandrescu
 
 wrote:
 Some other way may as well be introduce entries in bugzilla.

Is adding things that don't belong in bugzilla to bugzilla really a great idea?

Such as what ?

Same question - far as I can tell Bugzilla is meant to track all changes to a software product, so I'd be hard pressed to come with something that's not appropriate for it.

How about the very example that I gave about specifically providing a note to developers about the impending changes to std.format? No bug had been fixed, and no enhancement request had been implemented. No code change had even taken place yet. It was a note about a future change that developers needed to be made aware of. And while you _could_ put stuff like the inclusion of a new module in bugzilla, I really don't think that it belongs there. Bugzilla is for bug reports and enhancement requests, not for notes about changes to the code base. You can look at source control for those. I don't understand why you're so against having notes from human beings in the changelog. Yes, automating the list of bugs would be great, because that list is tedious and error-prone, but I dispute that it buys us anything to try and do the same with the WHATSNEW section. If anything, it makes things worse by trying to shoehorn non-bugs into bug reports. - Jonathan M Davis
Dec 24 2012
prev sibling next sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On 12/24/12, Jonathan M Davis <jmdavisProg gmx.com> wrote:
 I don't understand why you're so against having notes from human beings in
 the changelog.

I don't understand why we can't have both. One is a list automatically added via bugzilla, and then a separate section of handwritten changes.
Dec 24 2012
prev sibling next sibling parent reply Jonathan M Davis <jmdavisProg gmx.com> writes:
On Monday, December 24, 2012 18:08:58 Andrej Mitrovic wrote:
 On 12/24/12, Jonathan M Davis <jmdavisProg gmx.com> wrote:
 I don't understand why you're so against having notes from human beings in
 the changelog.

I don't understand why we can't have both. One is a list automatically added via bugzilla, and then a separate section of handwritten changes.

Exactly. - Jonathan M Davis
Dec 24 2012
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 12/24/12 12:12 PM, Jonathan M Davis wrote:
 On Monday, December 24, 2012 18:08:58 Andrej Mitrovic wrote:
 On 12/24/12, Jonathan M Davis<jmdavisProg gmx.com>  wrote:
 I don't understand why you're so against having notes from human beings in
 the changelog.

I don't understand why we can't have both. One is a list automatically added via bugzilla, and then a separate section of handwritten changes.

Exactly.

worksforme(tm) Thanks, Andrei
Dec 24 2012
prev sibling parent Dmitry Olshansky <dmitry.olsh gmail.com> writes:
12/24/2012 9:12 PM, Jonathan M Davis пишет:
 On Monday, December 24, 2012 18:08:58 Andrej Mitrovic wrote:
 On 12/24/12, Jonathan M Davis <jmdavisProg gmx.com> wrote:
 I don't understand why you're so against having notes from human beings in
 the changelog.

I don't understand why we can't have both. One is a list automatically added via bugzilla, and then a separate section of handwritten changes.

Exactly. - Jonathan M Davis

+1 Just make changelog.dd to be manually edited list of what's new + future plans. Then tuck in an automated tool to generate bugs section to the release packaging scripts. And automating bug entries list is trivial e.g. here is a D sketch (std.net.curl & std.csv rox) to generate DDoc entries in current changelog.dd format given 2 dates: https://gist.github.com/3734045 And staying on topic it would be terrific (and simple) to have separate sections on bugzilla entries fixed per category: bugs/enhancements/regressions. -- Dmitry Olshansky
Dec 24 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Monday, December 24, 2012 14:49:59 monarch_dodra wrote:
 Would it be a crazy idea to move the page to the wiki, and only
 pack it back into dmd when it gets packaged?
 
 I'd say the problem with changelog.dd is the effort associated
 with modifying it, no? On the wiki, it's basically "edit" "write"
 "commit" "done".
 
 The fact that you have to do an actual pull just to add an entry
 to a changelog makes something that should be easy as pie a real
 chore, and work grinds to a halt.

I thought about that, but I question that it buys us much. The bugzilla portion should be automated. That then only leaves the WHATSNEW section, which has far fewer entries. The wiki also opens us up to stray who-knows-who editing it, which may or may not be a problem. I really don't think that it's all that big a deal to create a pull request for a WHATSNEW section change (it's also the sort of thing which is likely to be pulled quickly), and if those are rare enough, and they relate to a specific pull request (as they often do), then you can simply put the changelog change in that pull request. I generally avoid that because of the risk of merge conflicts with changelog.dd, but if the list of bugzilla changelog items is automated, then the number of items which need to be put into changelog.dd is far lower, and the risk of merge conflicts is significantly reduced. - Jonathan M Davis
Dec 24 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Tuesday, December 25, 2012 03:07:35 Walter Bright wrote:
 On 12/24/2012 9:03 AM, Jonathan M Davis wrote:
 How about the very example that I gave about specifically providing a note
 to developers about the impending changes to std.format? No bug had been
 fixed, and no enhancement request had been implemented. No code change
 had even taken place yet. It was a note about a future change that
 developers needed to be made aware of.

Well, a future change shouldn't be in a *change* log any more than it should be in bugzilla. What you're talking about should be called "release notes".

If you want to be pedantic about it, sure. But we don't have release notes separate from the changelog at this point. And while some changes which aren't currently put in bugzilla _could_ be put there (e.g. the addition of a new module), that doesn't necessarily mean that they belong there. So, while automating the list of bug fixes makes good sense, having a section of the changelog or release notes or whatever which is written by humans also makes good sense. - Jonathan M Davis
Dec 25 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
On Tuesday, December 25, 2012 03:20:26 Walter Bright wrote:
 On 12/25/2012 3:14 AM, Jonathan M Davis wrote:
 On Tuesday, December 25, 2012 03:07:35 Walter Bright wrote:
 What you're talking about should be called "release notes".

If you want to be pedantic about it, sure. But we don't have release notes separate from the changelog at this point. And while some changes which aren't currently put in bugzilla _could_ be put there (e.g. the addition of a new module), that doesn't necessarily mean that they belong there. So, while automating the list of bug fixes makes good sense, having a section of the changelog or release notes or whatever which is written by humans also makes good sense.

I'd be in favor of a changelog auto-generated from bugzilla, and a human editted releasenotes. Because, as Andrei pointed out, maintaining the changelog is currently tedious and error prone. I know that a number of pull requests have not made it into the current changelog, because the people who pull them do not go through the tedium of doing that, and they shouldn't have to. Automation is the answer.

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. - Jonathan M Davis
Dec 25 2012
prev sibling next sibling parent "Leandro Lucarella" <leandro.lucarella sociomantic.com> writes:
On Tuesday, 25 December 2012 at 11:15:17 UTC, Jonathan M Davis 
wrote:
 On Tuesday, December 25, 2012 03:07:35 Walter Bright wrote:
 On 12/24/2012 9:03 AM, Jonathan M Davis wrote:
 How about the very example that I gave about specifically 
 providing a note
 to developers about the impending changes to std.format? No 
 bug had been
 fixed, and no enhancement request had been implemented. No 
 code change
 had even taken place yet. It was a note about a future 
 change that
 developers needed to be made aware of.

Well, a future change shouldn't be in a *change* log any more than it should be in bugzilla. What you're talking about should be called "release notes".

If you want to be pedantic about it, sure. But we don't have release notes separate from the changelog at this point. And while some changes which aren't currently put in bugzilla _could_ be put there (e.g. the addition of a new module), that doesn't necessarily mean that they belong there. So, while automating the list of bug fixes makes good sense, having a section of the changelog or release notes or whatever which is written by humans also makes good sense.

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...
Dec 25 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
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
Dec 25 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
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
Dec 25 2012
prev sibling next sibling parent "SomeDude" <lovelydear mailmetrash.com> writes:
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.
Dec 25 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
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
Dec 25 2012
prev sibling next sibling parent "Leandro Lucarella" <leandro.lucarella sociomantic.com> writes:
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).
Dec 25 2012
prev sibling parent "foobar" <foo bar.com> writes:
On Tuesday, 25 December 2012 at 19:44:41 UTC, Walter Bright wrote:
 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.

It seems everyone agrees there need to be an automated changelog and a hand written release-notes. I don't see a point to continue bikeshading whether they belong in a single document or two separate ones. Just pick the one that is easiest to implement! We can always add a link to the changelog from the release-notes to satisfy those that want a single document. The more important issue is whether to add bugzilla entries after the fact and whether the changelog should be geberated from Git or bugzilla. In the _current_ state of affairs yor (walter) are correct that relying on git log messages will be useless. BUT, this is only another symptom of the current broken process. The CORRECT way to implement this would be to take the actual changes from the SCM (git) on the RELEASE branch (as opposed to the development branch) and filter it to only use MERGE commits. What that does is, it ignores all the intermediate development commits that are irrelevant. Filling up bugzilla with entries that do not belong there shouldn't be the long term solution.
Dec 26 2012