[phobos] Changelogs

[Jonathan M Davis]

On Monday 07 March 2011 01:13:08 Russel Winder wrote:
> On Sun, 2011-03-06 at 19:36 -0800, Jonathan M Davis wrote:
> [ . . . ]
> 
> > 2. As it stands, we have one changelog file, and it's in the
> > d-programming-
> 
> [ . . . ]
> 
> A quick challenge to orthodoxy . . .
> 
> Why maintain a changelog at all?  The whole changelog workflow was
> introduced because version control systems were not good enough.  Now
> that Git is being used release notes can be constructed from the commit
> logs as part of the release process.
> 
> On Sun, 2011-03-06 at 21:56 -0800, Walter Bright wrote:
> Some good points.
> 
> > 1. For the *user* of D, rather than the developer of D, I think he'd
> > want to see the changelog in one place rather than clicking around to
> > look at various changelogs.
> 
> Certainly there needs to be a summary of the changes for each release
> for users to tell them what is going to break, or better what cruft can
> be removed in favour of good stuff.  However why write a changelog and a
> commit message?  This seems to be redundancy; definitely not DRY.
> 
> Also what use is a changelog? It's a log not a summary, and what users
> want is a retrospective summary, they don't want a log -- and the log is
> the commit messages, which can be got by issuing a git command.
> 
> > 2. I understand that a single changelog can be problematic for the
> > developer of D. So it is possibly a reasonable solution to create a
> > changelog per phobos, druntime, and dmd, and then merge them for the
> > releases.
> 
> If you have to have a changelog and there are three distinct projects
> then have a new project which is just the changelog for all three?

Honestly, I don't think that your average developer is really going to want to 
go through the git history of the repositories to see what was done. What 
they're likely to care about is a list of bugs and the major changes which have 
occurred since the last release (which is exactly what we currently give them). 
Looking at the git history would be way more of a pain than just glancing over 
the changelog on the main site and would be _way_ more information than they 
necessarily want. If they want to look at the git history, they can look at the 
git history, but I think that the average developer is going to want essentially 
what we've been giving them.

Now, they may really like it if we split what we've been giving them into 
sections so that the compiler was separated from the libraries, but I really 
think that they're still going to want a page like we've been giving them. Not 
to mention, it is quite common among open source projects to have a changelog in 
addition to the repository history, even though the repository history is 
generally completely visible to anyone who wants to look at it.

So, I think that we want to continue as we've been doing and post a changelog 
with the dmd releases. The question is whether we want to section that so that 
the compiler and library stuff aren't mixed together - that and whether we want 
separate changelog files in the repositories themselves. Personally, I'd like to 
have the separate changelog files which get merged into d-programming-
language.org at whatever interval (with them being merged at minimum when a 
release occurs), and I think that there is definitely some merit in splitting up 
the posted changelog into sections instead of having it all together as we have 
been. Not to mention, if we ever get to the point that we decide to separate the 
Phobos release cycle from the dmd release cycle, then having separate changelogs 
makes a _lot_ of sense.

Regardless, I do _not_ think that we should do away with the changelog.

- Jonathan M Davis