Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Added extra information and user-action summaries to 7 migration docs. #6850

Merged
merged 8 commits into from
Apr 27, 2023
Merged

Added extra information and user-action summaries to 7 migration docs. #6850

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
d22d6f7
Added extra information and user-action summaries to 7 migration docs.
ericsnekbytes Apr 24, 2023
8bd3da1
Update docs/source/migrate_to_notebook7.md
ericsnekbytes Apr 25, 2023
3344991
Update docs/source/migrate_to_notebook7.md
ericsnekbytes Apr 25, 2023
de8e18a
Updated nbclassic messaging.
ericsnekbytes Apr 25, 2023
36ab2ab
Revised heading.
ericsnekbytes Apr 26, 2023
ade5588
Updated heading.
ericsnekbytes Apr 27, 2023
ff610c8
Merge branch 'main' into migrate_to_7_updates
ericsnekbytes Apr 27, 2023
0fa3626
Formatting pass.
ericsnekbytes Apr 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 51 additions & 14 deletions docs/source/migrate_to_notebook7.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,62 @@
# Migrating to Notebook 7

```{warning}
The Jupyter Notebook application is undergoing a major refactoring to
improve the user experience and to make it easier to maintain and extend.
*Updated 2023-04-24*

This set of migration guides are intended to help you migrate your Classic Notebook
setup and extensions to the new Jupyter Notebook 7, which is built on top of JupyterLab 4.
```{warning}
The Jupyter Notebook application's newest version 7 upgrade might break your
extensions or other customizations, please read more below to find out if you
need to take any actions to ensure a smooth, uninterrupted experience
```

## Sunrising the Jupyter Notebook 7
A major upgrade to the Jupyter Notebook app is coming with Notebook 7! This
ericsnekbytes marked this conversation as resolved.
Show resolved Hide resolved
upgrade will bring a heap of new features, but will also break backwards
compatibility with many classic Notebook features and customizations.

This set of guides is here to help you migrate your Classic Notebook setup and
extensions to the new Notebook 7.

## What you need to do

For users who don't use extensions or other customizations, you will seamlessly
receive the new Notebook 7 when you `pip install notebook` once version 7 is
released out of beta, along with all its new features, like realtime
collaboration, debugger, and theming.

For users who need to use extensions or other customizations, you have a couple
of options:

- Look for Notebook 7 compatible versions of the extensions you already use,
and [find replacements for those that are not available]

- If you NEED to maintain compatibility with the Classic Notebook for extensions
ericsnekbytes marked this conversation as resolved.
Show resolved Hide resolved
or other customizations that are critical to your workflows, you can switch to
[nbclassic], the new home for users who need to maintain compatibility with the
Copy link
Member

@jtpio jtpio Apr 25, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "new home" and "maintain" words in this sentence give the somewhat misleading idea that nbclassic will be maintained in the long run?

NBClassic is supposed to help with the transition to Notebook 7, but shouldn't be seen as an "alternative" to Notebook 7 long term.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah it's a subtle thing to communicate. We want people who need it to know it's there and to use it, without giving the impression it's a permanent thing. I'll add a bit/re-work to add some clarity. Thanks!

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I posted a comment in the team compass issue to see if the EC can provide guidance for the documentation as well, since they will be looking at the blog post: jupyter/notebook-team-compass#24 (comment)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have updated this portion with a recent commit, and we can modify as needed after the EC takes a look.

old notebook interface

## Why things are changing
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe something like the following?

Suggested change
## Why things are changing
## Why a new major version?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this one is worth keeping, because it simplifies the language and reduces jargon (related to semantic versioning / "major version", which not everyone is going to know about). Maybe there's a plain-language compromise, like "Why the big version change?" Is it the "major-version-number-is-being-incremented-to-7" idea that you want to communicate here?

Copy link
Collaborator Author

@ericsnekbytes ericsnekbytes Apr 26, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jtpio Is "Why the big version change?" good? Edit: I've just pushed that, let me know if there's anything else.

Copy link
Member

@jtpio jtpio Apr 27, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"big" sounds ambiguous: what does big mean?

If this is because of the word "major" then maybe we could just drop it and only keep "Why a new version"?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Big was supposed to communicate that sweeping changes are taking place in plain-language (without the "major version" jargon and the odd-sounding/confusing phrasing that it necessitates...."Why a new major version" sounds odd, but "Why a major new version" does not...probably related to points noted in this BBC article...).

I've pushed an update to just "Why a new version?" which I think is good enough, let me know if you've got any other suggestions.


For the past few years, the Classic Jupyter Notebook has been in maintenance mode.
For the past few years, the Classic Jupyter Notebook has been in maintenance
mode.

Development has mostly moved to alternative user interfaces like JupyterLab, which is a more
modern and extensible web application. This has resulted in a lot of new
features and improvements in JupyterLab, but also in a lot of new features and
improvements that were not possible to integrate to the Classic Notebook.
Development has mostly moved to alternative user interfaces like JupyterLab,
which is a more modern and extensible web application. This has resulted in
a lot of new features and improvements in JupyterLab, but also in a lot of
new features and improvements that were not possible to integrate to the
Classic Notebook.

For a while the plan was to progressively _sunset_ the Classic Notebook and not maintain it anymore. However, the Classic Notebook is still widely used and it is still the default user interface for Jupyter in many scenarios. Many users and organizations have not been able to switch to JupyterLab yet. For some users, JupyterLab can also be a more complex environment to use, especially for beginners.
For a while the plan was to progressively _sunset_ the Classic Notebook and
not maintain it anymore. However, the Classic Notebook is still widely used
and it is still the default user interface for Jupyter in many scenarios.
Many users and organizations have not been able to switch to JupyterLab yet.
For some users, JupyterLab can also be a more complex environment to use,
especially for beginners.

Following the feedback from the community, it was decided late 2021 to continue developing the Jupyter Notebook application and _sunrise_ it as Notebook 7. Notebook 7 is built on top of JupyterLab components and delivers new features like realtime collaboration, debugger, and theming.
Following the feedback from the community, it was decided late 2021 to
continue developing the Jupyter Notebook application and _sunrise_ it as
Notebook 7.

You can find more details about the changes currently taking place in the Jupyter Ecosystem in the [JEP 79] and [team-compass note].
You can find more details about the changes currently taking place in the
Jupyter Ecosystem in the [JEP 79] and [team-compass note].

## New features in Notebook 7

Expand All @@ -44,3 +79,5 @@ migrating/multiple-interfaces.md

[jep 79]: https://jupyter.org/enhancement-proposals/79-notebook-v7/notebook-v7.html
[team-compass note]: https://github.com/jupyter/notebook-team-compass/issues/5#issuecomment-1085254000
[find replacements for those that are not available]: https://jupyter-notebook.readthedocs.io/en/latest/migrating/frontend-extensions.html#jupyterlab-equivalent-extensions-to-the-classic-notebook
[nbclassic]: https://github.com/jupyter/nbclassic