On 1/3/2013 9:54 PM, Jonathan M Davis wrote:
>> I do *not* think that a changelog new feature entry takes the place of
>> updating the documentation, and I do not agree with writing the
>> documentation twice (changelog and documentation).
>
> In general, the only "new features" which need to be in the documentation but
> don't end up there are in dmd. But even then, they need to be in the changelog
> or release notes - preferrably the release notes, if we're separating them. I
> expect that very few people will comb through the list of bug fixes.

New features are not bug fixes. That's why they're listed separately, and there aren't that many of them.


> They want
> to know the highlights, and we should list those. And _no one_ is going to dig
> through the documentation to try and figure out what changed.

Nobody is asking them to. The changelog has a pointer to a proper list of them.

> So, omitting a
> new feature entirely from the changelog or release notes because it's been put
> in the updated documentation makes no sense.

I don't believe I suggested that. I suggested adding a link in the enhancement request bugzilla entry to the right place in the documentation. That way, the documentation only has to be done once. A summary can be added to the bugzilla issue.

> The changelog and release notes
> definitely do _not_ replace proper documentation, but they're a necessary
> companion to it when new features are added or major changes are made.

The changelog list of new features has not gone away. Just click on where it says New/Changed Features at:

   http://dlang.org/changelog.html.

And here's the list:


http://d.puremagic.com/issues/buglist.cgi?chfieldto=2012-12-31&query_format=advanced&chfield=resolution&chfieldfrom=2012-08-02&chfieldvalue=FIXED&bug_severity=enhancement&bug_status=RESOLVED&version=D2&version=D1%20%26%20D2&resolution=FIXED&product=D

Please note that the documentation that was there before in the changelog, but with no corresponding bugzilla entry, has been cut & pasted into the enhancement request bugzilla entry that I created for it.

Nothing has been lost or removed.

In fact, this has pointed out quite a few New/Changed Features that had been omitted from the human curated list. I think that a complete list is better than the buggy, half-assed one we had before.

I will certainly concur that a lot (most?) of the titles on the bugzilla enhancement requests kinda suck, but you or I or anyone else can fix them as necessary, and I did fix a few of them.

On 1/3/2013 9:20 PM, Leandro Lucarella wrote:
> Examples:
> http://python.org/download/releases/3.3.0/

I see a list, one line per, with a clickable link. The only real difference is that there's one extra click to get that list in the D changelog, but then it's a list, one line per, with a clickable link for more info.

> http://llvm.org/releases/3.2/docs/ReleaseNotes.html (this link might be wrong
> because I can't access the llvm website right now to check)

At the moment, that site appears to be down.

On 1/3/2013 8:51 PM, Leandro Lucarella wrote:
> Please, please, consider adding release notes, at least for new features is not
> good enough to just use bugzilla links, you need a clear, succinct explanation
> of the feature. Where would you put it? In the bug report itself? Most of the
> time is not clear enough by the time the bug is created and the feature is
> polished after a long discussion. You shouldn't make users go through the
> entire history of a bug, which is completely internal to the compiler
> development, to know what have changed.

The titles of the bug reports can and should be edited after the fact. That will help a lot.

I'm not saying you're wrong. I'm saying that what you're asking for requires some significant effort from somebody. Nobody has put forth that effort in the past, resulting in the changelog being pretty crummy and woefully incomplete. At least now it is fairly complete.

If anyone wants to do a pull request on the changelog to add to it, that would be great.

On Thursday, January 03, 2013 22:24:34 Walter Bright wrote:
> Please note that the documentation that was there before in the changelog, but with no corresponding bugzilla entry, has been cut & pasted into the enhancement request bugzilla entry that I created for it.
> 
> Nothing has been lost or removed.

And where are items like

$(LI std.range.hasSlicing has been made stricter in an effort to make it more reliable. opSlice for infinite ranges must now return the result of std.range.take, and any range with slicing which supports $(D $) must now support it with the same semantics as arrays (including supporting subtraction for finite ranges).)

That's something that should be listed prominently, not buried in a long list of bugzilla entries. If you want to put that sort of thing in a separate release notes section, fine. But notes like this do _not_ belong in a list of bugzilla entries. They should be prominently displayed to users.

> In fact, this has pointed out quite a few New/Changed Features that had been omitted from the human curated list. I think that a complete list is better than the buggy, half-assed one we had before.
> 
> I will certainly concur that a lot (most?) of the titles on the bugzilla enhancement requests kinda suck, but you or I or anyone else can fix them as necessary, and I did fix a few of them.

I'm all for automating the bug fixes, and it makes perfect sense to handle many of the enhancement requests in the same way, but we should have a way to highlight major changes separately from the list of bugzilla entries (which have no indication of prominence or relative importance) as well as an area for giving specific notes to developers when needed (like major changes they should watch out for or impending changes that they should be aware of). If that's a separate release notes section rather than in the changelog itself, so be it, but we've now completely lost the section that we were using for that sort of thing. Instead, it's now simply a link to a bunch of bugzilla entries.

- Jonathan M Davis


P.S. Also, as a future improvement, we _really_ shouldn't be linking to bugzilla for our list. I've never seen a release notes document or changelog do that in my entire life. It would be _far_ more user friendly to list the changes like we did before with the bug number for each entry linking to the bug report (and it's what most projects to do from what I've seen). Automatically generating the list of bug fixes is great (and a definite step forward), but the current presentation leaves a lot to be desired.

On 1/3/2013 9:49 PM, Jonathan M Davis wrote:
> but other lines like
>
> $(LI std.string: $(RED The implementations of std.string.format and
> string.sformat have been replaced 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.))

Yes, you can put this in as the bugzilla title, though I'd tighten it up a little.


> $(LI std.range.hasSlicing has been made stricter in an effort to make it more
> reliable. opSlice for infinite ranges must now return the result of
> std.range.take, and any range with slicing which supports $(D $) must now
> support it with the same semantics as arrays (including supporting subtraction
> for finite ranges).)

This is 3 separate enhancements, each of which should be its own issue, and will certainly fit as the issue title.


> Automating the bug list is fine, but don't throw away all of the non-bugzilla
> stuff that we've been putting in the changelog.

Nothing has been deleted. In fact, I think those previous items in the 2.060 New/Changed Features are seriously deficient because they contain no hyperlinks for more information.

But, as I mentioned to Leandro, if someone wants to add some additional notes to the changelog file, that's great. But somebody has to do the work, and in the past there generally hasn't been much effort expended there.

Me, I've spent more time than I care to think about keeping that list manually updated, badly.

On 1/3/2013 8:25 PM, Andrei Alexandrescu wrote:
> Andrei "I know better than run my own SMTP/IMAP servers" Alexandrescu

All we need now is a Penny.

On 1/3/2013 7:44 PM, Bernard Helyer wrote:
> * I'm still going to complain. :P

My dad always told me that the time to worry is when there's no grumbling :-)

On Thursday, January 03, 2013 23:03:23 Walter Bright wrote:
> This is 3 separate enhancements, each of which should be its own issue, and will certainly fit as the issue title.

If you think that these work as titles in bugzilla issues, you're missing the point. They're notes that need to be given some prominence and brought to developers' attention, not simply be listed randomly among a bunch of bugzilla enhancement titles.

> But, as I mentioned to Leandro, if someone wants to add some additional notes to the changelog file, that's great. But somebody has to do the work, and in the past there generally hasn't been much effort expended there.

Fine, but then it needs to be clear where those changes are made. I'm one of the people who has generally tried to keep Phobos' and druntime's changelog.dd files up-to-date with changes. But I have no idea where else you'd want it. changelog.dd in d-programming-language.org does not appear to match what's on the website. It seems to list a lot of bugs explictly for 2.061.

- Jonathan M Davis

On 1/3/2013 11:15 PM, Jonathan M Davis wrote:
> On Thursday, January 03, 2013 23:03:23 Walter Bright wrote:
>> This is 3 separate enhancements, each of which should be its own issue, and
>> will certainly fit as the issue title.
>
> If you think that these work as titles in bugzilla issues, you're missing the
> point. They're notes that need to be given some prominence and brought to
> developers' attention, not simply be listed randomly among a bunch of bugzilla
> enhancement titles.
>
>> But, as I mentioned to Leandro, if someone wants to add some additional
>> notes to the changelog file, that's great. But somebody has to do the work,
>> and in the past there generally hasn't been much effort expended there.
>
> Fine, but then it needs to be clear where those changes are made. I'm one of
> the people who has generally tried to keep Phobos' and druntime's changelog.dd
> files up-to-date with changes.

Yes, I know, and I appreciate that.

> But I have no idea where else you'd want it.
> changelog.dd in d-programming-language.org does not appear to match what's on
> the website. It seems to list a lot of bugs explictly for 2.061.

They're commented out with the $(COMMENT ...) macro.

On 1/3/2013 10:42 PM, Walter Bright wrote:
> Nobody has put forth that effort in the
> past, resulting in the changelog being pretty crummy and woefully incomplete.

I apologize to Jonathan for that remark, because Jonathan has been putting out an effort on this.