On Friday, 4 January 2013 at 06:08:02 UTC, Leandro Lucarella wrote:
> Walter Bright, el  3 de January a las 19:18 me escribiste:
>> On 1/3/2013 12:27 PM, Leandro Lucarella wrote:
>> >BTW, Changelogs looks extremely naked now, I think release
> Bugzilla
> is for internal development, not to inform people about new features.

I couldn't agree more. As the documentation is also a *developement task*, Bugzilla could still be used as a tool for improving the documentation development.

However, let's not mistake the tool for the outcome.

Pushing it to the extreme, one could simply fill to the user the compiler, instead the documentation for the compiled language: "you'll read the source code and you'll be able to figure out what it compiles and what it does not".

On Friday, 4 January 2013 at 06:24:37 UTC, Walter Bright wrote:
> On 1/3/2013 9:54 PM, Jonathan M Davis wrote:
> 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

Two concrete examples:

http://d.puremagic.com/issues/show_bug.cgi?id=5992

is described in the list as: " Phobos Win64 - D2 "; At least, change its title to something more human, like "Win64 alpha has been released with working Phobos." (yes, that's exactly Don's comment, but at the end of the discussion).

http://d.puremagic.com/issues/show_bug.cgi?id=5269

is described as: "version(assert)". Only if you read the discussion you understand that "version(unittest) that allows setup code for assertions
to run when assertions are enabled and be compiled out when assertions are
disabled" was implemented.

It is very different thing to see "version(assert)" and reading a meaningful description of it...

On 1/4/2013 12:16 AM, eles wrote:
> Two concrete examples:
>
> http://d.puremagic.com/issues/show_bug.cgi?id=5992
>
> is described in the list as: " Phobos Win64 - D2 "; At least, change its title
> to something more human, like "Win64 alpha has been released with working
> Phobos." (yes, that's exactly Don's comment, but at the end of the discussion).
>
> http://d.puremagic.com/issues/show_bug.cgi?id=5269
>
> is described as: "version(assert)". Only if you read the discussion you
> understand that "version(unittest) that allows setup code for assertions
> to run when assertions are enabled and be compiled out when assertions are
> disabled" was implemented.
>
> It is very different thing to see "version(assert)" and reading a meaningful
> description of it...

I understand and agree. And, as I posted previously, anyone can fix the issue titles. I've already fixed a few.

On Thursday, January 03, 2013 23:42:05 Walter Bright wrote:
> They're commented out with the $(COMMENT ...) macro.

What's their purpose? I can understand automatically generating the list and putting it in changelog.dd or putting some sort of javascript or whatnot in there to generate the list when the page is loaded, but if you're just putting a link to bugzilla to give the list, why list the bugs in a comment which doesn't show up on the webpage at all?

- Jonathan M Davis

On Thursday, January 03, 2013 23:44:26 Walter Bright wrote:
> 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.

No offense taken. It's definitely true that the Phobos developers in general have been spotty in updating the changelog files, and while I've probably been the best at it, it's not like I haven't missed stuff. I completely agree that auto-generating the list of fixed bugs and enhancement requests is a huge improvement. I just don't want to not have the ability to add notes to developers beyond that.

- Jonathan M Davis

04-Jan-2013 07:10, Walter Bright пишет:
> On 1/3/2013 11:36 AM, Jonathan M Davis wrote:
>> Oh. Those are links. I was wondering when the data was actually going
>> to be
>> posted. When compared to the previous ones, it looks like there's only
>> headers
>> with no information.
>
> The idea is to add explanatory information to the bugzilla issue being
> pointed to.
>
> Making some effort to clarify the title of the bugzilla issue is also
> justified.
>
> This change to the changelog presentation does require that we up our
> game with bugzilla - accurate tags (you can see at the top what is being
> keyed on), accurate titles, and accurate information.
>

With all due respect I just plain refused crawling through the list of links of bugzilla to understand the whole amount of changes and/or enhancements.

New features need to be  featured (!) at the top of changelog and represented in the on-line spec obviously.

-- 
Dmitry Olshansky

On Thursday, January 03, 2013 22:34:44 Walter Bright wrote:
> 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.

I honestly think that that gives a _far_ better impression than simply giving a link to a bugzilla query, and it's how most open source projects do their changelogs. The basic look of our changelog with 2.060 and earlier was fairly good. It's just that the bug list wasn't automatically generated. What we've done this time offered a reasonably quick way to get an automatic list, but I think that we should shoot for making it look more like it used to but have the list be automatically generated rather than sticking with the bugzilla query. I'd do it, but doing it well will probably take some javascript voodoo that's well beyond my skill level, as my experience with javascript is about zero. The best I can do is write a quick D program that'll generate the list and then paste that into the changelog (which is what I did with 2.060), but that won't auto-update.

- Jonathan M Davis

On Friday, 4 January 2013 at 10:12:37 UTC, Jonathan M Davis wrote:
> No offense taken. It's definitely true that the Phobos developers in general
> have been spotty in updating the changelog files, and while I've probably been
> the best at it, it's not like I haven't missed stuff.

I think part of the problem was simply that it wasn't clear what should actually go into the changelog files.

Adding all the fixed issues as part of each pull request is not feasible because the frequency of merge conflicts with other pending pull requests would be way too high. Now that we got this aspect covered, I don't see a reason why having a collaboratively managed set of release notes wouldn't work – but maybe it would be better to collect them at the wiki instead of in the repositories?

David

On 2013-01-03 22:31, Pierre Rouleau wrote:

> FWIW, you can see some info here:
> http://forum.dlang.org/thread/k7afq6$2832$1@digitalmars.com

Funny thing, the syntax in the original post by Walter was deprecated from the beginning. The correct syntax is:

@(4) int a;

Or

struct Foo
{
    int b;
}

@Foo(3) int c;

-- 
/Jacob Carlborg

04-Jan-2013 10:44, Jonathan M Davis пишет:
> 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.
>

+1 Can't agree more.

-- 
Dmitry Olshansky