[Matplotlib-devel] Using towncrier to generate changelogs

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

[Matplotlib-devel] Using towncrier to generate changelogs

dstansby
Dear all,

I am proposing to change up how Matplotlib's API changes/what's new pages are generated, in particular moving to using towncrier to add more automation to the process. This is motivated by the crazy amount of time it took me to combine all the API change and what's new fragments into a coherent page for the 3.1.0 release.

The PR to change this process is here: https://github.com/matplotlib/matplotlib/pull/14589 The new process would be
  • When a new feature or api change or code removal is implemented, add a changelog file to the changelog/ folder
  • The changelog file should be named <PR number>.<type>.rst, and should contain a single sentence or paragraph describing the change. <type> is the type of change, ie. api_change, new_feature or removal
  • towncrier can then automatically collate these fragments into a single .rst page, which can be manually edited if needed before releasing
I think this will significnatly reduce the burden of producing what's new pages each release, without adding any extra burden on those writing the what's new entries.

Please take a look at the PR and leave comments/questions/suggestions! In particular, feedback on what "types" of changelog entry to include would be very welcome.

All the best,
David



_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Using towncrier to generate changelogs

tcaswell
I think this is a great idea, however I am a bit concerned about "should contain a single sentence or paragraph describing the change".  Does this mean we can not include plot directives it the what_new?

Tom

On Tue, Jun 25, 2019 at 1:45 PM David Stansby <[hidden email]> wrote:
Dear all,

I am proposing to change up how Matplotlib's API changes/what's new pages are generated, in particular moving to using towncrier to add more automation to the process. This is motivated by the crazy amount of time it took me to combine all the API change and what's new fragments into a coherent page for the 3.1.0 release.

The PR to change this process is here: https://github.com/matplotlib/matplotlib/pull/14589 The new process would be
  • When a new feature or api change or code removal is implemented, add a changelog file to the changelog/ folder
  • The changelog file should be named <PR number>.<type>.rst, and should contain a single sentence or paragraph describing the change. <type> is the type of change, ie. api_change, new_feature or removal
  • towncrier can then automatically collate these fragments into a single .rst page, which can be manually edited if needed before releasing
I think this will significnatly reduce the burden of producing what's new pages each release, without adding any extra burden on those writing the what's new entries.

Please take a look at the PR and leave comments/questions/suggestions! In particular, feedback on what "types" of changelog entry to include would be very welcome.

All the best,
David


_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel


--
Thomas Caswell
[hidden email]

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel
Reply | Threaded
Open this post in threaded view
|

Re: Using towncrier to generate changelogs

dstansby
I don't think this should be an issue - towncrier just reflows .rst fragments in individual files into a complete list when it's run. Worst case, it is possible to edit the final changelog file that is generated before pushing it.

Thinking about this a bit, maybe it would be better anyway (from a maintainability and discoverability point of view) to have examples showing off new features get a new examples gallery entry instead of a plot directive snippet on the what's new page.

David

On Wed, 10 Jul 2019 at 07:35, Thomas Caswell <[hidden email]> wrote:
I think this is a great idea, however I am a bit concerned about "should contain a single sentence or paragraph describing the change".  Does this mean we can not include plot directives it the what_new?

Tom

On Tue, Jun 25, 2019 at 1:45 PM David Stansby <[hidden email]> wrote:
Dear all,

I am proposing to change up how Matplotlib's API changes/what's new pages are generated, in particular moving to using towncrier to add more automation to the process. This is motivated by the crazy amount of time it took me to combine all the API change and what's new fragments into a coherent page for the 3.1.0 release.

The PR to change this process is here: https://github.com/matplotlib/matplotlib/pull/14589 The new process would be
  • When a new feature or api change or code removal is implemented, add a changelog file to the changelog/ folder
  • The changelog file should be named <PR number>.<type>.rst, and should contain a single sentence or paragraph describing the change. <type> is the type of change, ie. api_change, new_feature or removal
  • towncrier can then automatically collate these fragments into a single .rst page, which can be manually edited if needed before releasing
I think this will significnatly reduce the burden of producing what's new pages each release, without adding any extra burden on those writing the what's new entries.

Please take a look at the PR and leave comments/questions/suggestions! In particular, feedback on what "types" of changelog entry to include would be very welcome.

All the best,
David


_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel


--
Thomas Caswell
[hidden email]

_______________________________________________
Matplotlib-devel mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/matplotlib-devel