On Sun, 17 Feb 2013 20:55:21 -0500, Walter Bright
<newshound2@digitalmars.com> wrote:

> On 2/17/2013 5:31 PM, Mike Parker wrote:
>> Love the new release! Thanks to everyone who contributed. But I just want to
>> throw in my 2 cents about the new changelog format. It's impossible now to tell
>> at a glance what the major changes/fixes are.
>
> It wasn't before, either. It was a list sorted by bugzilla number - no other sort - and it's the same now.
>
>> Clicking through four links to
>> find them is bad enough, but the layout and color scheme of the Bugzilla search
>> results makes it even more time consuming. I know it's easier from a maintenance
>> perspective, but I've lost the motivation to even look at the changelog now. And
>> it's something I really used to look forward to with each release.
>
> I'm sorry, I'm baffled at this. The ordering and the information is exactly the same - a list of issue numbers and the issue title.
>

Let me give you some examples of "new features"

std.array.replace compile error (string and immutable string)
There's no Duration.max
Document extern properly
etc.

Now, I'll sure love the new replace compile error, the missing Duration.max, and the need to document extern as much as the next guy, but can we get some better descriptions? ;)

Some of the descriptions work well for a changelog, but many of them don't.  Even ones that are clear that they were a new feature are worded awkwardly.

For example, the new feature "std.random.uniform!Enum should return random enum member" should really be "std.random.uniform!Enum now returns a random enum member instead of a random integer"

The 'bugs fixed' report can be a link to bugzilla, but being able to read it inline on the changelog would be a good improvement.  These are going to be static lists, there is no need to query them from a DB every time.

-Steve

Walter Bright:

> I'm sorry, I'm baffled at this.

I read bugzilla entries all day long, but I think as a release page information that page gives too much information (the Sev 	Pri 	OS 	Assignee 	Status 	Resolution columns) that's just distracting noise. Sometimes giving less is more.

Bye,
bearophile

On 2/17/13 9:10 PM, Andrej Mitrovic wrote:
> On 2/18/13, Mike Parker<aldacron@gmail.com>  wrote:
>> But I just want to throw in my 2 cents about the new changelog format.
>
> Not just the changelog, but this release announcement too. Two
> sentences, without any information about what is being released, who
> is involved, and a short few sentences on what's new. Very cold, and a
> complete marketing failure.

I agree we need to improve on this. One way to achieve that, seeing as marketing is not Walter's focus, is to denote a release czar who has that particular task around releases. Andrej, would you want to try that role?

Andrei

On 2/17/13 8:02 PM, Walter Bright wrote:
> http://digitalmars.com/d/download.html
>
> The dlang.org site isn't updated yet, but the downloads are there.

I've updated the website, too. Enjoy!

Andrei

On 2/17/2013 6:11 PM, Steven Schveighoffer wrote:
> Let me give you some examples of "new features"
>
> std.array.replace compile error (string and immutable string)
> There's no Duration.max
> Document extern properly
> etc.

Compare the earlier changelogs with the bugzilla entries.

It's EXACTLY THE SAME TEXT.

EXACTLY.

I understand many people do not like the change to the changelog - but I ask for a reason that make sense. I keep hearing that the text is different, but that is simply not so. It's the same exact information. Even the categories are the same.

Also, anyone can go in and change the bugzilla issue titles to make them more readable.

On Sun, 17 Feb 2013 21:44:18 -0500, Walter Bright <newshound2@digitalmars.com> wrote:

> On 2/17/2013 6:11 PM, Steven Schveighoffer wrote:
>> Let me give you some examples of "new features"
>>
>> std.array.replace compile error (string and immutable string)
>> There's no Duration.max
>> Document extern properly
>> etc.
>
> Compare the earlier changelogs with the bugzilla entries.
>
> It's EXACTLY THE SAME TEXT.
>
> EXACTLY.

No.  We have quite a few messages that were not "bug reports" in prior releases.  These messages have no corresponding bugzilla entry.  These were truly useful descriptions.  The bug reports were few, and yes, there were a few instances like the ones I gave (I saw "relax inout rules" which is terrible as a description).

for example:

* std.​array.​insert has been deprecated. Please use std.​array.​insertInPlace instead.
* Major overhaul of std.​regex module's implementation. Breaking change in std.​regex.​replace with delegate, use Captures!string instead of RegexMatch!string as delegate parameter.

The latest versions have almost none of those useful descriptions.  They are almost exclusively of the cryptic you-have-to-click-on-me-to-understand-what-I-mean type.

Even if there are past examples of poor descriptions for the changelog, that is not not an excuse to make them all bugzilla reports.

A good first step would be to examine the bugzilla reports that will be listed as "new features" (should be easy since it's a report that's already being used by the web site), and change the descriptions to real useful enhancement descriptions before the release.  But I think the release needs a hard copy of these descriptions.

> I understand many people do not like the change to the changelog - but I ask for a reason that make sense. I keep hearing that the text is different, but that is simply not so. It's the same exact information. Even the categories are the same.

I did a search for the above two examples in bugzilla, and I found nothing.  Clearly, this is not the exact same information.

>
> Also, anyone can go in and change the bugzilla issue titles to make them more readable.

That actually is not a good thing...  Anyone can maliciously affect the changlog, or alter the changelog at some later point because they wanted to 'reopen' a bug.

-Steve

On 2/17/2013 7:36 PM, Steven Schveighoffer wrote:
> On Sun, 17 Feb 2013 21:44:18 -0500, Walter Bright <newshound2@digitalmars.com>
> wrote:
>
>> On 2/17/2013 6:11 PM, Steven Schveighoffer wrote:
>>> Let me give you some examples of "new features"
>>>
>>> std.array.replace compile error (string and immutable string)
>>> There's no Duration.max
>>> Document extern properly
>>> etc.
>>
>> Compare the earlier changelogs with the bugzilla entries.
>>
>> It's EXACTLY THE SAME TEXT.
>>
>> EXACTLY.
>
> No.  We have quite a few messages that were not "bug reports" in prior
> releases.  These messages have no corresponding bugzilla entry.  These were
> truly useful descriptions.  The bug reports were few, and yes, there were a few
> instances like the ones I gave (I saw "relax inout rules" which is terrible as a
> description).
>
> for example:
>
> * std.​array.​insert has been deprecated. Please use std.​array.​insertInPlace
> instead.
> * Major overhaul of std.​regex module's implementation. Breaking change in std.​
> regex.​replace with delegate, use Captures!string instead of RegexMatch!string
> as delegate parameter.
>
> The latest versions have almost none of those useful descriptions.  They are
> almost exclusively of the cryptic
> you-have-to-click-on-me-to-understand-what-I-mean type.

All that's necessary is to edit the title description. I've done that on a few of them.


> Even if there are past examples of poor descriptions for the changelog, that is
> not not an excuse to make them all bugzilla reports.

It is no more or less effort to fix the bugzilla titles than it is to edit the changelog.


> A good first step would be to examine the bugzilla reports that will be listed
> as "new features" (should be easy since it's a report that's already being used
> by the web site), and change the descriptions to real useful enhancement
> descriptions before the release.  But I think the release needs a hard copy of
> these descriptions.
>
>> I understand many people do not like the change to the changelog - but I ask
>> for a reason that make sense. I keep hearing that the text is different, but
>> that is simply not so. It's the same exact information. Even the categories
>> are the same.
>
> I did a search for the above two examples in bugzilla, and I found nothing.
> Clearly, this is not the exact same information.

With the new system, all changes should have a bugzilla entry for them. With the old, there were occasional vacuous statements in the changelog with no links to any discussion or just what it was.

Look at the changelogs that list an issue number. All of them have the exact same text as the corresponding bugzilla title. I know they're the same because:

1. people requested that they be the same
2. I created them using cut & paste

With bugzilla entries for each item in the changelog, you have:

1. a title
2. discussion
3. link to the pull request that shows the code that changed to implement it

>> Also, anyone can go in and change the bugzilla issue titles to make them more
>> readable.
>
> That actually is not a good thing...  Anyone can maliciously affect the
> changlog, or alter the changelog at some later point because they wanted to
> 'reopen' a bug.

I know that there is the potential for malicious behavior, but thankfully we haven't seen any of that. If we do, we'll have to restrict write access to bugzilla. That'll be a sad day.


If someone wants to step up and take charge of doing a better job with the changelog, I'm all for it. The old way was NOT a better job. It was usually left to me (and Jonathan) to try to cobble something together. When I was the only committer, I'd edit the changelog as things got changed. With the larger number of committers today, this got overlooked. The result was incomplete, inaccurate, and a lot of belated "hey, you left out these changes" after the release.

On Sun, 17 Feb 2013 22:54:54 -0500, Walter Bright <newshound2@digitalmars.com> wrote:

> On 2/17/2013 7:36 PM, Steven Schveighoffer wrote:
>> On Sun, 17 Feb 2013 21:44:18 -0500, Walter Bright <newshound2@digitalmars.com>
>> wrote:
>>
>>> On 2/17/2013 6:11 PM, Steven Schveighoffer wrote:
>>>> Let me give you some examples of "new features"
>>>>
>>>> std.array.replace compile error (string and immutable string)
>>>> There's no Duration.max
>>>> Document extern properly
>>>> etc.
>>>
>>> Compare the earlier changelogs with the bugzilla entries.
>>>
>>> It's EXACTLY THE SAME TEXT.
>>>
>>> EXACTLY.
>>
>> No.  We have quite a few messages that were not "bug reports" in prior
>> releases.  These messages have no corresponding bugzilla entry.  These were
>> truly useful descriptions.  The bug reports were few, and yes, there were a few
>> instances like the ones I gave (I saw "relax inout rules" which is terrible as a
>> description).
>>
>> for example:
>>
>> * std.​array.​insert has been deprecated. Please use std.​array.​insertInPlace
>> instead.
>> * Major overhaul of std.​regex module's implementation. Breaking change in std.​
>> regex.​replace with delegate, use Captures!string instead of RegexMatch!string
>> as delegate parameter.
>>
>> The latest versions have almost none of those useful descriptions.  They are
>> almost exclusively of the cryptic
>> you-have-to-click-on-me-to-understand-what-I-mean type.
>
> All that's necessary is to edit the title description. I've done that on a few of them.

Sure, so we need someone to do that.  But a changelog that is *potentially* informative is not actually informative now.  The previous changelogs were informative.

>> Even if there are past examples of poor descriptions for the changelog, that is
>> not not an excuse to make them all bugzilla reports.
>
> It is no more or less effort to fix the bugzilla titles than it is to edit the changelog.

Who edited the changelog before?  Can that person or people edit the bugzilla entries?

>>> I understand many people do not like the change to the changelog - but I ask
>>> for a reason that make sense. I keep hearing that the text is different, but
>>> that is simply not so. It's the same exact information. Even the categories
>>> are the same.
>>
>> I did a search for the above two examples in bugzilla, and I found nothing.
>> Clearly, this is not the exact same information.
>
> With the new system, all changes should have a bugzilla entry for them. With the old, there were occasional vacuous statements in the changelog with no links to any discussion or just what it was.

I found the statements in the changelog not requiring extra research.  Yes, it is important to have background for the reasoning of a change.  I agree that the statements should have any referenced bugzilla reports included.  But if you are not interested in the background for why a change was made, or the discussion that resulted in the change, or the original concern that led to the change, it is tedious to have to sift through that information to get to the conclusion.  Most changes can be summarized in one sentence for the casual observer.

In the past, I could scan the changelog, look for interesting changes, and the ones I was more interested in, I could drill down into.

A bug is a bug, and saying "we fixed this bug, here was the original description: xxx" is fine.  But new/changed features should have a full explanation and, if necessary, examples right in the description.

> Look at the changelogs that list an issue number. All of them have the exact same text as the corresponding bugzilla title.

Right, and for bugs, that is fine.  For bugs where the bugzilla description completely describes the change, that is fine.  For "feature enhancements" like "std.array.replace compile error (string and immutable string)", I can't determine anything from that, you might as well have just said "Bug 1234".

> With bugzilla entries for each item in the changelog, you have:
>
> 1. a title
> 2. discussion
> 3. link to the pull request that shows the code that changed to implement it

I don't disagree bug links should be in the changelog, nor do I really fundamentally disagree that replacing the changelog with a bugzilla query is a valid changelog.  What I disagree with though is the position that the previous changelog entries that were hand-written were no more informative than the current changelog.

>>> Also, anyone can go in and change the bugzilla issue titles to make them more
>>> readable.
>>
>> That actually is not a good thing...  Anyone can maliciously affect the
>> changlog, or alter the changelog at some later point because they wanted to
>> 'reopen' a bug.
>
> I know that there is the potential for malicious behavior, but thankfully we haven't seen any of that. If we do, we'll have to restrict write access to bugzilla. That'll be a sad day.

It doesn't have to be deliberately malicious behavior.  People think bug reports are bug reports, I've seen several cases where bug reports are re-opened with an issue that is related to the original, maybe they even change the description.  You just changed history, and the changelog.  A changelog for a static release of a piece of software should not be *that* dynamic.

It may be enough to require that bugs that are resolved at the point when a compiler release occurs can no longer be changed by unqualified personnel.

> If someone wants to step up and take charge of doing a better job with the changelog, I'm all for it. The old way was NOT a better job. It was usually left to me (and Jonathan) to try to cobble something together. When I was the only committer, I'd edit the changelog as things got changed. With the larger number of committers today, this got overlooked. The result was incomplete, inaccurate, and a lot of belated "hey, you left out these changes" after the release.

I agree, we need a better system.  Manually edited has its faults, and the current system has its faults.

I propose that when you post the beta on the mailing list, you also post the reports of the fixed bugs and enhancements.  Then people can edit the descriptions before the release.  Then I think after the release, the descriptions should be locked, and the bugs cannot be reopened.

I also would love to see an automatically generated changelog similar to the original based on the bugzilla data.  Can we add a "changelog description" field to bug reports so if the bug description (which arguably shouldn't be changed) isn't a very good changelog entry, that is used instead?

-Steve

On 2/17/2013 9:37 PM, Steven Schveighoffer wrote:
> I propose that when you post the beta on the mailing list, you also post the
> reports of the fixed bugs and enhancements.  Then people can edit the
> descriptions before the release.  Then I think after the release, the
> descriptions should be locked, and the bugs cannot be reopened.

The changelog is up on github, anyone can create a pull request for it. I invite you to.

On Sun, 17 Feb 2013 18:44:18 -0800
Walter Bright <newshound2@digitalmars.com> wrote:

> On 2/17/2013 6:11 PM, Steven Schveighoffer wrote:
> > Let me give you some examples of "new features"
> >
> > std.array.replace compile error (string and immutable string)
> > There's no Duration.max
> > Document extern properly
> > etc.
> 
> Compare the earlier changelogs with the bugzilla entries.
> 
> It's EXACTLY THE SAME TEXT.
> 
> EXACTLY.
> 

No it isn't.

First of all, it's now split across four separate pages. Five if you count the page that doesn't actually contain any real information besides the four links.

Secondly, the new format contains loads of superfluous data. Did the
old changelog page dedicate over 1/3 of the page to rows and rows
and rows of "nor P2 All No Owner RESO FIXE", none of wehich belongs in
a changelog? No it didn't. Definitely NOT the "exact same text".

Third, the old changelog's formatting was overall jsut far more readable.

Fourth, as people said, the wording in the old changelog was much more appropriate for a changelog. Yea, people can update the titles of the zilla entries: Thus making them *very strangely* worded for archived bug reports. But does that actually happen? No (And I'm unconviunced that it even should). Did changelog-appropriate wording happen with the old changelog? Yes.

DO you really think that so many people would be so annoyed with the new format if there *weren't* real problems with it?