I'll bring this up again, since it didn't really go anywhere the last time it was brought up. We have two issues with changelogs.

1. Changes to dmd, druntime, and Phobos are always lumped together in the changelog for a release. This may or may not be desirable. Some have expressed interest in separating them out - either as three projects or as two projects with druntime lumped in with either dmd or Phobos.

2. As it stands, we have one changelog file, and it's in the d-programming- language.org repository. Most of us don't have commit access to d-programming- language.org, so if we want to update the changelog, we need to create a pull request, and it seems rather silly to create a pull request for something that small (not to mention, that encourages updating the changelog only when a release happens when we really should be updating it as we fix bugs). So, either, we need to have a separate changelog file in each project which is combined as one in some manner in d-programming-language.org when a release happens, or we need all of the Phobos devs to have commit access to d-programming-language.org so that they can update the changelog themselves.

So, the first question is do we create changelog files in dmd, druntime, and Phobos and then combine them into the one in d-programming-language.org when we do a release, or do we make it so that all of the Phobos devs have commit access to d-programming-language.org?

And the second question is whether we want to split up the information in the changelog by project in some manner? If we do, having a changelog file per project makes a lot of sense, regardless of whether we want all of the Phobos devs to have commit access to d-programming-language.org.

- Jonathan M Davis

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.

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.

Jonathan M Davis wrote:
> I'll bring this up again, since it didn't really go anywhere the last time it was brought up. We have two issues with changelogs.
>
> 1. Changes to dmd, druntime, and Phobos are always lumped together in the changelog for a release. This may or may not be desirable. Some have expressed interest in separating them out - either as three projects or as two projects with druntime lumped in with either dmd or Phobos.
>
> 2. As it stands, we have one changelog file, and it's in the d-programming- language.org repository. Most of us don't have commit access to d-programming- language.org, so if we want to update the changelog, we need to create a pull request, and it seems rather silly to create a pull request for something that small (not to mention, that encourages updating the changelog only when a release happens when we really should be updating it as we fix bugs). So, either, we need to have a separate changelog file in each project which is combined as one in some manner in d-programming-language.org when a release happens, or we need all of the Phobos devs to have commit access to d-programming-language.org so that they can update the changelog themselves.
>
> So, the first question is do we create changelog files in dmd, druntime, and Phobos and then combine them into the one in d-programming-language.org when we do a release, or do we make it so that all of the Phobos devs have commit access to d-programming-language.org?
>
> And the second question is whether we want to split up the information in the changelog by project in some manner? If we do, having a changelog file per project makes a lot of sense, regardless of whether we want all of the Phobos devs to have commit access to d-programming-language.org.
>
> - Jonathan M Davis
> _______________________________________________
> phobos mailing list
> phobos at puremagic.com
> http://lists.puremagic.com/mailman/listinfo/phobos
>
>
> 

On Sunday 06 March 2011 21:56:23 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.
> 
> 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.

I don't believe that anyone was necessarily suggesting that the changelogs be separate pages. I think that it was more like the changelog for a given release would be split up into sections for dmd, druntime, and Phobos - or perhaps just the compiler and the libraries - but it would all still be on the same page. It would just be sectioned differently.

Having separate changelog files would facilitate that, and it would make it easier for developers on each project to update the changelog for that project without needing commit access to d-programming-language.org. Obviously, the entries from each file would have to be merged into the d-programming- language.org file before the release however.

- Jonathan M Davis

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?

-- 
Russel. ============================================================================= Dr Russel Winder      t: +44 20 7585 2200   voip: sip:russel.winder at ekiga.net 41 Buckmaster Road    m: +44 7770 465 077   xmpp: russel at russel.org.uk London SW11 1EN, UK   w: www.russel.org.uk  skype: russel_winder
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part
URL: <http://lists.puremagic.com/pipermail/phobos/attachments/20110307/31141493/attachment.pgp>

On 03/07/2011 10:13 AM, 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?

In general: Seems to make sense. If commit logs become final change logs, then
people would have to write meaningful commit logs (which in general is far to
be a given ;-).
Also, user change logs often hardly can be devlopper change logs, as you say.
(Think at yourself reading change logs of an app you are a /user/ of, even
being a programmer... usually uncomprehensible.)

Denis
-- 
_________________
vita es estrany
spir.wikidot.com

spir wrote:
> On 03/07/2011 10:13 AM, 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?
> 
> In general: Seems to make sense. If commit logs become final change
> logs, then people would have to write meaningful commit logs (which
> in general is far to be a given ;-).
> Also, user change logs often hardly can be devlopper change logs, as
> you say. (Think at yourself reading change logs of an app you are a
> /user/ of, even being a programmer... usually uncomprehensible.)

git-extras (https://github.com/visionmedia/git-extras) may be helpful
for changelogs. It ships with git changelog which generates a template
based on the commits since the last release and opens an editor.
I suppose you can find more tools to support such tasks.

Jens

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