Also, do we have some part(s) of the documentation where we discuss the concept of "binary compatibility"? It would be desirable from them to this newly created section.

https://docs.scala-lang.org/overviews/core/binary-compatibility-for-library-authors.html

I think it should be explained that the ability use pattern matching is lost if no unapply?

IMO this whole section belongs the guide on compatibility for library authors. Application authors never need to care about this.

nitpick: PR title has a typo (patter -> pattern)

Thanks for the feedback, I've reworked it.

There are parts of this pattern which are pretty repetitive and very regular:

• add a new constructor, private to the companion object, with the original fields (necessary, unless we want to deal with MiMa)
• add an apply factory method to the companion (necessary, unless we want to burden the class users with boilerplate)

Are these parts automatable using Macros? We would need the macro(s) to generate as many of these members as there areOptions in the case class (well, only theOptions that are on the right side of the case class constructor definition).

(Btw good things about this patten is that it seems to work with e.g. Circe for JSON codecshttps://scastie.scala-lang.org/huP4tCstQBufYKFwXUFs4Q )

Anything that needs to add members visible during typechecking cannot be done with macros.

@sideeffffect do you want to rework some parts or should we merge it as it is? (I am fine with both)

I thought we want to first finish theMiMa vs "private" primary constructors debate.

https://contributors.scala-lang.org/t/private-primary-constructor-vs-mima/6050/5

But I'm not against merging this documentation before. What do you guys think?

That’s a good point.

@smarter, what do you think about Sébastien’s suggestion of emitting the constructors as “package private” constructors? If we can do that, then I guess we would not need to add the MiMa exception anymore.

That would also be a binary breaking change which I assume mima would flag unless we special-case it in mima.

I assume MiMa already treats package private definitions like private definitions. If this is not the case, that should be fixed indeed. But then MiMa would not flag changes to the class constructors if they are emitted as package private. Of course, code compiled with a new version of the compiler (emitting private case class constructors as package private constructors at the bytecode level) would be binary incompatible with code compiled with a previous compiler, so library authors would have to add a MiMa exception for that. But at least, the emitted bytecode would be more correct because it would become impossible to call the constructor from Java code.

I createdscala/bug#12711 andscala/scala3#16651 to track the issue with private constructors that are still public.

We could add a note about that in the documentation, what do you think?

I did another pass and made some final adjustments. I think the guide is ready to go now.

This doesn't mention defining a new apply method in the companion (and keeping the old one) after adding the address field

Minor thing, fix word ordering to be "this makes the copy method private".

Thank you for the review,@bishabosha and@bjornregnell, I’ve addressed your comments ina818702