On 13-01-03 10:18 PM, Walter Bright wrote:
On 1/3/2013 12:27 PM, Leandro Lucarella wrote:
BTW, Changelogs looks extremely naked now, I think release notes are
really needed now. Al least for new features. Is far from ideal to make
people go through a bug report to know how they can adapt their code to
new features.
On the other hand, the older way of doing changelogs routinely missed a
*lot* of things. Relatively few people doing the pulls would bother to
log the changes. I think there were easy double the number of changes
showing up in the search than were in the log.
And sometimes bug reports are not updated on how things turned out, for
example #7041[1], a feature I implemented myself. The bug report is
outdated AFAIK, the title talks about a -di flags which doesn't even
exist, you actually have to go through the pull request[2] to see what
the hell is going on. And even then the behaviour of that pull request
was changed in a subsequent one[3], and there are no visible links
between those 2 pull requests.
Please update that bugzilla issue. As I posted elsewhere in this thread,
this method does require upping our game with bugzilla tags, titles, and
descriptions.
I don't see that it is any *harder* to update the bugzilla issue than it
is to provide a brief summary in the changelog.
As for what's new, the failure here is the failure to document those
changes. This is not a failure of the changelog - it's a failure of the
documentation pages. The bugzilla should have a link to the relevant
documentation.
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).
Anyway, at least for this particular change, the changelog is basically
useless, and I don't think the bug report is the right place to inform
users about compiler changes.
We've been using bugzilla for a long time to organize enhancement requests.
Users don't care about the history and
discussion around a change, they just only want to know how to take
advantage of new features and how to fix their code (possibly with some
exceptions of course, in which case they can still go back to the bug
report and pull requests).
I agree this new system is imperfect - but I argue it is better than
what we were doing before.
I would agree with you that updating documentation and having access to
the exact details is a very good thing to do. And most current
developers already using D will most likely be satisfied with this.
However, for outsiders like me, that manages development groups and is
waiting for D2 to become stable enough to start investing preliminary
prototypes in D2 and developing software in house (first for tools while
training new developers with it) and given the fact that D2 is still
stabilizing, an explicit description of the highlights of the major
changes of a new version is a good selling point for the language.
I was able to introduce Python in a group that was very conservative and
old die-hard C programmers, simply because the documentation of Python
was so well done. Each *major* release is fully documented.
Now, D is newer, D2 is not yet completely stable yet (not that anything
these days is). So maybe I am comparing apples and oranges. Python has
lots of changes between official versions (with its own bug tracker with
all the details of the various changes), but then they have a *release*
version (eg. Python 2.7, Python 3.3, ...) and minor releases on top of
those. The model seems to be a little different in D. Will it get
closer to a model similar to Python in the future? In the Python model
of development it seems easier to create documentations for important
releases.
I really hope D succeeds in becoming an important programming language;
it's got so many nice features and its community is so knowledgeable. A
little PR here and there around the releases, where a quick review would
identify major breakthrough would probably not hurt D's popularity
though. Since I agree on avoiding duplication, would a list of major new
features of the release (similar to what existed in previous logs), made
of links to the updated documentation, help?
Anyway, I know I'm an outsider and have not participated in the
development of this incredible language and all wonderful programs that
the community came up with. I just wanted to give you some feedback
from the outside and, at the same time, thank Walter all the D community
for the wonderful work that has been done!
/Pierre
