Merge pull request #58 from bgamari/patch-2

base-libraries: Rename ghc-internals -> ghc-internal

Author: goldfirere

proposals/accepted/051-ghc-base-libraries.rst

@@ -83,13 +83,13 @@ Proposal
 
 We propose to divide ``base`` into three packages:
 
-- ``ghc-internals``: exposes aspects of GHC's internals that may be of interest to "hard-core" developers interested in maximum performance (see `Nikita's blog post <https://nikita-volkov.github.io/internal-convention-is-a-mistake/>`__).
-  The API of ``ghc-internals`` is fully under the control of the GHC team, and of no direct interest to the CLC — only its effects on the API of base.
+- ``ghc-internal``: exposes aspects of GHC's internals that may be of interest to "hard-core" developers interested in maximum performance (see `Nikita's blog post <https://nikita-volkov.github.io/internal-convention-is-a-mistake/>`__).
+  The API of ``ghc-internal`` is fully under the control of the GHC team, and of no direct interest to the CLC — only its effects on the API of base.
 
 - ``base``: as now, whose API is curated by CLC.
-  Depends on ``ghc-internals``, and hence on ``ghc-bignum`` and ``ghc-prim``.
+  Depends on ``ghc-internal``, and hence on ``ghc-bignum`` and ``ghc-prim``.
 
-- ``ghc-experimental``, initially empty, depends on ``base`` and on ``ghc-internals``.
+- ``ghc-experimental``, initially empty, depends on ``base`` and on ``ghc-internal``.
   Functions and data types here are intended to have their ultimate home in base, but while they are settling down they are subject to much weaker stability guarantees.
   Generally, new functions and types introduced in GHC Proposals would start their life here.
   Example: new type families and type constructors for tuples, `GHC Proposal #475 <https://github.com/ghc-proposals/ghc-proposals/pull/475>`__.
@@ -103,12 +103,12 @@ All three packages conform rigorously to the PVP.
 
 Some observations about this structure:
 
-- We should develop both social and technical mechanisms to discourage people from depending directly on ``ghc-internals``, because if such dependencies become frequent and ossified, it will lead to future pain when the API changes.
-  The very name ``ghc-internals`` should serve as a very strong signal in its own right, but even so, saying "we told you not to rely on it" may be true but won't lessen that pain.
+- We should develop both social and technical mechanisms to discourage people from depending directly on ``ghc-internal``, because if such dependencies become frequent and ossified, it will lead to future pain when the API changes.
+  The very name ``ghc-internal`` should serve as a very strong signal in its own right, but even so, saying "we told you not to rely on it" may be true but won't lessen that pain.
   The specific mechanisms do not form part of this proposal, but some possibilities are `discussed in a separate section <#discourage-brainstorm>`__.
 
   Note: "discourage" does not imply "ban".
-  It must remain possible for hard-core developers to depend on `ghc-internals`.
+  It must remain possible for hard-core developers to depend on `ghc-internal`.
   Our goal is only that naive developers should not do so by accident.
 
 - In contrast, clients are *not* discouraged from depending on ``ghc-experimental``; although again its name should convey the idea that it might change at short notice.
@@ -134,11 +134,11 @@ Some observations about this structure:
 
     This is going to disappear from base.
     You probably don't want to use it at all.
-    But if you absolutely must, get it from ``ghc-internals``.
+    But if you absolutely must, get it from ``ghc-internal``.
 
-- To expose a new function from ``ghc-internals`` requires that any functions on which it depends are also in ``ghc-internals`` (not base).
-  So we may need to move code from ``base`` to ``ghc-internals``, leaving a shim behind in base.
-  In practice, that may mean that quite a lot of code will move into ``ghc-internals`` quite quickly.
+- To expose a new function from ``ghc-internal`` requires that any functions on which it depends are also in ``ghc-internal`` (not base).
+  So we may need to move code from ``base`` to ``ghc-internal``, leaving a shim behind in base.
+  In practice, that may mean that quite a lot of code will move into ``ghc-internal`` quite quickly.
   But that's fine: *it is just an implementation matter*: provided the modules, exports, and API of ``base`` are maintained, it is immaterial to clients (and hence to CLC) exactly *how* they are maintained.
 
 - This proposal is fully compatible with, and actively supports, the `CLC charter <https://github.com/haskell/core-libraries-committee#base-package>`__:
@@ -153,13 +153,13 @@ Some observations about this structure:
 
   - allowing the GHC Steering Committee to add new functions and types in ``ghc-experimental``.
 
-- The three "internal" packages: ``ghc-internals``, ``ghc-bignum``, and ``ghc-prim``, could arguably be a single package, but the GHC team has decided that encapsulating the relevant code in this way helps to keep dependencies and responsibilities clear.
+- The three "internal" packages: ``ghc-internal``, ``ghc-bignum``, and ``ghc-prim``, could arguably be a single package, but the GHC team has decided that encapsulating the relevant code in this way helps to keep dependencies and responsibilities clear.
   And it's purely an internal GHC matter; if the team wants to structure GHC's internals with three packages, or ten, that's up to them.
 
 Continuous integration
 ======================
 
-A major difficulty is **knowing when the API of 'base' (as defined in Section 2) has changed.** A change requires CLC approval; but how do we know what commits (to ``base``, to ``ghc-internals``, to ``ghc-prim``) make such a change?
+A major difficulty is **knowing when the API of 'base' (as defined in Section 2) has changed.** A change requires CLC approval; but how do we know what commits (to ``base``, to ``ghc-internal``, to ``ghc-prim``) make such a change?
 
 In the past we have relied on best efforts; but with a bunch of volunteers, mistakes will be made.
 And mistakes can lead to a loss of trust.
@@ -190,43 +190,43 @@ We therefore propose the following, as part of CI:
 5. Develop a new suite of performance tests, specifically for base.
    This is quite open-ended; it is not clear what would be desirable, or how much it would cost.
 
-Some modules in ``ghc-internals`` will very directly affect exports of ``base`` (e.g via shim).
+Some modules in ``ghc-internal`` will very directly affect exports of ``base`` (e.g via shim).
 These modules could be identified, via the existing ``CODEOWNERS`` mechanism, to ping CLC on any commit to those modules.
-This list could be selective, or include all of ``ghc-internals``, at CLC's preference.
+This list could be selective, or include all of ``ghc-internal``, at CLC's preference.
 
 Some of these are cheap to do; others are less so.
 Fortunately the HF seems willing to help.
 
 *But whatever we do here will be a step forward* from our current, unsatisfactory situation.
-Moreover, they will help with CI for changes to GHC itself! (It is rather *more* likely that a commit to GHC's simplifier will cause a perf regression in some package, than a commit to ``ghc-internals``.)
+Moreover, they will help with CI for changes to GHC itself! (It is rather *more* likely that a commit to GHC's simplifier will cause a perf regression in some package, than a commit to ``ghc-internal``.)
 
 Discussion
 ==========
 
-Discourging the (direct) use of ``ghc-internals``
+Discourging the (direct) use of ``ghc-internal``
 -------------------------------------------------
 
 .. _discourage-brainstorm:
 
-Here are some ideas to be explored later for how to discorage the use of ``ghc-internals``.
+Here are some ideas to be explored later for how to discorage the use of ``ghc-internal``.
 
-- The name ``ghc-internals`` is a pretty strong signal all by itself.
+- The name ``ghc-internal`` is a pretty strong signal all by itself.
 
 - Cabal description and README explains how it is intended used (and not used).
 
-- Hoogle could (by default anyway) never show stuff from ``ghc-internals``.
+- Hoogle could (by default anyway) never show stuff from ``ghc-internal``.
 
-- Do not upload Haddocks for ``ghc-internals`` to Hackage.
+- Do not upload Haddocks for ``ghc-internal`` to Hackage.
   (Ditto ``ghc-prim``.) Need to make sure that if someone wants to follow the Haddock source-code link to (say) Functor, they should still find it regardless of where it is actually defined.
 
-- We could consider issuing a warning if you say ``-package ghc-internals`` (or ``ghc-bignum`` or ``ghc-prim``), one that was hard to silence.
+- We could consider issuing a warning if you say ``-package ghc-internal`` (or ``ghc-bignum`` or ``ghc-prim``), one that was hard to silence.
   Since we can have module-level ``WARNING`` pragmas with custom categories, one way to realise this would be to pick a category and add such pragmas to every module in the relevant packages, though we might want to do something more systematic.
   The text of the warnings could encourage users to
 
   - switch to a function exposed by base, and/or
   - petition the CLC to expose this super-useful function from base.
 
-- ``cabal check`` (a per-package check) could warn on packages that use ``ghc-internals``.
+- ``cabal check`` (a per-package check) could warn on packages that use ``ghc-internal``.
 
 GHC Proposals process
 ---------------------
@@ -252,7 +252,7 @@ We propose that:
 Abstraction leakage
 -------------------
 
-We may foresee a couple of ways in which changes in ``ghc-internals`` could become client visible:
+We may foresee a couple of ways in which changes in ``ghc-internal`` could become client visible:
 
 - Occasionally, an error message may mention a fully qualified name for an out-of-scope identifier.
   For example (GHC test ``mod153``)::
@@ -264,11 +264,11 @@ We may foresee a couple of ways in which changes in ``ghc-internals`` could beco
                          or ‘M.id’, defined at mod153.hs:2:21
 
   The "originally defined in" mentions a module; and if that module is in a package that is not imported, GHC will package-qualify the module name.
-  And seeing ``ghc-internals:GHC.Base`` is perhaps less nice.
+  And seeing ``ghc-internal:GHC.Base`` is perhaps less nice.
   This is not a new problem: we already package-qualify modules in ``ghc-prim``.
   One solution is to remove the "originally defined in.." parenthesis for types and functions that would require such package qualification.
 
-- Another form of leakage could be: a new class in ``ghc-internals``, *not exposed in base*, that is given instances for existing data types.
+- Another form of leakage could be: a new class in ``ghc-internal``, *not exposed in base*, that is given instances for existing data types.
   There is a risk that those instances might confusingly be visible to clients of ``base``.
   If so, the CLC should at least be consulted.
 
@@ -279,8 +279,8 @@ They may not be show-stoppers, but we should be thoughtful about mitigating them
 Versions and backports
 ----------------------
 
-We agree that the version number of ``ghc-internals`` may have a major bump between minor releases of GHC.
-(Why? Because to fix the bug we change something in ``ghc-internals``.)
+We agree that the version number of ``ghc-internal`` may have a major bump between minor releases of GHC.
+(Why? Because to fix the bug we change something in ``ghc-internal``.)
 
 This makes an exception to a general rule: generally, a minor release of GHC (say 9.6.4) which only fixes bugs, never makes a major version bump to ``base``, or indeed any boot package.
 
@@ -318,12 +318,12 @@ Some members of the community would like to be able to upgrade/re-install the ``
 (For example, see `this Haskell Discourse thread <https://discourse.haskell.org/t/pre-pre-hftp-decoupling-base-and-ghc/3727>`__ and the earlier versions of now-closed `HF Proposal #47 <https://github.com/haskellfoundation/tech-proposals/pull/47>`__.)
 The goal of such reinstalling would be both to (a) support multiple versions of ``base`` with the same GHC, and (b) support multiple versions of GHC with the same ``base``.
 
-By separating ``ghc-internals`` from ``base``, this proposal may make the reinstallable ``base`` project one step more feasible.
-In particular, by corralling the code that is intimately tied to a specific version of GHC in ``ghc-internals``, one might hope the code left in ``base`` would be portable across versions of GHC with no extra effort.
+By separating ``ghc-internal`` from ``base``, this proposal may make the reinstallable ``base`` project one step more feasible.
+In particular, by corralling the code that is intimately tied to a specific version of GHC in ``ghc-internal``, one might hope the code left in ``base`` would be portable across versions of GHC with no extra effort.
 
 Nevertheless, *supporting reinstallable ``base`` is not a goal of this proposal*, nor is it an immediate consequence of it.
 There is not yet consensus that this is a goal worth pursuing.
-What code should be moved from ``base`` to ``ghc-internals`` is also out of scope (as described above in the proposal proper), and without knowing those details, we cannot know whether ``base`` would incidentally become more portable either.
+What code should be moved from ``base`` to ``ghc-internal`` is also out of scope (as described above in the proposal proper), and without knowing those details, we cannot know whether ``base`` would incidentally become more portable either.
 
 Other teams to consult
 ======================
@@ -332,7 +332,7 @@ There are other stakeholders in this space who we should consult, in addition to
 
 **Stackage curators**
 
-- Is it OK to make a major bump in ``ghc-internals`` for a minor release of GHC?
+- Is it OK to make a major bump in ``ghc-internal`` for a minor release of GHC?
 
 **Haddock team**
 
@@ -341,14 +341,14 @@ There are other stakeholders in this space who we should consult, in addition to
 
 **Hackage team**
 
-- Can/should we support hiding ``ghc-internals`` on Hackage?
+- Can/should we support hiding ``ghc-internal`` on Hackage?
 
 **Security team** / **Stability working group**
 
-- It might be easy for the new security-vulnerability mechanism to also flag packages that depend transitively on ``ghc-internals``.
+- It might be easy for the new security-vulnerability mechanism to also flag packages that depend transitively on ``ghc-internal``.
   If they depend on it via ``base``, this is fine.
   But if they depend on it via another package, this could be a hazard migrating to a newer GHC the code authors were not aware of.
 
 **HLint team**
 
-- Can we add a check for imports from ``ghc-internals``?
+- Can we add a check for imports from ``ghc-internal``?