Improve error message when deprecated --collaborative is used without jupyter-collaboration

[mdengler]

Updates error message from fix to #14774

References

References issue #14774

Code changes

Adds to the error message so user knows:

1. the process was forcibly exited
2. the obvious fix (remove any --collaborative command line flag)
3. the not-so-obvious fixes (other command line / config flags -- which don't have the string "collaborat" in them at all -- and/or disable / remove related extensions)

User-facing changes

Same as "Code changes" section.

Backwards-incompatible changes

None

[jupyterlab-probot]

Thanks for making a pull request to jupyterlab!
To try out this branch on binder, follow this link:

[welcome]

Thanks for submitting your first pull request! You are awesome! 🤗

If you haven't done so already, check out Jupyter's Code of Conduct. Also, please make sure you followed the pull request template, as this will help us review your contribution more quickly.

You can meet the other Jovyans by joining our Discourse forum. There is also a intro thread there where you can stop by and say Hi! 👋

Welcome to the Jupyter community! 🎉

[fcollonval]

Thanks @mdengler would you mind linking to the official documentation rather than the forum: https://jupyterlab-realtime-collaboration.readthedocs.io/en/latest/configuration.html

This will help maintaining the information up to date.

[mdengler]

Thanks. I rebased the PR branch onto main and pushed it again because some UI tasks failed (? hope the rebase fixes).

I put the documentation link you suggested first, but included the second discussion link because it has some cross-cutting information that is very useful in practice.

I can remove and leave just the documentation link in; for ease of review, I include screenshots of and links to the two links in this comment:

Documentation at https://jupyterlab-realtime-collaboration.readthedocs.io/en/latest/configuration.html :

Discussion at https://discourse.jupyter.org/t/how-to-disable-jupyter-collaboration-extension/21329/9 :

[krassowski]

I can remove and leave just the documentation link in; for ease of review, I include screenshots of and links to the two links in this comment:

Please do remove the link to the forum, I also believe we should not need to link to it. If in future there is a specific bit of information which is on the forum but not in the docs, the docs need to be updated, because the docs are versioned and permanent, while the forum answers only reflect what is working as of the time they were written.

[mdengler]

I'm hoping that, as a long-time jupyter lab user myself, the statement that "this forum post was useful because it brought together configuration information that is spread across the documentation" would help clarify why it's useful.

If [...] there is [...] information [...] not in the docs, the docs need to be updated

The issue is not that the information is not present in the documentation, but that it's not in the same place in the documentation. The documentation structure puts the information the user needs to fix this problem -- the information about how to affect/remove some configuration that they may have had already set -- in separate documentation sections, probably for good reasons. No documentation structure can meet all the requirements of every issue, because issues can touch on different aspects of the system. In this case, the issue revolves around configuration, and the configuration can exist in multiple places but the documentation documents these places in separate sections.

[krassowski]

Please see my other comment where I suggest a solution which "fixing" the documentation to include more examples and links to common Jupyter configuration docs.

[mdengler]

The checks/tests failures appear to be unrelated to my change (one string in one error message)

[krassowski]

The current version has a pleonasm/tautology which makes it hard to understand. It also links to the forum which we advise against.

Suggested change

	To run without collaboration, disable collaboration (for example, remove the `--collaborative` flag from the commandline; this flag is now deprecated and will be removed in JupyterLab v5). To see more ways to adjust the collaborative behavior, see https://jupyterlab-realtime-collaboration.readthedocs.io/en/latest/configuration.html and https://discourse.jupyter.org/t/how-to-disable-jupyter-collaboration-extension/21329/9 .
	If you wish to proceed without installing `jupyter_collaboration` please remove the `--collaborative` flag or switch off the `LabApp.collaborative` configuration traitlet depending on how you enabled this setting in an earlier version.
	The `--colaborative` flag is not needed when `jupyter_collaboration` is installed and will be removed in JupyterLab v5. You can continue using this flag to ensure that collaborative mode is enabled, but it does not have a functional impact on `jupyter_collaboration`.
	To configure or disable collaboration when `jupyter_collaboration` is installed, please refer to:
	https://jupyterlab-realtime-collaboration.readthedocs.io/en/latest/configuration.html

I know that the Nick's message on the forum is valuable to you because it demonstrates how traitlets configuration works and that it can be provided with either a json file or on command line, however if we explained this for every single of hundreds of configuration options we have, and had a link to a post for every such a configuration option it would really be difficult to maintain, for example if someone modifies their post on the forum that we linked to. Instead what we could do is improving https://docs.jupyter.org/en/latest/use/config.html to add more examples, for example including the json file - if you would like to open a pull request there feel free to tag me for review.

[krassowski]

We can also improve https://jupyterlab-realtime-collaboration.readthedocs.io/en/latest/configuration.html by linking to https://docs.jupyter.org/en/latest/use/config.html and providing more examples on jupyterlab-realtime-collaboration side.

[mdengler]

has a pleonasm/tautology

You mean "to run without collaboration, disable collaboration"? It's more of an antanaclasis, right (the first "collaboration" is the python module, the second "collaboration" is the feature/concept). Nevertheless, I see your point; I hope I've improved it now.

if we [had a long configuration & runtime options example] for every single of hundreds of configuration options we have [...] it would be difficult to maintain

I take your point completely -- though I think some very-common options/issues might justify this cost, but this is not one of them -- and have removed the link.

what we could do is improving https://docs.jupyter.org/en/latest/use/config.html to add more examples, for example including the json file - if you would like to open a pull request there feel free to tag me for review.

I think this would definitely improve the situation and will give this a try sometime.

[krassowski]

Thanks for your contribution and patience here @mdengler!

[welcome]

Congrats on your first merged pull request in this project! 🎉

Thank you for contributing, we are very proud of you! ❤️