Explain or refer to the brownout strategy in the thrown exception

[Stijn Peeters]

I became aware of sklearn's deprecation because the exception thrown by this package started showing up in my CI Docker build logs, however because it only happens sometimes and the majority of builds still passed, I chalked it up to a quirk of the build system and figured it was more of a warning than a serious error (also because we only use the sklearn package through another dependency that still refers to it).

I eventually looked at the repository and understood that this error only happened sometimes because of the 'brownout strategy' that was adopted but this is not clear from the error message shown in pip.

It would have been a lot clearer to me that I needed to take action if this was mentioned in the error message shown to users. Since full deprecation is still pretty far in the future and I think other people could be in the same boat as me it would be helpful if the error message could somehow explicitly clarify the implications of this 'brownout strategy'.

[Loïc Estève]

Thanks for taking the time to open an issue!

I agree with you that the brownout strategy can be a bit confusing since it can be dismissed as a temporary issue ... but we decided that was the best approach. This article does a good job of explaining why brownouts are useful in general.

Improvement suggestions for the error message would be welcome, with the following constraints:

• don't make the error message a lot longer, it seems already quite long as it is
• I would suspect most people getting this error will not be familiar with the term "brownout" and explaining it in the error message while keeping it short seems quite hard.
• I would be a bit reluctant to have many other releases of the sklearn package to avoid confusing the situation further.

About the need to take action the error message says:

The 'sklearn' PyPI package is deprecated, use 'scikit-learn' rather than 'sklearn' for pip commands.

and

Here is how to fix this error in the main use cases:
...

so I am not too sure what else can be done on this front.

There is also a link to the README of this project in the error message:

More information is available at https://github.com/scikit-learn/sklearn-pypi-package,

For reference the full error message is below, maybe you got something different?

The 'sklearn' PyPI package is deprecated, use 'scikit-learn'
rather than 'sklearn' for pip commands.

Here is how to fix this error in the main use cases:
- use 'pip install scikit-learn' rather than 'pip install sklearn'
- replace 'sklearn' by 'scikit-learn' in your pip requirements files
  (requirements.txt, setup.py, setup.cfg, Pipfile, etc ...)
- if the 'sklearn' package is used by one of your dependencies,
  it would be great if you take some time to track which package uses
  'sklearn' instead of 'scikit-learn' and report it to their issue tracker
- as a last resort, set the environment variable
  SKLEARN_ALLOW_DEPRECATED_SKLEARN_PACKAGE_INSTALL=True to avoid this error

More information is available at
https://github.com/scikit-learn/sklearn-pypi-package

If the previous advice does not cover your use case, feel free to report it at
https://github.com/scikit-learn/sklearn-pypi-package/issues/new

[Olivier Grisel]

Since the brownout period is coming to an end, I think the existing message is appropriate.