Using towncrier to generate changelogs

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
<https://github.com/hawkowl/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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20190625/c6699702/attachment.html>

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 <dstansby at gmail.com> 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
<https://github.com/hawkowl/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
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel

--
Thomas Caswell
tcaswell at gmail.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20190710/6f100b78/attachment.html>

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 <tcaswell at gmail.com> 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 <dstansby at gmail.com> 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
<https://github.com/hawkowl/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
Matplotlib-devel at python.org
https://mail.python.org/mailman/listinfo/matplotlib-devel

--
Thomas Caswell
tcaswell at gmail.com

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/matplotlib-devel/attachments/20190715/1e94549d/attachment.html>