Updates following Stability group discussion

Author: simonpj

proposals/0000-ghc-module-naming.rst

@@ -7,26 +7,35 @@ Background and motivation
 The accepted `Proposal #51: GHC base libraries <https://github.com/haskellfoundation/tech-proposals/blob/main/proposals/accepted/051-ghc-base-libraries.rst>`_
 defines the following libraries:
 
-* ``base``: the foundational library on which the rest of the ecosystem is based.
-
+* ``base``:
+  * The foundational library on which the rest of the Haskell ecosystem is based.
   * Its API is carefully curated by the `Core Libraries Committee <https://github.com/haskell/core-libraries-committee>`_, and is kept rather stable.
+  * Depends on ``ghc-internal`` (and ``ghc-prim`` etc), but *not* on ``ghc-experimental``.
+  * Major version bumps are at the Core Libraries Committee's discretion.
 
-* ``ghc-experimental``: the home of experimental extensions to GHC, usually ones proposed by the
+* ``ghc-experimental``:
+  * The home of experimental extensions to GHC, usually ones proposed by the
   `GHC Steering Committee <https://github.com/ghc-proposals/ghc-proposals/>`_.
 
-  * Functions and types in here are usually candidates for later transfer into ``base``.  But not necessarily: if a collection of functions is not adopted widely enough, it may not be proposed for a move to `base`.
+  * Functions and types in here are usually candidates for later transfer into ``base``.  But not necessarily: if a collection of functions is not adopted widely enough, it may not be proposed for a move to `base`.  Or it could move to another library entirely.
 
   * It is user-facing (user are encouraged to depend on it), but its API is less stable than ``base``.
 
-* ``ghc-prim, ghc-internals`` (and perhaps others): define functions and data types used internally by GHC to support the API of ``base`` and ``ghc-experimental``.
+  * Depends on ``base``.
+
+  * Likely to have a major version bump with each GHC release.
+
+* ``ghc-prim, ghc-internal`` (and perhaps others; it's an internal GHC implementation decision):
+  * Define functions and data types used internally by GHC to support the API of ``base`` and ``ghc-experimental``.
 
   * These libraries come with no stability guarantees: they may change at short notice.
 
 In addition we already have:
 
 * ``ghc``: this library exposes GHC as a library, through the (currently ill-defined) GHC API.
 
-All these libraries follow the Haskell Package Versioning Policy (PVP).
+All these libraries follow the Haskell Package Versioning Policy (PVP).  The reader is encouraged
+to consult `Proposal #51: GHC base libraries <https://github.com/haskellfoundation/tech-proposals/blob/main/proposals/accepted/051-ghc-base-libraries.rst>`_ for more background and rationale for this library structure.
 
 The question arises of *what module names should be used*. For example, suppose that all three exposed a module called ``Data.Tuple``.  In principle that would be fine -- GHC allows you
 to use the package name in the ``import`` statement, to disambiguate.  But it's *extremely* confusing.  This proposal articulates a set of conventions to
@@ -44,22 +53,62 @@ any changes to ``ghc`` or to ``cabal``.
 Proposal 1
 -----------
 
-* Modules in ``base``, ``ghc-experimental``, ``ghc-prim``, ``ghc-internals`` etc should all have distinct names.
+* Modules in ``base``, ``ghc-experimental``, ``ghc-prim``, ``ghc-internal`` etc should all have distinct names.
 
 That principle leads immediately to the question: what should those names be?  Hence proposal 2.
 
 Proposal 2
 -----------
 
-* Modules in GHC's internal libraries (``ghc-prim``, ``ghc-internals`` etc) should be of form ``GHC.*``.
-* Modules in ``ghc-experimental`` should be of form ``Experimental.*``.
-* Modules in ``base`` should not have either of these prefixes.
+* Modules in GHC's internal libraries (``ghc-prim``, ``ghc-internal`` etc) should be of form ``GHC.Internal*``.
+* Modules in ``ghc-experimental`` should be of form ``*.Experimental``.
+* Modules in ``base`` should not have either of these forms.
 
 So example we might have
 
-* ``GHC.Tuple`` in ``ghc-internals``,
-* ``Experimental.Tuple`` or ``Experimental.Data.Tuple`` in ``ghc-experimental``
-* ``Data.Tuple`` in ``base``
+* ``GHC.Internal.Bits`` in ``ghc-internal``,
+* ``Data.Bits.Experimental`` in ``ghc-experimental``
+* ``Data.Bits``, and currently also ``GHC.Bits``, in ``base``
+
+Why ``GHC.Internal.*`` for modules in ``ghc-internal``?  Would ``GHC.*`` not be enough? Here's why:
+* ``base`` already has ``GHC.Bits``, and Proposal 1 stops us re-using the same module name in ``ghc-internal``.
+  If we were starting from a blank sheet of paper we might have no ``GHC.*`` modules in ``base``, but there
+  curently 138 such modules and it seems unlikely that we will ever remove all, or even most, of them from
+  ``base``.
+
+* The prefix ``GHC.Internal`` serves as an additional clue to the importing module that this API is not stable.
+
+Note that among the GHC implementation packages (``ghc-prim``, ``ghc-internal``, ``ghc-bignum`` etc) there
+is no expectation that the module name signals which package the module is in. It's just an internal
+implementation matter.
+
+Using a prefix for ``ghc-internal`` and a suffix for ``ghc-experimental`` may seem inconsistent,
+but it was a clear consensus from the discussion about the proposal:
+* ``Data.Tuple.Experimental``, for example, is an companion/extension of ``Data.Tuple``; some exports may move from one to the other. Many developers sort their imports alphabetically. Making this a suffix means all ``Data.Tuple``-related imports are next to each other.  For example, one might prefer this::
+
+    import Control.Applicative
+    import Control.Applicative.Experimental
+    import Control.Arrow
+    import Data.Tuple
+    import Foreign.C
+    import Foreign.C.Experimental
+
+  to this::
+
+    import Control.Applicative
+    import Control.Arrow
+    import Experimental.Control.Applicative
+    import Experimental.Foreign.C
+    import Data.Tuple
+    import Foreign.C
+
+  This pattern, of a module in ``ghc-experimental`` that is closely related to one in ``base`` seems likely to be common.
+
+* On the other hand, GHC-internal modules are often unrelated to the naming scheme of ``base``.
+  Here a prefix feels more appropriate.  Moreover this ``GHC.*`` convention is already widely
+  used, in both ``base`` and ``ghc-prim``, as well as the modules that implement GHC itself, so
+  using a prefix aligns with current practice.
+  
 
 Proposal 3
 -----------
@@ -80,16 +129,26 @@ rather carefully.
 Proposal 4
 ------------
 
-* The public API of package ``ghc`` (GHC as a library) should have modules of form ``GhcAPI.*``.
+All of the modules in package ``ghc`` currently start with ``GHC.*`` which
+(currently correctly) signals that they are part of GHC's internals.
+
+As part of the GHC API redesign (a HF project in its own right, currently stalled) it would be very helpful
+to identify a (multi-module) stable API for package ``ghc``. In that way, users of package ``ghc``
+could know whether
+they are using a curated, relatively-stable API function, or reaching deep into GHC's guts and using
+a random fuction whose name or type, or very existence, might change without warning. Hence:
+
+* The public API of package ``ghc`` (GHC as a library) should have modules whose names clearly distinguish them
+  from internal modules.
+
+For example, the public API could have modules of form ``GhcAPI.*``, or ``GHC.API.*``, or something else.
+The specifica are a matter for the future GHC API working group.
 
-All of the modules in package ``ghc`` currently start with ``GHC.*`` which correctly signals that they are part of GHC's internals.
-As part of the GHC API redesign (a HF project in its own right, currently stalled) it would be very helpfult
-to modules with stable APIs, and a new prefix, such as ``GhcAPI.*``.
 
 
 Timescale
 ==========
-The first release of GHC with `ghc-experimental` and `ghc-internals` will be GHC 9.10, which expect to
+The first release of GHC with `ghc-experimental` and `ghc-internal` will be GHC 9.10, which expect to
 release in early 2024.  It would be good to establish naming conventions for modules well before this date.
 
 Example lifecycle
@@ -118,7 +177,7 @@ Alternatives
   * In the meantime there are two modules both called ``Data.Tuple``.  This is bad.  Which one does ``import Data.Tuple`` import?  (Look at the Cabal file, perhaps?)  How can I import both?  (Package-qualified imports perhaps.) So it will really only help in the case of a brand-new module, not already in ``base``.
   * It loses the explicit cue, in the source code, given by ``import Experimental.Data.Tuple``.
 
-* We could use ``GHC.*`` for modules in ``ghc-experimental``, and maybe ``GHC.Internals.*`` for module in ``ghc-internals``.  But
+* We could use ``GHC.*`` for modules in ``ghc-experimental``, and maybe ``GHC.Internals.*`` for module in ``ghc-internal``.  But
 
   * There are two sorts of GHC-specific-ness to consider:
 
@@ -127,14 +186,14 @@ Alternatives
 
     It is worth distinguishing these: it's confusing if both start with ``GHC.``.
 
-  * It would be a huge upheaval (with impact on users) to rename hundreds of modules in ``ghc-internals``.
+  * It would be a huge upheaval (with impact on users) to rename hundreds of modules in ``ghc-internal``.
 
-* We could use ``GHC.Experimental.*`` for modules in ``ghc-experimental``.  But that seems a bit backwards: ``GHC.Tuple`` (in ``ghc-internals``) would superficially appear more stable (less experimental) than ``GHC.Experimental.Tuple`` in ``ghc-experimental``; but the reverse is the case.
+* We could use ``GHC.Experimental.*`` for modules in ``ghc-experimental``.  But that seems a bit backwards: ``GHC.Tuple`` (in ``ghc-internal``) would superficially appear more stable (less experimental) than ``GHC.Experimental.Tuple`` in ``ghc-experimental``; but the reverse is the case.
 
 * We could use a suffix ``*.Internals`` or ``*.Experimental`` instead of a prefix.  But
 
   * This sort of naming is often used to distinguish modules *within* a package, not *between* packages.
-  * In the case of ``ghc-internals`` it would still suffer from the cost of renaming hundreds of modules.
+  * In the case of ``ghc-internal`` it would still suffer from the cost of renaming hundreds of modules.
 
 * Concerning Proposal 4, we could instead use