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.
