Make clear .Internal convention does not adhere to the spec

[hasufell]

No description provided.

[gbaz]

I generally support this, though I think it could use some tweaks to the language to be a bit less abrupt, and also perhaps add a bit more motivation (it is a faq after all)!

[bgamari]

Thanks for carrying this out, @hasufell.

[chshersh]

I'm slightly against this addition to the spec. Mostly for two reasons:

1. I don't think a spec should mention practices that it forbids. This list is never going to be exhaustive. Why not also say that modules like Data.*.MagicFairyDust should also follow PVP? The rules of the spec should be unambiguous to avoid specifying any specific examples not covered by the spec.
   • It's fine to provide examples but you wouldn't say in a cooking recipe that mentions "olive oil" to not use "sunflower oil" because it's not olive. Same here.
2. I still consider the .Internal module naming convetion a lightweight solution for dealing with PVP and Haskell shortcomings. There're no alternative that doesn't require more work and I will continue using .Internal modules in my packages to exempt from PVP because I can't afford to do more work unless I'm explicitly paid for it. Life of an OSS maintainer is already challenging enough, so it's often impossible to find the capacity for doing more work. And if some people will continue follow this convention, forbidding it won't help.

I suggest using positive language. The spec shouldn't forbid anything. In fact, it doesn't need to mention the .Internal module convention at all. Instead, the spec can simply encourage people to use the *-internal package convention if they want to expose the internals of their packages and follow PVP at the same time.

[tomjaguarpaw]

I'm slightly against this addition to the spec ... I don't think a spec should mention practices that it forbids

This is not an addition to the spec. It's an addition to the FAQ.

[hasufell]

Exactly. This is an addition to the FAQ on a best-effort basis. We introduce this, because it's wide-spread practice (that's ok), but we want to raise awareness that it's not PVP conform and we want to promote the alternative (the -internal package approach). Adding this to PVP FAQ gives this better visibilty.

[chshersh]

Sure, if it's FAQ than I'm fine with the addition.

[Bodigrim]

LGTM. Dear CLC members, any more opinions on this before we vote? CC @mixphix @parsonsmatt @angerman

[parsonsmatt]

I would rather have seen #46 merged and approved. The .Internal pattern is all over the place and significantly easier for library maintainers. I do see the value of the -internal package convention, and I do agree that it is better, but it's also significantly more work.

Being totally 100% PVP compliant is a difficult task, and I'd be surprised if >1% of Hackage packages were totally compliant (noting that a properly compliant package would require a minor bound on base if you're implicitly or openly importing the Prelude). So, sure, this pattern isn't PVP compliant, might as well add it to the FAQ as an explicit call-out, but it's really just another demonstration that the PVP is an annoying policy and inflexible to the actual needs of users.

[hasufell]

I would rather have seen #46 merged and approved.

That is entirely orthogonal to this issue (and I do not wish to discuss that here). Doing that would require a version increment of the spec.

The current versions of the spec do not permit that convention and there's no question about that. This PR just makes that more verbosely clear.

[Bodigrim]

@hasufell are you happy to trigger a vote? Or shall we wait for more opinions / discussion?

[hasufell]

I'm ok with triggering a vote.

[tomjaguarpaw]

+1 from me

[hasufell]

+1

[angerman]

While I'd much rather see proper annotations per binding for this. I agree that this is pretty much the community adopted convention. Thus until such a time where we have better mechanisms, this seems to just provide a bit more clarity around expectations, I guess.

Weak +1.

[Bodigrim]

+1 from me.

[Bodigrim]

@chshersh @mixphix @parsonsmatt just a gentle reminder to vote.

[chshersh]

+1

[mixphix]

-1. Should we expect all packages currently following the .Internal module convention to switch? If so, how soon? Surely we can't force such a change. And what would the effect be? That we stop using packages that adhere to the former? That dependents of internal functionality must import another package, trickling up through the ecosystem? The module-level demarcation is enough to indicate that functionality should be expected to break. Moving that to the package level just adds another obstacle for maintainers to navigate.

[parsonsmatt]

+1

The addition to the FAQ is technically correct, and the mention of the -internal pattern is a good step.

I do agree with @mixphix that we should change the spec to match the common practice, but that seems to be an orthogonal concern.

[Bodigrim]

Thanks all, 6 votes in favour are enough to approve.