Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Generate changelog? #1430

Closed
gravitystorm opened this issue Mar 20, 2015 · 23 comments
Closed

Generate changelog? #1430

gravitystorm opened this issue Mar 20, 2015 · 23 comments
Assignees
@gravitystorm @pnorman
Labels
general
Milestone
Bugs and improvem...

Comments

@gravitystorm
Copy link
Owner

When I find other projects without a changelog, they annoy me. But I certainly don't want to maintain one by hand - that'll just slow down the release process and is too boring and too much effort.

I found https://github.com/skywinder/github-changelog-generator which looks promising. We operate pretty much exclusively through issues and pull requests, so it can pick up almost all that we do.

I've generated an example using the option --no-issues and it's at https://gist.github.com/gravitystorm/6ecdd3ec6d5656fa03b6 . I'm not against issues showing up, but I didn't like seeing the ones that were closed wontfix

What do people think? Is it a good idea to have a changlog, and if so, is this tool appropriate?
@matthijsmelissen
Copy link
Collaborator

So far @pnorman and I are sending manually generated messages to talk and dev. See for example this message. I think the manually generated list is much more pleasant to read. For someone wanting more details, we link to the full list of commits.

Generating the change log manually also has the advantage of being able to combine multiple similar changes into one line, and on the other hand to expand large change requests (such as the water-features on) in multiple lines.

The target audience of the messages to talk and dev might be a bit different from the target audience of a changelog, though. For example, I don't mention internal refactoring that doesn't have effect on rendering.

With respect to this particular tool: it looks at the date a commit is authored, not when it is merged, to decide to which version a PR belongs. That means that some PRs, for example 'add rendering for amenity=car_rental #1388 (nebulon42)', are classed in the wrong version. I'm not sure if it's possible to change this behaviour?

In any case, compiling the list of commits into a human-readable changelog is not much work (not more than 30 minutes), and in my opinion is more helpful than a mechanically generated changelog. Of course. there is no reason we cannot have both.

@pnorman
Copy link
Collaborator

pnorman commented Mar 20, 2015

I was thinking of opening the same issue...

I'd rather use the manually generated messages, as they're a selection of what we consider significant. I can combine all my pre-hstore SQL cleanup PRs into one message.

I do note that the generator added #1342, which was a PR we didn't merge.

@mboeringa
Copy link

I do support the idea of a changelog, even if it is auto-generated. There are definitely cases when it is useful to have a comprehensive overview of (all) issues fixed or stuff changed in a specific version / release.

I am not to bothered with the discussion of auto-generated versus manual, the auto-generated version will find its usage too... as long as it is accurate, which may be an issue considering the remarks by @math1985 and @pnorman...

@matkoniecz
Copy link
Contributor

With respect to this particular tool: it looks at the date a commit is authored, not when it is merged, to decide to which version a PR belongs. That means that some PRs, for example 'add rendering for amenity=car_rental #1388 (nebulon42)', are classed in the wrong version. I'm not sure if it's possible to change this behaviour?

I opened github-changelog-generator/github-changelog-generator#256

@skywinder
Copy link

I'm not against issues showing up, but I didn't like seeing the ones that were closed wontfix

Hi! The last version is automatically exclude issues, that not-related to change log (any issue, that has label question duplicate invalid wontfixby default)

As I can see - you are using a lot of custom labels for issues.
So, you can also use options --exclude-labels to specify your own list of labels, that shouldn't appear in change log.

@pnorman
Copy link
Collaborator

pnorman commented Aug 3, 2015

I generated a changelog at https://gist.github.com/pnorman/962619427ba90e134873

A few observations

@HolgerJeromin
Copy link
Contributor

The seperation of pull request and issues is IMO not helpful with our many changes. If a PR closes an issue it should be only listed below the PR.

@skywinder should i open a corresponding issue on your project?

@skywinder
Copy link

@pnorman

  1. this issue described here: Exclude related issues or PR's to avoid redundancy  github-changelog-generator/github-changelog-generator#67 I don't know, I make some research, but don't know to detect correctly related issue. I would be glad for help.
  2. in old merged PR listed for a wrong release github-changelog-generator/github-changelog-generator#256 I describe some cases, that will be incorrect, if I will resolve issue in your way. So, until we not find non-destructive implementation of this feature - the only workaround is using milestones with specified version.
  3. if you have another ideas - how to manage issues - I will be glad to discuss.
  4. can't understand, how Quick dev. environment using Vagrant & Salt #1342 related to change log generation

@skywinder
Copy link

@HolgerJeromin I believe this issue is already exists: github-changelog-generator/github-changelog-generator#67 But I don't know how to resolve it yet.

@HolgerJeromin
Copy link
Contributor

You know the PR number (you write it at the end), and in it there must be the magic word "fixes #xy, superseed #xy, and others" in the commit title or comment.

@pnorman
Copy link
Collaborator

pnorman commented Aug 3, 2015

can't understand, how #1342 related to change log generation

This was an issue that was incorrectly showing up when github-changelog-generator was run by @gravitystorm back in March.

@gravitystorm gravitystorm self-assigned this Mar 2, 2016
@gravitystorm
Copy link
Owner Author

github-changelog-generator has been further developed in the last year, and so I want to resurrect this task. There's a variety of options to use issue/pr tags to improve the results, so I'm going to try it out on a branch and see what results I can get nowadays.

I'm keen to get the changelog working since we're going to be doing more unusual things - changing the database schema, moving to mapnik 3, etc over the next few months.

@skywinder
Copy link

@gravitystorm feel free to ask me, if you need any help with this tool.

@gravitystorm gravitystorm mentioned this issue Mar 23, 2016
Closed
@gravitystorm
Copy link
Owner Author

I've pushed an initial version to https://github.com/gravitystorm/openstreetmap-carto/blob/changelog/CHANGELOG.md

I think we can make this work, although there's a few problems with the output that need work:

  • Lots of issue tagging. We have a higher percentage of invalid and wontfix issues than most projects, so we need to go and tag everything. For this reason, I've set the config to only go back a handful of versions (since v2.36.0) otherwise it'll take months to tag everything
  • We might need to create release milestones to get PRs to appear in the correct releases. Needs more investigation
  • There's a bunch of stuff that appears in the v2.37.0 section, that needs sorting out.

My next work is going through each of the entries in the changelog. If there's an incorrect entry then either:

  • tag the issue/PR accordingly (e.g. wontfix, invalid)
  • change the config
  • report a bug upstream :-P

Help is welcome in going through the changelog. When we're happy with our setup, we can merge into master.

@matkoniecz
Copy link
Contributor

We have a higher percentage of invalid and wontfix issues than most projects, so we need to go and tag everything

There is also one social problem. wontfix is rather about a real problem that is unfixable/not worth fixing (like #934). Tagging feature requests as invalid will be inflammatory and encourage irritation (nobody like to see rejection of their proposal, adding "invalid" tag on top will make it even worse).

I propose to keep "invalid" label for something that makes absolutely no sense to appear here - as it applies to other projects, is caused by invalid data (like #2079, #1887).

Maybe create a new label "rejected"/"refused"? Note, I am not a native speaker and it may be purely my personal preference to see "rejected" as gentler than "invalid".

@matthijsmelissen
Copy link
Collaborator

Maybe create a new label "rejected"/"refused"? Note, I am not a native speaker and it may be purely my personal preference to see "rejected" as gentler than "invalid".

Do you have an example of a closed issue that should be neither wontfix nor invalid accoridng to you?

@matkoniecz
Copy link
Contributor

I would not expect #2064 to be tagged as wontfix. For me "wontfix" means that there is some problem that will not be fixed.

Though I see nothing wrong in using it for rejected feature requests - difference between "there is a real problem here but it will not be fixed" and "it will not be fixed as it is not fixable - maybe for technical reasons, maybe because there is no problem in the first place" is not significant.

@gravitystorm
Copy link
Owner Author

I'm interested in coming up with better tags to describe the different situations. I agree that wontfix is not a good tag in many situations. It has connotations that there is indeed something that is "broken" and needs "fixing" and that we're refusing to do it.

#2077 - wontfix isn't right here since it's a new feature request (nothing was broken so nothing needs fixing). declined is a polite option, probably better than refused.

@matkoniecz
Copy link
Contributor

BTW, it may labelling easier to use also "enhancement" label for accepted issues that need/needed fixing. This way https://github.com/gravitystorm/openstreetmap-carto/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aclosed+-label%3Aenhancement+-label%3Aduplicate+-label%3Awontfix+-label%3Ainvalid+-label%3Abug+-label%3Adeclined+ will display only issues that need additional labels.

@gravitystorm
Copy link
Owner Author

Thanks @matkoniecz for all the issue labelling - I've updated the changelog today and a lot of things have disappeared.

I've also added the "declined" label as an alternative to "wontfix", and there's support for this label in the config file.

Finally, I've found github-changelog-generator/github-changelog-generator#304 which is the same problem that we're having, with everything appearing in the v2.37.0 entry

@pnorman
Copy link
Collaborator

pnorman commented Aug 30, 2016

I compiled a list of previous release notes

@magol
Copy link

magol commented Aug 30, 2016 •
edited
Loading

I do absolutely understand why to automatically generate a change log. But as some already said, I feel that a manual change log is significantly better. A changelog should be at a significantly higher level than at PR level. Often, it is many commits and PR per change.

Read more on http://keepachangelog.com/

@olivierlacan

@pnorman pnorman self-assigned this Sep 5, 2016
@pnorman pnorman mentioned this issue Sep 5, 2016
Merged
pnorman referenced this issue in openstreetmap/iD May 9, 2017
@bhousel
Friendlier CHANGELOG format, linkify issues and names
4f3f27e
@HolgerJeromin
Copy link
Contributor

Just for your information: https://www.conventionalcommits.org

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

@gravitystorm gravitystorm

@pnorman pnorman

Labels
general
Projects
None yet
Milestone
Bugs and improvements
Development

No branches or pull requests
8 participants
@gravitystorm @magol @matkoniecz @pnorman @HolgerJeromin @skywinder @matthijsmelissen @mboeringa