Formally deprecate modules informally marked unstable in #146

[Ericson2314]

Background

In #146 a number of modules (based on @bgamari's spreadsheet were documented as unstable.

• GHC-internal modules in base #146 (comment) has the exact list of modules.

• https://gitlab.haskell.org/ghc/ghc/-/merge_requests/10422 is the implementation PR

However, these modules were not formally deprecated. I am not sure why this didn't happen.

In #295, I am proposing how to eventually remove them entirely, but there is unlikely to be consensus on how to do this imminently.

@Bodigrim suggested

What I would suggest is to mark all modules, which were marked as unstable in #146 (comment), as deprecated (at this point without any particular schedule for removal). Then after a couple of GHC releases we will be in good position to decide whether and when to remove them from base

@AndreasPK likewise suggests a first step of

Some problematic modules are identified (I agree with the list for the most part) and a decision is made to deprecate them.

I am therefore seeing consensus across CLC members and GHC devs that this is a good first step. Great! let's do it.

Proposal

Deprecate these modules. (Some things in #146 are already deprecated, and thus not included below.)

Deprecated Module	Migration
GHC.Arr	Use the array package`
GHC.ArrayArray	Use GHC.Exts bad suggestion because we want to get rid of that module too, but its what the docs say today
GHC.Conc.IO	Use GHC.Conc, or ghc-internal for any unstable bits not in GHC.Conc
GHC.Encoding.UTF8	Use text
GHC.Exception	Use Control.Exception, or ghc-internals for anything not in there
GHC.Exception.Type	Same advice as for GHC.Exception
GHC.Fingerprint.Type	Use GHC.Fingerprint. If it is deprecated as per below, inline those instructions.
GHC.InfoProv	Use ghc-internal
GHC.IO.Buffer	Use ghc-internal
GHC.IO.Device	Use ghc-internal
GHC.IO.Encoding	Use ghc-internal
GHC.IO.Exception	Use ghc-internal
GHC.IO.Handle.Text	Use ghc-internal
GHC.Stack.Types	Use GHC.Stack
GHC.TopHandler	Use GHC.Conc or ghc-internal
GHC.Event.TimeOut	Use ghc-internal
GHC.Float.RealFracMethods	Rely on rewrite rules, or use ghc-internal
GHC.GHCi	Use ghc-internal
GHC.GHCi.Helpers	Use ghc-internal
GHC.IO.Handle.Internals	Use GHC.IO.Handle or ghc-internal
GHC.IO.Handle.Types	Use GHC.IO.Handle or ghc-internal
GHC.IO.SubSystem	Use ghc-internal
GHC.IOPort	Use ghc-internal
System.Posix.Internals	Use ghc-internal

Appendix: Excluded deprecations

These modules were additionally recommended by @bgamari but not marked in #146.
I see no reason why not to deprecate them too, but I am not proposing to do so yet, at @Bodigrim's suggestion.

Additional deprecated Module	Migration
GHC.Bits	Use Data.Bits
GHC.Char	Use Data.Char, or regular == and /== from Prelude
GHC.Fingerprint	Use Data.Typeable or ghc-internal

These modules were marked deprecated but it doesn't seem prudent to deprecate them at this time.

Exceptions to not yet deprecate	Reasons
GHC.Conc	Wildely used, no stable replacement yet
GHC.IO	Wildely used, no stable replacement yet
GHC.RTS.Flags	Handled in #289
GHC.Stats	Want to move to ghc-experimental, but can't do deprecrated module reexports yet
GHC.ExecutionStack	Want to move to ghc-experimental, but can't do deprecrated module reexports yet

[bgamari]

I do not believe that we should be giving "use ghc-internal" as a migration strategy in the case of things which we actually expect users to use. From my perspective, GHC's core libraries consist of four classes of declarations:

1. User-facing things that are generally expected to be provided by any Haskell implementation (e.g. Data.List, System.IO)
2. User-facing things that rely on stable design choices of GHC that another Haskell implementation may reasonably implement differently (e.g. GHC.InfoProv, GHC.ExecutionStack, GHC.Stats, the ghc-compact package)
3. Things that are dependent upon GHC implementation details that GHC-upstream does not explicitly declare to be stable but which a user might nevertheless have good reason to use (e.g. GHC.IO.Handle.Internals, the ghc-heap package).
4. Things that are dependent upon GHC implementation details that GHC-upstream would rather users entirely avoid relying upon (e.g. GHC.GHCi, GHC.IOPort, GHC.Conc.Sync.sharedCAF, GHC.Prim.{unpackClosure#,getApStackVal#,getCCSOf#,...})

We want to expose these declarations in such a way that (1), (2), and (3) are both conveniently accessible to users and readily assigned semantically-meaningful version numbers.

In my opinion this means that:

• (1) should be exposed by base.

• (2) should be exposed by either a dedicated package (e.g. ghc-compact) or perhaps a catch-all, as of yet unnamed, package (for concreteness we will refer to this package ghc-primitives here). Alternatively, we might also decide to accept a pragmatic compromise and continue expose some fraction of (2) from base.

• (3) should be exposed from either a dedicated package or from ghc-primitives.

• (4) should be either hidden or only exposed from ghc-internal

[bgamari]

However, these modules were not formally deprecated. I am not sure why this didn't happen.

Just to fill in some context: The spreadsheet above was an initial study to assess what was currently in base with the goal of informing the next steps, beginning with the base/ghc-internal split. The question of what should happen with the things listed as "internal" on that spreadsheet was intentionally deferred. The hope was exactly that we would eventually have a discussion like the one being had on this ticket.

[AndreasPK]

The modules which are not marked as ghc-internal should only be deprecated after their contents are available in a non ghc-internal location. Based on the discussion in the other proposal this seems like a oversight?

Otherwise this seems sensible to me as written.

[hasufell]

The modules which are not marked as ghc-internal should only be deprecated after their contents are available in a non ghc-internal location.

Yes, users should be able to react to the deprecation warning.

[Ericson2314]

@bgamari

The question of what should happen with the things listed as "internal" on that spreadsheet was intentionally deferred.

OK whew. I thought I might have been misreading it when I did my best attempt to guess what goes where :). But I guess not.

The modules which are not marked as ghc-internal should only be deprecated after their contents are available in a non ghc-internal location.

For Ben's (4), no --- some things are just completely internal/unstable and there need not be any other place to get them, But for the others 3 categories, yes, I agree!

---

I have no idea what things are in which category; I just know they are GHC.* modules and the module docs now have a scary instability message. I welcome any and all suggestions about what should go where; I just want to drive this to a conclusion :)

[bgamari]

For Ben's (4), no --- some things are just completely internal/unstable and there need not be any other place to get them, ...

For what it's worth, I don't see any harm with using a deprecation cycle for things in class (4); none of these deprecations are particularly urgent, as far as I can tell.

I have no idea what things are in which category; I just know they are GHC.* modules and the module docs now have a scary instability message. I welcome any and all suggestions about what should go where; I just want to drive this to a conclusion :)

I'll try to come up with a concrete set of proposed changes to your list today.

[Ericson2314]

For what it's worth, I don't see any harm with using a deprecation cycle for things in class (4); none of these deprecations are particularly urgent, as far as I can tell.

Oh I didn't mean no deprecation cycle; I the CLC still wants one. I just mean that the message rightly would say "Use ghc-internal" because there is no more stable place to get the item, by definition of the item being in class (4).

I'll try to come up with a concrete set of proposed changes to your list today.

Great! I put it in a gist https://gist.github.com/Ericson2314/58ddea784f19705ef79651c0ad00141c in case that is useful for you :)

[Bodigrim]

I would strongly recommend to start with something as limited and uncontroversial as possible; we can always deprecate more modules in subsequent proposals. There is no reason to keep the proposal stalled until someone figures out the definitive list of modules to deprecate.

[Ericson2314]

@Bodigrim I'll gladly chop down my table, but I don't know what to chop. I don't know which things are controversial.

I am not up to date with the contents of individual deprecations, nor do I particular want to be, I just want to see the process move forward.

[Bodigrim]

No one knows upfront what will happen to be perceived as controversial, even my reading of the room is often off.

As a suggestion, the first table above seems most uncontroversial to me. It's a modest step, but a step forward nevertheless.

[Ericson2314]

@Bodigrim the big first table?

[Bodigrim]

@Ericson2314 yes.

[Ericson2314]

@Bodigrim OK I updated it (and the gist I linked before)