Release changelog 5.4 #876

MSeal · 2018-09-05T19:58:00Z

Changelog improvements for release. We added a few missing additions from the release PR #869 and are working to describe the major changes more in-depth. This will be the contents of the google group email as well.

Added a few reviewers because there's some some limitations on bandwidth for reviewing and getting it finalized.

MSeal · 2018-09-05T22:31:53Z

Could use some eyes on the descriptions before final release cut.

SylvainCorlay

Just went through it and caught a few typos.

I may be mistaken in some cases since I am not a native speaker as you know.

SylvainCorlay · 2018-09-05T23:08:08Z

docs/source/changelog.rst

+
+There were a few new metadata fields which are now respected in nbconvert.
+
+``nb.metadata.authors`` metadata attribute will be respected in latex exports. Multiple authers will be added with ``,`` separation against their names.


typo authers -> authors

SylvainCorlay · 2018-09-05T23:08:53Z

docs/source/changelog.rst

+
+``nb.metadata.title`` will be respected ahead of ``nb.metadata.name`` for title assignment. This better matches with the notebook format.
+
+``nb.metadata.filename`` will override the default output_filename_template when extracting notebook resources in the ``ExtractOutputPreprocessor``. Helpful for when you want to consistently fix to a particular output filename, espcially when you need to set image filenames for your exports.


(It is) - helpful?

SylvainCorlay · 2018-09-05T23:09:10Z

docs/source/changelog.rst

+
+``nb.metadata.filename`` will override the default output_filename_template when extracting notebook resources in the ``ExtractOutputPreprocessor``. Helpful for when you want to consistently fix to a particular output filename, espcially when you need to set image filenames for your exports.
+
+The ``raises-exception`` cell tag (``nb.cells[].metadata.tags[raises-exception]``), or ``nb.metadata.allow_errors`` for all ells, now allows for cell exceptions to not halt execution as respected in nbval and other notebook interfaces. This feature is toggleable with the ``force_raise_errors`` configuration option.


for all ells -> for all cells.

as respected -> like?

SylvainCorlay · 2018-09-05T23:10:17Z

docs/source/changelog.rst

+The ``raises-exception`` cell tag (``nb.cells[].metadata.tags[raises-exception]``), or ``nb.metadata.allow_errors`` for all ells, now allows for cell exceptions to not halt execution as respected in nbval and other notebook interfaces. This feature is toggleable with the ``force_raise_errors`` configuration option.
+Errors from executing the notebook can be allowed with a ``raises-exception`` tag on a single cell, or the ``allow_errors`` configurable option for all cells. An allowed error will be recorded in notebook output, and execution will continue.
+If an error occurs when it is not explicitly allowed, a ``CellExecutionError`` will be raised.
+If ``force_raise_errors`` is True, ``CellExecutionError`` will be raised for any error that occurs while executing the notebook. This overrides both the ``allow_errors`` option and the `raises-exception` cell tag.


MSeal · 2018-09-05T23:15:48Z

Uhh, no your English is good and most of those need fixing. I didn't review this closely enough and/or copied from docs in the code and forgot my editor was not syntax highlighting issues. Thanks for the typo check!

mpacer · 2018-09-06T00:03:10Z

So I think we should revisit the content around the Execute Preprocessor to focus on how it has been improved in a number of ways; including the introduction of configurable kernel managers even though they are just a tiny part of the story. I'll attempt that.

MSeal · 2018-09-06T00:30:28Z

Thanks M. As an FYI if we don't have the documentation all set by tomorrow morning I won't be able to do the release until Tuesday (or someone else will need to do it).

blink1073 · 2018-09-06T00:31:08Z

Looking at this now. Happy to be the one to get it out the door if need be.

blink1073 · 2018-09-06T00:32:49Z

docs/source/changelog.rst

+
+``nb.metadata.title`` will be respected ahead of ``nb.metadata.name`` for title assignment. This better matches with the notebook format.
+
+``nb.metadata.filename`` will override the default output_filename_template when extracting notebook resources in the ``ExtractOutputPreprocessor``. The attribute is helpful for when you want to consistently fix to a particular output filename, especially when you need to set image filenames for your exports.


Ticks around "output_filename_template"?

blink1073 · 2018-09-06T00:33:32Z

docs/source/changelog.rst

+
+``nb.metadata.filename`` will override the default output_filename_template when extracting notebook resources in the ``ExtractOutputPreprocessor``. The attribute is helpful for when you want to consistently fix to a particular output filename, especially when you need to set image filenames for your exports.
+
+The ``raises-exception`` cell tag (``nb.cells[].metadata.tags[raises-exception]``) allows for cell exceptions to not halt execution. The tag is respected in the same way by nbval and other notebook interfaces. ``nb.metadata.allow_errors`` will apply this rule for all cells. This feature is toggleable with the ``force_raise_errors`` configuration option.


Ticks around "nbval" (or even a link)? https://github.com/computationalmodelling/nbval

blink1073 · 2018-09-06T00:33:56Z

docs/source/changelog.rst

+The ``raises-exception`` cell tag (``nb.cells[].metadata.tags[raises-exception]``) allows for cell exceptions to not halt execution. The tag is respected in the same way by nbval and other notebook interfaces. ``nb.metadata.allow_errors`` will apply this rule for all cells. This feature is toggleable with the ``force_raise_errors`` configuration option.
+Errors from executing the notebook can be allowed with a ``raises-exception`` tag on a single cell, or the ``allow_errors`` configurable option for all cells. An allowed error will be recorded in notebook output, and execution will continue.
+If an error occurs when it is not explicitly allowed, a ``CellExecutionError`` will be raised.
+If ``force_raise_errors`` is True, ``CellExecutionError`` will be raised for any error that occurs while executing the notebook. This overrides both the ``allow_errors`` option and the `raises-exception` cell tags.


Need double ticks for "raises-exception"

blink1073 · 2018-09-06T00:34:25Z

docs/source/changelog.rst

+
+The kernel manager can now be optionally passed into the ``ExecutePreprocessor.preprocess`` and the ``executenb`` functions as the kwarg ``km``. This means that the kernel can be configured as desired before beginning preprocessing.
+
+This is useful for executing in a context where the kernel has external dependencies that need to be set to non-default values. An example of this might be a Spark kernel where you wish to configure the spark cluster location ahead of time without building a new kernel.


Consistent cap case for "Spark"

blink1073 · 2018-09-06T00:34:57Z

docs/source/changelog.rst

+Raw Templates
+++++++++++++
+
+Template exporters can now be assigned raw templates as string attributes by setting the raw_template variable.


Ticks for "raw_template"?

mpacer

A few things need to be clarified — I'll work on the text for that unless you want to make the changes yourself.

mpacer · 2018-09-06T00:41:21Z

docs/source/changelog.rst

+Surfacing exporters in front-ends
+++++++++++++++++++++++++++++++++
+
+Custom exporters are now exposed for front-ends, including classic notebook, to consume. As an example, this means that latex exporter will be made available for latex 'text/latex' mimetype for the Download As interface.


Couple FYIs; I'll make the changes:

The LaTeX exporter isn't a custom exporter — "custom exporter" refers to exporters that aren't included in nbconvert itself.

Exporters can often handle more than just their specific media type (e.g., the LaTeX exporter handles image/png by storing the png data out to a file and then loading it with
\begin{figure} [htb!] \includegraphics{filename.png} … \end{figure}

At least @rgbkrk and I are trying to use the term media type in favour of mimetype as it's more intuitive for lots of people.

mpacer · 2018-09-06T00:43:13Z

docs/source/changelog.rst

+New command line flags
++++++++++++++++++++++
+
+The ``--no-input`` flag will apply metadata changes to input cells to mark them as hidden. This is great for notebooks which generate "reports" where you want the code that was executed to not appear by default.


--no-input doesn't affect notebook metadata, in fact it has no use case if the output is a notebook. It works by filtering out the input blocks inside the templates. I'll make a change to reflect the mechanism.

mpacer · 2018-09-06T00:45:00Z

docs/source/changelog.rst

+
+``nb.metadata.filename`` will override the default output_filename_template when extracting notebook resources in the ``ExtractOutputPreprocessor``. The attribute is helpful for when you want to consistently fix to a particular output filename, especially when you need to set image filenames for your exports.
+
+The ``raises-exception`` cell tag (``nb.cells[].metadata.tags[raises-exception]``) allows for cell exceptions to not halt execution. The tag is respected in the same way by nbval and other notebook interfaces. ``nb.metadata.allow_errors`` will apply this rule for all cells. This feature is toggleable with the ``force_raise_errors`` configuration option.


I think we can include most of the details of this in the refactored section on the ExecutePreprocessor. Since it's the next section, I think it's not too bad to mention that these things exist and link below for more details.

mpacer · 2018-09-06T07:23:30Z

I’ll try to get these changes written up tomorrow at the airport… but I won’t be pushing anything tonight.

Carreau · 2018-09-06T09:08:06Z

I fixed some of the comments (mostly backticks), note that this is "just" a changelog, you do not need to be too precise, and we can still fix the changelog in further minor or patch release.

Carreau · 2018-09-06T09:08:35Z

Also, if you do not feel like making the release because you are busy next week, Let me know and I can try to do it.

mpacer · 2018-09-06T13:23:26Z

I thought the change log notes were supposed to be the basis of the announcement email as well? Those were all things we should have ironed out for the announcement email.

Carreau · 2018-09-06T14:08:35Z

Sure, but changelog and announcement email/blog are (often) a one time thing. They address mostly a subset of the audiance: - general users to be excited about new feature/bugfix - people who want to know what have change quickly to know wether they are affected. Once you read the changelog about a feture/bug/change that affect you, you (often) head to another page/section to get the actual info. So you shouldn't spend an unreasonable amount of time making things too perfect. As you said it is the basis of an announcement. You should not feel bad if it's innacurate or approximatif, toi will ~always find somebody unhappy. You can also see it the following way: if it's not perfect, or could be improved, it's an occasion to tell someone that update to the changelog is an easy and welcome contribution to get them engaged. Hope that make some sens and let you be more relaxed. I'll also leave that here: http://thecodelesscode.com/case/215

…

On Thu, Sep 6, 2018, 15:23 M Pacer ***@***.***> wrote: I thought the change log notes were supposed to be the basis of the announcement email as well? Those were all things we should have ironed out for the announcement email. — You are receiving this because your review was requested. Reply to this email directly, view it on GitHub <#876 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAUezwRNJGiX6O2OOslcn897SobV-7G8ks5uYSHPgaJpZM4Wblwy> .

blink1073 · 2018-09-06T14:13:11Z

Thanks for the link, @Carreau, that was insightful and disheartening 😄

MSeal · 2018-09-06T16:28:27Z

I'm in a agreement with releasing and refining notes later if there's confusion or requests for it. The only piece we are missing is a deeper description of Execute Preprocessor, but I added some note about the subject and encouraged people to read that source code if they want to see more of the changes.

Unless someone wants to halt it I am planning on attempting to run the rest of the release around noon (Pacific time) today.

Carreau · 2018-09-06T17:10:56Z

Unless someone wants to halt it I am planning on attempting to run the rest of the release around noon (Pacific time) today.

I can be around gitter if necessary.

Some fixes have been applied, please re-review, or we can iterate.

MSeal requested review from minrk, Carreau, blink1073 and mpacer September 5, 2018 19:58

MSeal force-pushed the release-changelog-5.4 branch from ac3413d to b4cc829 Compare September 5, 2018 22:34

MSeal and others added 4 commits September 5, 2018 15:34

Updated changelog (need significant changes descriptions)

1272219

fix header levels and add more high level notes

21cfcac

add Comprehensive Notes heading

5e8704c

Added significant changes section details

cff8dae

MSeal force-pushed the release-changelog-5.4 branch from b4cc829 to cff8dae Compare September 5, 2018 22:35

SylvainCorlay reviewed Sep 5, 2018

View reviewed changes

Fixed various typos

80465f3

blink1073 reviewed Sep 6, 2018

View reviewed changes

mpacer previously requested changes Sep 6, 2018

View reviewed changes

some formatting

fb38c77

MSeal added 2 commits September 6, 2018 09:22

Applied feedback to changelog notes

90ae108

Added a note about execute preprocessor improvements

9ddd5fa

Carreau previously approved these changes Sep 6, 2018

View reviewed changes

Carreau removed the request for review from minrk September 6, 2018 17:11

Carreau approved these changes Sep 6, 2018

View reviewed changes

rgbkrk approved these changes Sep 6, 2018

View reviewed changes

blink1073 approved these changes Sep 6, 2018

View reviewed changes

SylvainCorlay approved these changes Sep 6, 2018

View reviewed changes

MSeal merged commit 5ade53d into jupyter:master Sep 6, 2018

MSeal added this to the 5.4 milestone Feb 8, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Release changelog 5.4 #876

Release changelog 5.4 #876

MSeal commented Sep 5, 2018

MSeal commented Sep 5, 2018

SylvainCorlay left a comment

SylvainCorlay Sep 5, 2018

SylvainCorlay Sep 5, 2018

SylvainCorlay Sep 5, 2018

SylvainCorlay Sep 5, 2018

SylvainCorlay Sep 5, 2018

MSeal commented Sep 5, 2018

mpacer commented Sep 6, 2018 •

edited

Loading

MSeal commented Sep 6, 2018

blink1073 commented Sep 6, 2018

blink1073 Sep 6, 2018

blink1073 Sep 6, 2018

blink1073 Sep 6, 2018

blink1073 Sep 6, 2018

blink1073 Sep 6, 2018

mpacer left a comment

mpacer Sep 6, 2018

mpacer Sep 6, 2018

mpacer Sep 6, 2018

mpacer commented Sep 6, 2018

Carreau commented Sep 6, 2018

Carreau commented Sep 6, 2018 •

edited

Loading

mpacer commented Sep 6, 2018

Carreau commented Sep 6, 2018 via email

blink1073 commented Sep 6, 2018

MSeal commented Sep 6, 2018

Carreau commented Sep 6, 2018


		There were a few new metadata fields which are now respected in nbconvert.

		``nb.metadata.authors`` metadata attribute will be respected in latex exports. Multiple authers will be added with ``,`` separation against their names.


		``nb.metadata.title`` will be respected ahead of ``nb.metadata.name`` for title assignment. This better matches with the notebook format.

		``nb.metadata.filename`` will override the default output_filename_template when extracting notebook resources in the ``ExtractOutputPreprocessor``. Helpful for when you want to consistently fix to a particular output filename, espcially when you need to set image filenames for your exports.


		``nb.metadata.filename`` will override the default output_filename_template when extracting notebook resources in the ``ExtractOutputPreprocessor``. Helpful for when you want to consistently fix to a particular output filename, espcially when you need to set image filenames for your exports.

		The ``raises-exception`` cell tag (``nb.cells[].metadata.tags[raises-exception]``), or ``nb.metadata.allow_errors`` for all ells, now allows for cell exceptions to not halt execution as respected in nbval and other notebook interfaces. This feature is toggleable with the ``force_raise_errors`` configuration option.


		The kernel manager can now be optionally passed into the ``ExecutePreprocessor.preprocess`` and the ``executenb`` functions as the kwarg ``km``. This means that the kernel can be configured as desired before beginning preprocessing.

		This is useful for executing in a context where the kernel has external dependencies that need to be set to non-default values. An example of this might be a Spark kernel where you wish to configure the spark cluster location ahead of time without building a new kernel.

Release changelog 5.4 #876

Release changelog 5.4 #876

Conversation

MSeal commented Sep 5, 2018

MSeal commented Sep 5, 2018

SylvainCorlay left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MSeal commented Sep 5, 2018

mpacer commented Sep 6, 2018 • edited Loading

MSeal commented Sep 6, 2018

blink1073 commented Sep 6, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mpacer left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mpacer commented Sep 6, 2018

Carreau commented Sep 6, 2018

Carreau commented Sep 6, 2018 • edited Loading

mpacer commented Sep 6, 2018

Carreau commented Sep 6, 2018 via email

blink1073 commented Sep 6, 2018

MSeal commented Sep 6, 2018

Carreau commented Sep 6, 2018

mpacer commented Sep 6, 2018 •

edited

Loading

Carreau commented Sep 6, 2018 •

edited

Loading