Updating SymPy changelog process
70 views
Skip to first unread message
Aaron Meurer
Jun 22, 2017, 4:18:04 PM6/22/17
to sy...@googlegroups.com
Once I have finished the SymPy release, I would like to make an update
to how we do changelogs.
Right now, changelog entries are made manually on the wiki, at
https://github.com/sympy/sympy/wiki/Release-Notes. The issue with this
is that very few people update the release notes when pull request
changes are made, so we end up with a long list of changes that need
to be added to the release notes at release time. This results in the
release notes generally not being done very well, because there are
typically too many changes to reasonably go through and add to the
notes.
My suggestion is to require each pull request to add its own release
notes entry as part of the PR. The PR won't be mergeable unless it has
a release notes entry.
The way to achieve this is to move the release notes from the wiki to
the main SymPy repo. The process that seems to work well is this:
- There is a directory changelog/ in the repo. Every pull request adds
a new file to this directory. The name of the file does not matter (a
good convention is branchname.rst). This file follows a template
format, like
**Backwards incompatible changes:**
...
**Major changes:**
...
**Minor changes:**
...
(the header names could be different). Each PR adds bullet points for
the changes made in that PR.
Then at release time, the release script takes all the files in
changelog.rst and amalgamates them into a single changelog file for
that release.
The separate files makes it so that there are never git merge
conflicts (so long as people chose unique filenames).
Each pull request would have a check in the tests to make sure that it
adds or modifies a changelog file. There could also be some way to
tell the tests that the change is too minor to require a changelog
entry (say, if it has "SKIP CHANGELOG" in the PR text).
This process was suggested to me by Anthony Scopatz, who uses it in
Xonsh https://github.com/xonsh/xonsh/blob/master/CONTRIBUTING.rst#changelog.
I would appreciate any thoughts or suggestions on this. It will likely
not be implemented until after the release.
Aaron Meurer
to how we do changelogs.
Right now, changelog entries are made manually on the wiki, at
https://github.com/sympy/sympy/wiki/Release-Notes. The issue with this
is that very few people update the release notes when pull request
changes are made, so we end up with a long list of changes that need
to be added to the release notes at release time. This results in the
release notes generally not being done very well, because there are
typically too many changes to reasonably go through and add to the
notes.
My suggestion is to require each pull request to add its own release
notes entry as part of the PR. The PR won't be mergeable unless it has
a release notes entry.
The way to achieve this is to move the release notes from the wiki to
the main SymPy repo. The process that seems to work well is this:
- There is a directory changelog/ in the repo. Every pull request adds
a new file to this directory. The name of the file does not matter (a
good convention is branchname.rst). This file follows a template
format, like
**Backwards incompatible changes:**
...
**Major changes:**
...
**Minor changes:**
...
(the header names could be different). Each PR adds bullet points for
the changes made in that PR.
Then at release time, the release script takes all the files in
changelog.rst and amalgamates them into a single changelog file for
that release.
The separate files makes it so that there are never git merge
conflicts (so long as people chose unique filenames).
Each pull request would have a check in the tests to make sure that it
adds or modifies a changelog file. There could also be some way to
tell the tests that the change is too minor to require a changelog
entry (say, if it has "SKIP CHANGELOG" in the PR text).
This process was suggested to me by Anthony Scopatz, who uses it in
Xonsh https://github.com/xonsh/xonsh/blob/master/CONTRIBUTING.rst#changelog.
I would appreciate any thoughts or suggestions on this. It will likely
not be implemented until after the release.
Aaron Meurer
Jason Moore
Jun 22, 2017, 4:20:15 PM6/22/17
to sy...@googlegroups.com
I fully support this!
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+unsubscribe@googlegroups.com.
To post to this group, send email to sy...@googlegroups.com.
Visit this group at https://groups.google.com/group/sympy.
To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAKgW%3D6JnXOn7A%2B-J%2BMWRyg05CP05rq%2BzCJ719V2B9OaE5AyePw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
Anthony Scopatz
Jun 22, 2017, 4:20:47 PM6/22/17
to sy...@googlegroups.com
Hi All,
I'd like to say that for xonsh we find this strategy incredibly useful. This was inspired originally by http://keepachangelog.com/en/1.0.0/
Let me know if you need any clarifications.
Be Well
Anthony
--
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 https://groups.google.com/group/sympy.
To view this discussion on the web visit https://groups.google.com/d/msgid/sympy/CAKgW%3D6JnXOn7A%2B-J%2BMWRyg05CP05rq%2BzCJ719V2B9OaE5AyePw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.
--
Asst. Prof. Anthony Scopatz
Nuclear Engineering Program
Mechanical Engineering Dept.
University of South Carolina
sco...@cec.sc.edu
Office: (803) 777-9334
Cell: (512) 827-8239
Office: Horizon 1, #011 (ground floor, not first)
Book a meeting with me at https://scopatz.youcanbook.me/
Open up an issue: https://github.com/scopatz/me/issues
Check my calendar
Amit Kumar
Jun 23, 2017, 7:28:36 AM6/23/17
to sympy
+1
Gaurav Dhingra
Oct 23, 2017, 12:35:56 PM10/23/17
to sympy
Currently we are not following this. Neither have the release notes been formed, what I say is we change the "Pull Request Template" to this https://github.com/scikit-learn/scikit-learn/blob/master/PULL_REQUEST_TEMPLATE.md from which we use for the section of 'What does this PR implement/fix? Explain your changes' could be used to add a 'release note entry'.
---
Gaurav Dhingra
On Friday, June 23, 2017 at 1:48:04 AM UTC+5:30, Aaron Meurer wrote:
Aaron Meurer
Oct 23, 2017, 2:43:51 PM10/23/17
to sy...@googlegroups.com
The ideas discussed here still need to be implemented. Unfortunately,
I haven't had the time to do it, but maybe someone else can.
The idea is to have something completely automated, which means that
the CI tests will fail if there isn't a changelog entry. Doing this on
the pull request itself is an interesting idea. If we had some tooling
around it, I think it could work. However, without tooling, it's not
much better than what we have now, because the release notes still
have to be amalgamated manually.
Aaron Meurer
I haven't had the time to do it, but maybe someone else can.
The idea is to have something completely automated, which means that
the CI tests will fail if there isn't a changelog entry. Doing this on
the pull request itself is an interesting idea. If we had some tooling
around it, I think it could work. However, without tooling, it's not
much better than what we have now, because the release notes still
have to be amalgamated manually.
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 https://groups.google.com/group/sympy.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/sympy/3315ac08-22bf-434a-aa08-77040911755a%40googlegroups.com.
> 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 https://groups.google.com/group/sympy.
> To view this discussion on the web visit
Reply all
Reply to author
Forward
0 new messages