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

Improve release notes #833

Closed
ruflin opened this Issue May 11, 2015 · 7 comments

Comments

Projects
None yet
3 participants
@ruflin
Owner

ruflin commented May 11, 2015

Currently release notes are created from the changes.txt file. Keep this file up-to-date leads to conflicts of pull requests and probably also errors. If possible, release notes should be generated automatically. For release notes I suggest to have the following points/topics inside:

  • Enhancements
  • Backward Compatibility breaks
  • Bugfixes

The release notes should always be published in the Release Tag on Github and on Elastica.io. If possible, both would be based on the same file so it only has to be generated once and could be generated automatically.

@im-denisenko @webdevsHub Your input here is more then welcome. My goal is to simplify and automate the release process to make it more convenient.

@webdevsHub

This comment has been minimized.

Show comment
Hide comment
@webdevsHub

webdevsHub May 11, 2015

Contributor

I never managed an open project so I have no experience in that :(

Some time ago I worked in a project with JIRA and there was a JIRA plugin to generate changelogs for a new release, maybe there is something similar in travis-ci?

A quick research on github led me to https://github.com/skywinder/github-changelog-generator. It generates a markdown file based on tag comparisons. It basically takes the title of closed issues and creates the README.md. It also groups by labels, so we could introduce labels such as "Feature", "BC break", "Bug". The project also has a wiki page with links to other tools https://github.com/skywinder/Github-Changelog-Generator/wiki/Alternatives

Contributor

webdevsHub commented May 11, 2015

I never managed an open project so I have no experience in that :(

Some time ago I worked in a project with JIRA and there was a JIRA plugin to generate changelogs for a new release, maybe there is something similar in travis-ci?

A quick research on github led me to https://github.com/skywinder/github-changelog-generator. It generates a markdown file based on tag comparisons. It basically takes the title of closed issues and creates the README.md. It also groups by labels, so we could introduce labels such as "Feature", "BC break", "Bug". The project also has a wiki page with links to other tools https://github.com/skywinder/Github-Changelog-Generator/wiki/Alternatives

@im-denisenko

This comment has been minimized.

Show comment
Hide comment
@im-denisenko

im-denisenko May 11, 2015

Contributor

I'm against of autogenerated release notes.

Since DVCS was invented, changelog files were deprecated as tool to keep detailed project history, but they moved to higher level of abstraction. Nowadays I expect, that release notes (and changelog) is written for humans by humans, because if I want to know, which exactly commits or pull requests were merged, I could use git log or hg log, whatever. But if my intention is just update my project dependency, then I really don't care, what exactly happens since last version - I want just read short description about what was added, changed or broken. And changelog files in that case is best place to go, because commit history !== actual history.

My suggestion is:

  • Group entries in changes.txt by releases, not by dates.
  • Add dev-master section on top of file for unreleased changes.
  • Rename it to CHANGELOG.md to have markdown.
  • Update it manually every release. Maybe, some tool could be used like one of @webdevsHub mentioned, but final output should be then fixed to be human-readable.
Contributor

im-denisenko commented May 11, 2015

I'm against of autogenerated release notes.

Since DVCS was invented, changelog files were deprecated as tool to keep detailed project history, but they moved to higher level of abstraction. Nowadays I expect, that release notes (and changelog) is written for humans by humans, because if I want to know, which exactly commits or pull requests were merged, I could use git log or hg log, whatever. But if my intention is just update my project dependency, then I really don't care, what exactly happens since last version - I want just read short description about what was added, changed or broken. And changelog files in that case is best place to go, because commit history !== actual history.

My suggestion is:

  • Group entries in changes.txt by releases, not by dates.
  • Add dev-master section on top of file for unreleased changes.
  • Rename it to CHANGELOG.md to have markdown.
  • Update it manually every release. Maybe, some tool could be used like one of @webdevsHub mentioned, but final output should be then fixed to be human-readable.
@webdevsHub

This comment has been minimized.

Show comment
Hide comment
@webdevsHub

webdevsHub May 12, 2015

Contributor

@im-denisenko has some good points (for humans by humans and markdown). An extension to this is http://keepachangelog.com/.

I do not think there is way to avoid CHANGELOG.md conflicts without using a generation tool. The first step should be to create a CONTRIBUTING.md with all that rules and a note that a contributor should wait with CHANGELOG.md updates until the PR is ready to merge to avoid conflicts

Contributor

webdevsHub commented May 12, 2015

@im-denisenko has some good points (for humans by humans and markdown). An extension to this is http://keepachangelog.com/.

I do not think there is way to avoid CHANGELOG.md conflicts without using a generation tool. The first step should be to create a CONTRIBUTING.md with all that rules and a note that a contributor should wait with CHANGELOG.md updates until the PR is ready to merge to avoid conflicts

@ruflin

This comment has been minimized.

Show comment
Hide comment
@ruflin

ruflin May 13, 2015

Owner

I like the CHANGELOG.md and CONTRIBUTING.md suggestion. For the changelog itself, I think it should be "revised" by a human, but not necessarly created by a human. What I do in my projects where we use Jira is that we put a emphasize on writing go JIRA ticket titles which are then directly also the pull request titles. So part of the CONTRIBUTING.md should be to make sure good pull request / issue descriptions are given which directly can be used in the CHANGELOG.md.

As soon as the Release notes are created, do you have an idea how the same release notes could be used for the Github release and on Elastica.io?

Owner

ruflin commented May 13, 2015

I like the CHANGELOG.md and CONTRIBUTING.md suggestion. For the changelog itself, I think it should be "revised" by a human, but not necessarly created by a human. What I do in my projects where we use Jira is that we put a emphasize on writing go JIRA ticket titles which are then directly also the pull request titles. So part of the CONTRIBUTING.md should be to make sure good pull request / issue descriptions are given which directly can be used in the CHANGELOG.md.

As soon as the Release notes are created, do you have an idea how the same release notes could be used for the Github release and on Elastica.io?

@im-denisenko

This comment has been minimized.

Show comment
Hide comment
@im-denisenko

im-denisenko May 13, 2015

Contributor

As soon as the Release notes are created, do you have an idea how the same release notes could be used for the Github release and on Elastica.io?

As the start point, ctrl-c ctrl-v is fine.
Next step is to automatize entire release process in Makefile, I guess.

Contributor

im-denisenko commented May 13, 2015

As soon as the Release notes are created, do you have an idea how the same release notes could be used for the Github release and on Elastica.io?

As the start point, ctrl-c ctrl-v is fine.
Next step is to automatize entire release process in Makefile, I guess.

@ruflin

This comment has been minimized.

Show comment
Hide comment
@ruflin

ruflin May 14, 2015

Owner

For the Release notes: Is that what you were looking for? https://github.com/ruflin/Elastica/blob/changelog-standard/CHANGELOG.md#200---2015-05-11

Not sure why ankers don't work in my file but they work here: https://github.com/olivierlacan/keep-a-changelog/blob/gh-pages/CHANGELOG.md

Owner

ruflin commented May 14, 2015

For the Release notes: Is that what you were looking for? https://github.com/ruflin/Elastica/blob/changelog-standard/CHANGELOG.md#200---2015-05-11

Not sure why ankers don't work in my file but they work here: https://github.com/olivierlacan/keep-a-changelog/blob/gh-pages/CHANGELOG.md

@ruflin

This comment has been minimized.

Show comment
Hide comment
@ruflin

ruflin May 22, 2015

Owner

Closing this as we have now the CONTRIBUTING.md which I think is a very good idea.

Owner

ruflin commented May 22, 2015

Closing this as we have now the CONTRIBUTING.md which I think is a very good idea.

@ruflin ruflin closed this May 22, 2015

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