New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Maintenance of ChangeLog and NEWS files #3190

Open
Quintus opened this Issue Aug 3, 2016 · 6 comments

Comments

Projects
None yet
4 participants
@Quintus

Quintus commented Aug 3, 2016

Hi,

it appears the ChangeLog and NEWS file are unmaintained (they contain no information). I would appreciate it if the NEWS file would duplicate the information from the release announcements to have them readable in the source tree itself, but if there is no intention to maintain either of these files, they should be removed, because it looks confusing otherwise.

Greetings
Marvin

@matz

This comment has been minimized.

Show comment
Hide comment
@matz

matz Aug 3, 2016

Member

You're right. I will remove ChangeLog. Keeping NEWS seems a good idea, if we can maintain. But we clearly haven't done it well, should we remove it too?

Member

matz commented Aug 3, 2016

You're right. I will remove ChangeLog. Keeping NEWS seems a good idea, if we can maintain. But we clearly haven't done it well, should we remove it too?

@bovi

This comment has been minimized.

Show comment
Hide comment
@bovi

bovi Aug 6, 2016

Member

I'm all for removing it or creating a script to generate it out of the git logs for a release candidate.

Member

bovi commented Aug 6, 2016

I'm all for removing it or creating a script to generate it out of the git logs for a release candidate.

@Quintus

This comment has been minimized.

Show comment
Hide comment
@Quintus

Quintus Aug 6, 2016

On Sat, Aug 06, 2016 at 04:35:39AM -0700, Daniel Bovensiepen wrote:

I'm all for removing it or creating a script to generate it out of the
git logs for a release candidate.

No, please not. The Git log is not as informative to someone who does
not actively follow the development. The NEWS file should contain the
user-visible changes, which you cannot automatically generate from the
Git log.

Greetings
Marvin

Quintus commented Aug 6, 2016

On Sat, Aug 06, 2016 at 04:35:39AM -0700, Daniel Bovensiepen wrote:

I'm all for removing it or creating a script to generate it out of the
git logs for a release candidate.

No, please not. The Git log is not as informative to someone who does
not actively follow the development. The NEWS file should contain the
user-visible changes, which you cannot automatically generate from the
Git log.

Greetings
Marvin

@bovi

This comment has been minimized.

Show comment
Hide comment
@bovi

bovi Aug 7, 2016

Member

The NEWS file should contain the user-visible changes, which you cannot automatically generate from the Git log.

I agree fully but most projects I see can't maintain something like that in the long run. So better than nothing or even better then something wrong, I think this would be an option which needs low efforts. And in the end nothing speaks against compressing the git-log output to something more understandable to the general public via additional pull-requests after a release.

Member

bovi commented Aug 7, 2016

The NEWS file should contain the user-visible changes, which you cannot automatically generate from the Git log.

I agree fully but most projects I see can't maintain something like that in the long run. So better than nothing or even better then something wrong, I think this would be an option which needs low efforts. And in the end nothing speaks against compressing the git-log output to something more understandable to the general public via additional pull-requests after a release.

@zzak

This comment has been minimized.

Show comment
Hide comment
@zzak

zzak Aug 7, 2016

Member

I think if you ask people submitting features to add a line to NEWS its much easier to maintain, and don't worry about trying to add every bugfix to the file.

Member

zzak commented Aug 7, 2016

I think if you ask people submitting features to add a line to NEWS its much easier to maintain, and don't worry about trying to add every bugfix to the file.

@Quintus

This comment has been minimized.

Show comment
Hide comment
@Quintus

Quintus Aug 7, 2016

On Sun, Aug 07, 2016 at 05:51:04AM -0700, Daniel Bovensiepen wrote:

The NEWS file should contain the user-visible changes, which you
cannot automatically generate from the Git log.

I agree fully but most projects I see can't maintain something like
that in the long run.

I suggested in the OP that the file should contain copies of the release
announcements. Since these will be written anyway, I don't see much
extra work than copy&paste of the release announcement markup into the
NEWS file. For example, for 1.2.0 it could simply contain the same text
as the 1.2.0 release announcement in the "What's new" section1. If the
info is available anyway, why not add it to the source tree?

Greetings
Marvin

Quintus commented Aug 7, 2016

On Sun, Aug 07, 2016 at 05:51:04AM -0700, Daniel Bovensiepen wrote:

The NEWS file should contain the user-visible changes, which you
cannot automatically generate from the Git log.

I agree fully but most projects I see can't maintain something like
that in the long run.

I suggested in the OP that the file should contain copies of the release
announcements. Since these will be written anyway, I don't see much
extra work than copy&paste of the release announcement markup into the
NEWS file. For example, for 1.2.0 it could simply contain the same text
as the 1.2.0 release announcement in the "What's new" section1. If the
info is available anyway, why not add it to the source tree?

Greetings
Marvin

matz added a commit that referenced this issue Aug 8, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment