Bit of a PITA to repeat the information in every PR in a release note for that PR as well. The automation tools in IPython for this work well there and in statsmodels. Would be nice to consider adding these to pandas.
https://github.com/ipython/ipython/blob/master/tools/gh_api.py https://github.com/ipython/ipython/blob/master/tools/github_stats.py
Comment From: ghost
Yes, you've mentioned these before. I'm sure they're useful.
The release notes aren't just a list of commits though. Sometimes the commit message isn't sufficient and it takes 2 sentences rather then one. Sometimes even an example is required. It also keeps the release notes current continuously.
I also sometimes push commits directly to master rather then via a PR, though maybe I shouldn't.
Comment From: jseabold
Yes, I put it here rather than on that PR (again), so I don't have to mention it anymore.
The main reason for doing this is to take advantage of git and not have to repeat yourself, since it provides most of the tools you need, and can actually force you to follow a maintenance workflow (Fernando convinced us of this and his messages are on MLs, so I won't repeat.)
These tools produce some autogenerated content that you can source in your hand-written release notes, which would contain information about things that really should be highlighted with examples and more information. The automated stuff is good for small enhancements and bug fixes mostly
When merging PRs, the onus would be on the maintainer who does the merge (and reviews and understands the code) to provide a useful merge commit message with the understanding that it will go into the overview automatic release documentation and keep the git log nice. There's also a link automatically to the merge commit / PR and the docs.
People on the bleeding edge can always click on the milestone and closed PRs on github to see if they want to upgrade, but yes you'll lose some of the continual updates unless you make a cron job to run this or something, but you'd still have the big highlights in the handmade release notes.
Comment From: ghost
That means either: - Seperating release notes into an auto-generated list and a more expository document to accompany - Giving up the continous changelog (git log does give you that in a sense) or regenerating the list after each PR. - or adding more logic to the scripts so we can refresh a changelog without clobbering existing manual additions.
I agree that the majority of commits end up with a release note that's not fundamentally different then a git log entry. and that could be automated.
From experience, documenting as you go ends up producing more detailed logs, so while that extra step for each PR is annoying (and bugging contributors for it is tiresome), the resulting changelogs have ended up much richer overall because of the habit.
Comment From: jreback
I think the release notes make a nice document of categorized changes (rather than a straight up log)
you could prob do this in an automated fashion based on how (sometimes) commits are tagged (eg ENH, BUG)
on a single commit pr I use the same message (in release notes and commit)
but on a multi commit or it is just a summary for release notes
I know it's a pain to keep bugging people (sorry @jseabold)
Comment From: jreback
one more thought
we can use the git merge button if it's s straightforward pr
since we do a lot if merging it's just easier (that manually merging)
Comment From: jtratner
What if we added a make command that added most recent commit message to correct release notes? (and maybe figured out correct section).
Comment From: jreback
+1 in that
Comment From: ghost
So after every PR merge we need to pull, run, add, commit and push? that's not less work for maintainers. It can only be run after the PR is opened (to get the issue number), and you'd have to call in to GH api to get the issue number based on the branch. Depending on how it works, you may end up with conflicts when PRs sit in the queue for a while.
Not convinced we'd be better off.
Deciding that one part of the release notes is hand written, for PRs that it makes sense for and we just generate a seperate list of everything based on git log right before tagging a release would be workable though.
Comment From: jtratner
PR author does it.
Comment From: ghost
Ok. But that's something different from what @jseabold suggested and won't eliminate the back-and-forth.
Comment From: jseabold
Here's what I'm proposing. - Every change goes through a PR. No pushing to master, so everything ends up in the full change log. - The PR author only needs to touch release notes for substantial changes. - The person who merges essentially makes the change log through adding a useful summary in the merge commit messages (no fast-forward merges).
The richness and completeness of the change log is unaffected. The only difference is that you have a main release notes page with everything users really care about that contains a link to the full changes with all of the little niggly changes and minor bug-fixes. (Or you could just use an include directive to keep it on the same page).
You could keep a continuous change log or not.
Why it's not a big deal to lose it: this is what git log is for so why duplicate it? People that are thinking about upgrading to the bleeding edge are already comfortable with git. Plus now the merge commits are all there in the log and can be reviewed and the big changes are in the online docs.
To keep it: if you want to keep them, then you add a call to the docs generation in the same thing that pushes the nightly doc builds. And have an include directive in the manual docs. No clobbering involved.
Comment From: jseabold
For example
http://ipython.org/ipython-doc/stable/whatsnew/version1.0.html
which contains a link to
http://ipython.org/ipython-doc/stable/whatsnew/github-stats-1.0.html#issues-list-100
Comment From: jreback
http://pandas.pydata.org/pandas-docs/dev/whatsnew.html#v0-13-0-january-3-2014
links to this (mainly for the bugfix section):
http://pandas.pydata.org/pandas-docs/dev/release.html#pandas-0-13-0
Comment From: jtratner
That IPython auto doc does look nice...
Comment From: jorisvandenbossche
I am going to close this for now (too many open issues :-)). For now I think we are fine with the current approach of not automating, but we can always reopen if someone wants to bring this up again