Release notes in the wiki vs with the source

[Jason Moore]

We keep track of our release notes on the wiki. To me, it seems like these should be in a file included with the source code so it always travels with the git repo and our source distributions. It would also be nice if every pull request with significant changes had to include a change to the changelog file. A check to see if the changelog file was modified in a PR could be done on with travis too.

Are there reasons that the wiki is preferred?

Jason
moorepants.info
+01 530-601-9791

[Sergey Kirpichev]

See this thread:
https://groups.google.com/d/msg/sympy/qkP3WAuWwbc/k3mi2NDea9MJ

In my view, we should adopt some tagging for merge commits (e.g. with pr headers).  This
can help us with automatic generation of the release notes.  Something like the scipy project.

Take for example our last release notes or scipy's doc/release/0.15.0-notes.rst.  Both have:
1) new features
2) bugfixes
3) deprecations
4) backward-incompatible changes
We should divide our pr's to such or similar categories.

Also, list of closed issues in the given release - great feature for next changelog.

Automatic generation of the release notes will be trivial if we adopt the above
mentioned tagging and this syntax for closing issues:
https://help.github.com/articles/closing-issues-via-commit-messages/

Sure, it will require a manual intervention from the release manager, but others can help.

We can add old release notes retroactively (at least, for the
code history in our git tree).

[Aaron Meurer]

One issue with shipping the changelog in the source is that it will
tend to always be in a state of merge conflict.

Regarding an issue list in the change log, I've always found the
hand-written changelogs to be better for human consumption.
Automatically generated changelogs are not really readable, as all
issues are presented equally, and without the proper context to the
intended audience.

I'm not opposed to adding them (it should be quite easy to generate
such a list), but it should be as a footnote to the existing release
notes, not a replacement.

Aaron Meurer

> --
> You received this message because you are subscribed to the Google Groups
> "sympy" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to sympy+un...@googlegroups.com.
> To post to this group, send email to sy...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sympy.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/sympy/d9d4490b-a339-484a-bbfb-16c24d3e46e1%40googlegroups.com.
>
> For more options, visit https://groups.google.com/d/optout.

[Matthew Brett]

On Fri, Nov 21, 2014 at 8:56 AM, Aaron Meurer <asme...@gmail.com> wrote:
> One issue with shipping the changelog in the source is that it will
> tend to always be in a state of merge conflict.

IPython solves this by collecting items that will eventually go in the
changelog in a directory of separate files:

https://github.com/ipython/ipython/blob/master/docs/source/whatsnew/pr/README.md

Matthew

[Sergey B Kirpichev]

On Fri, Nov 21, 2014 at 10:56:01AM -0600, Aaron Meurer wrote:
> One issue with shipping the changelog in the source is that it will
> tend to always be in a state of merge conflict.

How it's possible with my suggestions above? New changelog
appears only when you start the release branch.

> Regarding an issue list in the change log, I've always found the
> hand-written changelogs to be better for human consumption.

Sure. But it's better to start from some autogenerated
changelog, not from zero. And to minimize editing efforts for
release manager(s) - we can adopt some policy for merge commits.

[Joachim Durchholz]

+1 for that approach.

[Jason Moore]

Yes, the IPython approach seems nice. I'd be willing to set it up if others would want it.

Jason
moorepants.info
+01 530-601-9791

--
You received this message because you are subscribed to the Google Groups "sympy" group.

To unsubscribe from this group and stop receiving emails from it, send an email to sympy+unsubscribe@googlegroups.com.

To post to this group, send email to sy...@googlegroups.com.
Visit this group at http://groups.google.com/group/sympy.

To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/54700B76.4010803%40durchholz.org.

[Aaron Meurer]

I still prefer having the release notes in the wiki. It makes it
easier for people to change them (they don't have to fiddle with pull
requests, and it's already hard enough to get people to update them).
What are the benefits of having them in the main repo? Note that the
wiki is under revision control (git clone
g...@github.com:sympy/sympy.wiki.git).

Aaron Meurer

On Sat, Nov 22, 2014 at 12:02 AM, Jason Moore <moore...@gmail.com> wrote:
> Yes, the IPython approach seems nice. I'd be willing to set it up if others
> would want it.
>
>
> Jason
> moorepants.info
> +01 530-601-9791
>
> On Fri, Nov 21, 2014 at 11:05 PM, Joachim Durchholz <j...@durchholz.org>
> wrote:
>>
>> Am 21.11.2014 um 19:02 schrieb Matthew Brett:
>>>
>>> On Fri, Nov 21, 2014 at 8:56 AM, Aaron Meurer <asme...@gmail.com> wrote:
>>>>
>>>> One issue with shipping the changelog in the source is that it will
>>>> tend to always be in a state of merge conflict.
>>>
>>>
>>> IPython solves this by collecting items that will eventually go in the
>>> changelog in a directory of separate files:
>>>
>>>
>>> https://github.com/ipython/ipython/blob/master/docs/source/whatsnew/pr/README.md
>>
>>
>> +1 for that approach.
>>
>> --
>> You received this message because you are subscribed to the Google Groups
>> "sympy" group.
>> To unsubscribe from this group and stop receiving emails from it, send an

>> email to sympy+un...@googlegroups.com.

>> To post to this group, send email to sy...@googlegroups.com.
>> Visit this group at http://groups.google.com/group/sympy.
>> To view this discussion on the web visit
>> https://groups.google.com/d/msgid/sympy/54700B76.4010803%40durchholz.org.
>>
>> For more options, visit https://groups.google.com/d/optout.
>
>

> --
> You received this message because you are subscribed to the Google Groups
> "sympy" group.
> To unsubscribe from this group and stop receiving emails from it, send an

> email to sympy+un...@googlegroups.com.

> To post to this group, send email to sy...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sympy.
> To view this discussion on the web visit

> https://groups.google.com/d/msgid/sympy/CAP7f1AhhE2Z%2B5dHHd%2BT-T8ZuSgWARxDFJC%3DpnEVQy2fXS766bg%40mail.gmail.com.

[Matthew Brett]

On Sat, Nov 22, 2014 at 12:24 PM, Aaron Meurer <asme...@gmail.com> wrote:
> I still prefer having the release notes in the wiki. It makes it
> easier for people to change them (they don't have to fiddle with pull
> requests, and it's already hard enough to get people to update them).
> What are the benefits of having them in the main repo? Note that the
> wiki is under revision control (git clone
> g...@github.com:sympy/sympy.wiki.git).

I'm not up to date on the IPython workflow, but I think the advantage
of their system is that contributors can fill out the release notes as
part of their PRs, and maintainers can ask for this as part of review,
as in 'thanks for the feature X, would you mind writing a section for
the changelog in doc/source/whatsnew/pr'. Obviously contributors
could also do that in the wiki, but that's another place and interface
for contributor and reviewer.

Matthew

[Jason Moore]

I'm proposing two things:

1. We maintain the release notes within the source code repository.

2. We institute methods requiring change log notes to be included with each PR (minor things can be exceptions with "minor" being subjective).

Here are my reasons for both:

1. When dealing with dependency hell issues in software development having the release notes within the tarball or git repo is very helpful, as opposed to searching around online documentation or google searching. Most other software projects distribute their release notes with the source. To me, it seems like that is the status quo. The release notes are part of the documentation and we keep the docs with the source. It seems odd to be separate if it is a part of the documentation. We already pretty much require people to submit Github PRs for changing the source code and documentation yet we send them to the wiki for the releases notes. If it was part of the source repo, then only one mechanism is needed for all changes to source/docs.

2. Other packages in the scipy sphere seem to do a better job at release notes than us. For example, Pandas really stands out to me. A combination of automated listing of merged PRs and closed issues with manually written notes would be ideal. This would help give us superb information for end users on changes and backwards incompatible breaks, etc. I don't see any reason why our release notes shouldn't have information regarding each change to the code base except that is takes more work for each contributor.* If we had a rule that significant PRs can't be merged without adding release notes we wouldn't have to spend time figuring out what is missing when we want to do a release.

We also merge many PRs with no updates to the online documentation. I hate to suggest creating barriers to contribution but it is usually regarded that documentation makes or breaks a project. I think we can stand to have higher standards for our contributions. Each PR should include adequate docs, including the online docs and release notes. We could start with the release notes and see how it goes.

*Being more strict about commit messages and rebasing tons of tiny commits into bigger commits with nice commit messages could help here too. Certainly for nice automated messages.

Jason
moorepants.info
+01 530-601-9791

--
You received this message because you are subscribed to the Google Groups "sympy" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sympy+un...@googlegroups.com.
To post to this group, send email to sy...@googlegroups.com.
Visit this group at http://groups.google.com/group/sympy.

To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAH6Pt5rJJbU485C4NJ7rJb-Jboy4tKe%2BxFgkx76ccoPa-4uFaw%40mail.gmail.com.

[Sergey B Kirpichev]

On Sat, Nov 22, 2014 at 02:24:05PM -0600, Aaron Meurer wrote:
> I still prefer having the release notes in the wiki. It makes it
> easier for people to change them

Unfortunately, this doesn't work:
#2782 - not mentioned
#2927 - fixes #7145
#7300 - small change, but...
#2992 - two bug fixed
#7296 - not mentioned

Just five lines from
git log --merges sympy-0.7.5..sympy-0.7.6 --oneline

> What are the benefits of having them in the main repo? Note that the
> wiki is under revision control (git clone
> g...@github.com:sympy/sympy.wiki.git).

1) No omissions and (hopefully) less mistakes (due to automation)
2) Less work.
3) People expect this (see other projects on scipy.org, or
python.org - "what's new" is a part of the documentation).
4) Distibutions expect this (e.g. Debian has lintian warning about
missing upstream changelog file).

The price is low: instead of just pushing commit button -
committer should add a human-readable note and some labels.

Another variant - we could gather changelog entry from the PR
description. It's editable in any time by PR author or any
collaborator.

Scripting all this should be trivial.

[Aaron Meurer]

If I'm not mistaken, both Python and scipy keep their docs in a separate repo.

Another challenge with our release notes is that we tend to have a
*lot* of changes per release, thanks to both the rate at which we
release, and the large amount of code we have coming in from GSoC
(plus a lot of smaller contributions from various people). The release
notes should do a good job of summarizing the high-level changes for
the release as well as list all changes for anyone who's interested.

I do agree that our release notes should be improved. I'm just not
convinced that moving them to the source would solve that.

Aaron Meurer

> --
> You received this message because you are subscribed to the Google Groups "sympy" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sympy+un...@googlegroups.com.
> To post to this group, send email to sy...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sympy.

> To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/20141122224034.GA1943%40darkstar.order.hcn-strela.ru.

[Sergey B Kirpichev]

On Sat, Nov 22, 2014 at 06:25:19PM -0600, Aaron Meurer wrote:
> If I'm not mistaken, both Python and scipy keep their docs in a separate repo.

$ ls -lR ~/src/cpython/Doc/whatsnew/changelog.rst
-rw-r----- 1 sk sk 62 Jan 13 2014
/home/sk/src/cpython/Doc/whatsnew/changelog.rst
$ ls -l ~/src/scipy/doc/release/0.15.0-notes.rst
-rw-r----- 1 sk sk 4,0K Sep 10 17:31
/home/sk/src/scipy/doc/release/0.15.0-notes.rst

> I do agree that our release notes should be improved. I'm just not
> convinced that moving them to the source would solve that.

How exactly you suggest to improve this process (i.e. release
notes writting)? It's clear that the current way doesn't work.

[Jason Moore]

Scipy release notes are in the source too: https://github.com/scipy/scipy/tree/master/doc/release

Jason
moorepants.info
+01 530-601-9791

--
You received this message because you are subscribed to the Google Groups "sympy" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sympy+un...@googlegroups.com.
To post to this group, send email to sy...@googlegroups.com.
Visit this group at http://groups.google.com/group/sympy.

To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/20141123132304.GA25042%40darkstar.order.hcn-strela.ru.