On Sun, 17 Feb 2013 22:54:54 -0500, Walter Bright
<newshou...@digitalmars.com> wrote:
On 2/17/2013 7:36 PM, Steven Schveighoffer wrote:
On Sun, 17 Feb 2013 21:44:18 -0500, Walter Bright
<newshou...@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
