[MRG] Add missing entries to whatsnew

doc/whats_new/v0.22.rst

@@ -14,17 +14,53 @@ refer to
 :ref:`sphx_glr_auto_examples_release_highlights_plot_release_highlights_0_22_0.py`.
 
 
+Cleaning of the public API
+--------------------------
+
+Scikit-learn has a public API, and a private API.
+
+Any change to the public API is subject to a deprecation cycle of two minor
+versions. The private API isn't publicly documented and isn't subject to any
+deprecation cycle, so users should not rely on it.
+
+Whether a tool is private or public depends on whether you can import it
+without a leading underscore in the import path. For example
+``sklearn.pipeline.make_pipeline`` is public, while
+`sklearn.pipeline._name_estimators` is private.
+``sklearn.ensemble._gb.BaseEnsemble`` is private too because the whole `_gb`
+module is private.
+
+Up to 0.22, some tools were de-facto public (no leading underscore), while
+they should have been private in the first place. In version 0.22, these
+tools have been made properly private, and the public API space has been
+cleaned. In addition, importing from files in sub-packages is deprecated:
+you should use ``from sklearn.cluster import Birch`` instead of ``from
+sklearn.cluster.birch import Birch`` (in practice, ``birch.py`` has been
+moved to ``_birch.py``).
+
+.. note::
+
+    All the tools in the public API should be documented in the `API
+    Reference <https://scikit-learn.org/dev/modules/classes.html>`_. If you
+    find a public tool that isn't in the API reference, that means it should
+    either be private or documented. Please let us know by opening an issue!
+
+
 Deprecations: using ``FutureWarning`` from now on
 -------------------------------------------------
 
 When deprecating a feature, previous versions of scikit-learn used to raise
 a ``DeprecationWarning``. Since the ``DeprecationWarnings`` aren't shown by
 default by Python, scikit-learn needed to resort to a custom warning filter
-that would always show the warnings.
-
-This filter is now removed, and starting from 0.22 scikit-learn will show
-``FutureWarnings`` for deprecations. :pr:`15080` by `Nicolas Hug`_.
+to always show the warnings. That filter would sometimes interfere
+with users custom warning filters.
 
+Starting from version 0.22, scikit-learn will show ``FutureWarnings`` for
+deprecations, `as recommended by the Python documentation
+<https://docs.python.org/3/library/exceptions.html#FutureWarning>`_.
+``FutureWarnings`` are always shown by default by Python, so the custom
+filter has been removed and scikit-learn no longer hinders with user
+filters. :pr:`15080` by `Nicolas Hug`_.
 
 Changed models
 --------------
@@ -111,6 +147,12 @@ Changelog
   exposes an ``n_iter_`` indicating the maximum number of iterations performed
   on each seed. :pr:`15120` by `Adrin Jalali`_.
 
+- |Fix| :class:`cluster.AgglomerativeClustering` and
+  :class:`cluster.FeatureAgglomeration` now raise an error if
+  `affinity='cosine'` and `X` has samples that are all-zeros. :pr:`7943` by
+  :user:`mthorrell`.
+
+
 :mod:`sklearn.compose`
 ......................
 
@@ -336,14 +378,6 @@ Changelog
   estimator's constructor but not stored as attributes on the instance.
   :pr:`14464` by `Joel Nothman`_.
 
-:mod:`sklearn.hierarchical`
-...........................
-
-- |Fix| :class:`hierarchical.AgglomerativeClustering` and
-  :class:`hierarchical.FeatureAgglomeration` now raise an error if
-  `affinity='cosine'` and `X` has samples that are all-zeros. :pr:`7943` by
-  :user:`mthorrell`.
-
 :mod:`sklearn.impute`
 .....................
 
@@ -525,8 +559,8 @@ Changelog
   :pr:`14732` by :user:`Agamemnon Krasoulis <agamemnonc>`.
 
 - |Enhancement| 'roc_auc_ovr_weighted' and 'roc_auc_ovo_weighted' can now be
-  used as the `scoring` parameter of model-selection tools. :pr:`14417` by
-  `Thomas Fan`_.
+  used as the :term:`scoring` parameter of model-selection tools.
+  :pr:`14417` by `Thomas Fan`_.
 
 :mod:`sklearn.model_selection`
 ..............................