Proposals for naming and package structure

[NthPortal]

Proposals:

1. Only names that are planned to exist in a future Scala release can be outside of a next (sub-)package. Names that will not exist in a future Scala release MUST be in a next (sub-)package.
   a. Corollary: Extension methods MUST go in next (sub-)packages.
   b. Possible extension: All names that are planned to exist in a future Scala release MUST be outside of next (sub-)packages.
2. Extension method value classes SHOULD be named Next<Name>Extensions, where <Name> is the name of the type.
   a. For example, extension methods for LazyList would go in value class named NextLazyListExtensions.
   b. Extension method value classes for an object that is a companion SHOULD be named Next<Name>CompanionExtensions.
   c. Extension method value classes for general collection types (e.g. Map, Set) should have have a prefix to <Name> that is the first letter of each package segment (e.g. NextSCISetExtensions for scala.collection.immutable.Set)

Something something RFC 2119

[sjrd]

Names that will not exist in a future Scala release MUST NOT be outside of a next (sub-)package.

The triple negation was very hard for me too read, and I understood it the wrong way the first two times I read the sentence. Perhaps consider:

-Names that will not exist in a future Scala release MUST NOT be outside of a next (sub-)package.
+Names that will not exist in a future Scala release MUST be inside of a next (sub-)package.

[NthPortal]

I don't know why that slipped by me. yes, fixed

[BalmungSan]

@NthPortal How should the object holding the value class be named? Just <Name>Extensions?
So for example, if I want some additional methods on LazyList I would import scala.collection.immutable.next.LazyListExtensions._?

[NthPortal]

IMO, it can go directly in the package object.

[BalmungSan]

@NthPortal so importing next._ would import all extensions?

[NthPortal]

correct. and if you wanted to import just one, you'd import next.NextLazyListExtensions or whatever

[martijnhoekstra]

Having to import next.something would mean that cross-building 3.0/3.1 won't be possible unless we ship this with empty next instances for 3.1. that'd be lame.

[NthPortal]

then just import next._

[SethTisue]

would -Yimports:... be helpful here, when cross-building? as a way of allowing the imports to be different in different Scala versions, as needed, without the user having to alter their actual source code? (cc @som-snytt)

[martijnhoekstra]

Then you'd still need to ship a version with an empty next package for 3.1. which means inflicting the transitive dependency on your dependents.

That can be sort of worked around with people taking a provided dependency for 3.1.

[sjrd]

Having to import next.something would mean that cross-building 3.0/3.1 won't be possible unless we ship this with empty next instances for 3.1. that'd be lame.

I think that shipping empty next instances is exactly what we'll do.

Anyway, they probably won't stay empty as we then start adding new stuff coming in 3.2 or later.

[martijnhoekstra]

Julien suggested on #25 that there wouldn't be 3.2 stuff in this library.

Per version -Yimports is probably at least as invasive/cumbersome for users as having the lame dependency on the empty next package and declaring it provided for 3.1.

[NthPortal]

I've noticed we still have a shadowing problem for names which appear in multiple packages (e.g. Set, Seq), so I've updated the proposals to account for that

[BalmungSan]

Did you come to a conclusion about this?

So I could update #23 and open a follow up for groupByTo & groupMapTo

[NthPortal]

Vote by reacting to this comment (see the following comment for more granular votes)

In favour of (👍) or against (👎) proposal 1 in its entirety

In favour of (🚀) or agains (👀) proposal 2 in its entirety

[NthPortal]

Granular votes (by reacting):

In favour of proposals 1 and 1a but against 1b (👀)
In favour of proposals 2 and 2a but against 2b (👎)
In favour of proposals 2 and 2a but against 2c (😕)

[SethTisue]

This all looks good, except I don't know what I think about 1b. What are the pros and cons there?

[NthPortal]

I'll give an example of something that 1b affects.

Currently, scala.collection.concurrent.Map does not have a companion, unlike other Map types (see scala/bug#12115). We cannot add it in that package in scala-library-next, because the companion needs to be in the same compilation unit. If we were to add such a companion, it would have to be an object Map in package scala.collection.concurrent.next; however, that would violate 1b.

If we were to reject 1b and add s.c.c.next.Map, we would need an alias val Map = s.c.c.Map in package s.c.c.next in the Scala 3.1 version of this library, and couldn't just have an empty package.

---

As I see it,

Pros: simplicity

Cons: reduces the total set of possible changes/fixes/improvements

[NthPortal]

follow-up at #46

[NthPortal]

I propose that we don't wait on finalizing this and #46 to merge PRs, and we can just refactor the library once we've decided on those.