search

haskellfoundation / tech-proposals

The Haskell Foundation Tech Proposal Process
Other
69 stars 29 forks source link

Module naming conventions for GHC base libraries #53

Closed simonpj closed 1 year ago

simonpj commented 1 year ago

This proposal suggests naming conventions for the libraries

Rendered form here

gbaz commented 1 year ago

Thanks Simon. All this looks pretty eminently rational to me. I especially like proposal 3 that we shouldn't go around renaming modules that already exist rapidly, but rather should over time have individual discussions as we start to disentangle things and migrate them across packages.

simonpj commented 1 year ago

I think that only six people have contributed to this discussion so far. I bet that many more have an opinion. Please do say what you think! Reminder:

This proposal suggests naming conventions for the libraries

Rendered form here

simonpj commented 1 year ago

I'm also in favour of the .Experimental suffix. I imagine Data.List.Experimental could re-export the contents of Data.List and add some extra experimental goodies; it's then a very small delta to switch between import Data.List and import Data.List.Experimental, whereas import Experimental.Data.List would appear somewhere completely different if imports are sorted.

So to be clear, you advocate:

Is that right? It seems superficially inconsistent, and yet each on its own makes sense.

Modules in the ghc library (GHC API) are all called GHC.* (e.g. GHC.Tc.Gen.App) and I don't think we can change that.

What do others think? It's all about what colour to paint the bikeshed, but we do need to agree it, otherwise we'll get a mess of inconsistent approaches in different modules.

adamgundry commented 1 year ago

So to be clear, you advocate:

  • Use a .Experimental suffix in ghc-experimental
  • Use a GHC.Internal. prefix in ghc-internals

Is that right? It seems superficially inconsistent, and yet each on its own makes sense.

Exactly. I'm not particularly worried about making these consistent, since they serve quite different purposes.

michaelpj commented 1 year ago

Is that right? It seems superficially inconsistent, and yet each on its own makes sense.

I think there is a logic to it:

numlit2 commented 1 year ago

Use a .Experimental suffix in ghc-experimental

Data.List.Experimental is not as strong as Experimental.List. In a code review with sorted imports scattered X.Y.Experimental are easier to miss than a group of Experimental.*.

If you want to optimize for experts do X.Y.Experimental, if you want to make it more obvious and easier to spot use Experimental.*. I think the introduction of unstable dependencies should be as prominent as possible.

tek commented 1 year ago

it would be possible to expose both…

nomeata commented 1 year ago

if you want to make it more obvious and easier to spot use Experimental.*

Or EXPERIMENTAL. maybe? Too bad we can't include ⚠️ in the module name.

JakobBruenker commented 1 year ago

Instead of relying on the module name to warn users, another solution could be to add {-# WARNING in "x-experimental" Data.List.Experimental "<some message>" #-}, and have users use Wno-x-experimental if they are sure they want to use it. I don't think we currently have module-scoped warnings though. (Edit: I think technically https://github.com/ghc-proposals/ghc-proposals/pull/134 allows you to do this, although probably not in a super convenient way)

vanceism7 commented 1 year ago

I like the idea of X.Y.Experimental, it feels more appropriately categorized and I kind of doubt someone would miss it. A simple search/replace would probably find them anyways. Perhaps we could even add an experimental warning flag that could be triggered on when desired so the compiler could show warnings for anything deemed experimental that was being used in the code.

On another note: I'm just bike-shedding here, but it seems like ghc-experimental should actually be called "base-experimental". Because the code living in it has a life-goal of moving into base, and users are encouraged (or atleast not forbidden) to use it in their own code.

I think this naming change helps to enforce the policy that users shouldnt be depending on ghc libraries but the base libs instead

tomjaguarpaw commented 1 year ago

it seems like ghc-experimental should actually be called "base-experimental". Because the code living in it has a life-goal of moving into base

Whose life-goal? If anyone's, it's the goal of GHC HQ. It's not the goal of CLC, who have purview over base. Therefore I don't think the name "base" should be co-opted here.

users are encouraged (or atleast not forbidden) to use it in their own code

I truly hope the name "ghc-experimental" sounds discouraging because I wouldn't like users to depend on this library lightly!

vanceism7 commented 1 year ago

Whose life-goal? If anyone's, it's the goal of GHC HQ. It's not the goal of CLC, who have purview over base. Therefore I don't think the name "base" should be co-opted here.

I truly hope the name "ghc-experimental" sounds discouraging because I wouldn't like users to depend on this library lightly!

ghc-experimental definitely sounds like it's something users shouldn't be referencing in their code. Even base-experimental sounds pretty scary to me. But the quote from the rendered makes it seem like it's ok to use it

  • 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.
  • It is user-facing (user are encouraged to depend on it), but its API is less stable than base.

Based on that wording, it sounds like the intent is that the code from experimental eventually matures and takes a home in base, and that it's ok to use it with the warning that it might change on you.

If that's the case, I think base-experimental is more appropriate. If it's supposed to be super scary and normal devs shouldn't be depending on it, then I agree with calling it ghc-experimental. But ghc-experimental sounds like it shouldn't even be user facing

Bodigrim commented 1 year ago

I'm just bike-shedding here, but it seems like ghc-experimental should actually be called "base-experimental". Because the code living in it has a life-goal of moving into base, and users are encouraged (or atleast not forbidden) to use it in their own code.

It seems you are reading the purpose of ghc-experimental as being a staging ground for inclusion into base. I don't think it's correct: the primary goal for ghc-experimental is to experiment with API required to implement GHC proposals. It may never end up in base (after all, it is only aspirational, "ultimate" goal to do so), and it's more likely than not that, building upon results of experiments, the final design approved for inclusion in base will be much different from one in ghc-experimental.

If it's supposed to be super scary and normal devs shouldn't be depending on it, then I agree with calling it ghc-experimental.

It depends whether experiments scare you, right? If you depend on ghc-experimental, you agree to participate in an experiment. Sure, this experiment is not supposed to be "super scary", and it is designed to bring positive outcomes in mind, but there is always a chance, and we want consumers to be conscious about it.

The heuristics is simple: ghc-internal for GHC developers, base for CLC, and ghc-experimental for GHC Steering Committee. If there is ghc in the package name, it is guided by a community body with GHC in its name. I'm quite strongly opposed to renaming to base-experimental.

vanceism7 commented 1 year ago

I'm just bike-shedding here, but it seems like ghc-experimental should actually be called "base-experimental". Because the code living in it has a life-goal of moving into base, and users are encouraged (or atleast not forbidden) to use it in their own code.

It seems you are reading the purpose of ghc-experimental as being a staging ground for inclusion into base. I don't think it's correct: the primary goal for ghc-experimental is to experiment with API required to implement GHC proposals. It may never end up in base (after all, it is only aspirational, "ultimate" goal to do so), and it's more likely than not that, building upon results of experiments, the final design approved for inclusion in base will be much different from one in ghc-experimental.

If it's supposed to be super scary and normal devs shouldn't be depending on it, then I agree with calling it ghc-experimental.

It depends whether experiments scare you, right? If you depend on ghc-experimental, you agree to participate in an experiment. Sure, this experiment is not supposed to be "super scary", and it is designed to bring positive outcomes in mind, but there is always a chance, and we want consumers to be conscious about it.

The heuristics is simple: ghc-internal for GHC developers, base for CLC, and ghc-experimental for GHC Steering Committee. If there is ghc in the package name, it is guided by a community body with GHC in its name. I'm quite strongly opposed to renaming to base-experimental.

Got it. I totally agree with the logic. I think some of those finer points should be included in the description of ghc-experimental just to make it a little more clear. Thanks for the explanation!

nomeata commented 1 year ago

The heuristics is simple: ghc-internal for GHC developers, base for CLC, and ghc-experimental for GHC Steering Committee. L

The apparent inevitability of Conway's Law amazes me every time.

simonpj commented 1 year ago

I have done a full refresh of this library-module-naming-convention proposal, and pushed the result.

I think we are done. Any final thoughts?

bgamari commented 1 year ago

I, for one, am quite happy with where this proposal ended up. Thanks, @simonpj!

Ericson2314 commented 1 year ago

I am too.

Thanks @simonpj!

simonpj commented 1 year ago

Great -- let's take this proposal as decided.

gbaz commented 1 year ago

merging as approved.