Add 3.3.0 announcement

[Kordyjan]

No description provided.

[julienrf]

Would it be possible to show the compiler output in such a case?

[sjrd]

Consider using the following explicit subsections for this section:

1. Language changes
2. Developer experience improvements
3. Standard library additions

We must make extra clear what is language and what is not language, as it confuses users too often.

[tgodzik]

We should make things clear what is a language feature for sure, but maybe we can have some tags instead? The sections might comprise of a single point, so that seems very formal for the sake of it being formal.

[sjrd]

I think having a section with a single point is good. It makes it very obvious that there is actually very little that changes in the language (contrary to what we can read left and right).

[sjrd]

This should come earlier, as it is the only thing that may potentially have an impact on existing codebases during the upgrade process. Everything else is things you can profit from after you've upgraded.

In the Scala.js release notes, we have an explicit "Changes with compatibility concerns" section before a "What's new" section. See for example https://www.scala-js.org/news/2023/01/26/announcing-scalajs-1.13.0/. Consider doing the same here.

[tgodzik]

On one hand it will be useful to have a list of things that might cause issues when updating, but maybe we can add it as a later section and let people know at the start?

"For compatibility concerns look to..."

This way we can first focus on things that are most interesting to users?

Also if lazy vals are an internal thing, so maybe it should on be in the same section? Or have a section with Impactful changes for x.y.z release? If the new lazy vals are not working then it's a bug and if we say that it's compatibility concerns that might cause people to think that something changed that might make their code stop compiling, while it's actually very unlikely.

[sjrd]

This way we can first focus on things that are most interesting to users?

Not every user has the same interests. When I upgrade something, the first thing I want to know is: is there anything I should pay attention to while I upgrade? 90% of the time, that's all I care about in release notes of software I use. The "exciting stuff" is not interesting to me in that scenario.

[tgodzik]

A clear link and mention should be ok then, no? I think a lot of people might be interested about the "exciting stuff" so it would be good to cater to both demographics.

[sjrd]

Yes, sure. At the end of the day, it's a matter of opinion. If you prefer to show the exciting stuff first given those considerations, go for it. ;)

[sjrd]

This is also for the "Changes with compatibility concerns" section.

You probably want to make it more explicit that this a bug fix (so OK to do in a minor version), but for which we have already noticed existing problems in the wild, and so we're helping users by proactively giving them more information on how to deal with it.

[Kordyjan]

I've applied all the language suggestions. Now I'm thinking about the structural changes suggested by @sjrd. if I understand them correctly, we would end up with a structure like this:

- What does "LTS" mean?
- Changes in Scala 3.3.0
  ├── Changes with compatibility concerns
  │   ├── New lazy vals
  │   └── Stability of inline parameters
  ├── Language changes
  │   └── More consistent braceless syntax
  ├── Standard library changes
  │   └── `boundary` and `break`
  └── Usability Improvements
      └── Linting
          ├── Checking for unused values
          └── Checking for discarded values
- Should I update to Scala 3.3.0

I see a bunch of problems:

• we are starting with things affecting only a very minor fraction of the users. New lazy vals are mostly implementation detail. The stability of inline parameters affects only a few libraries from the Open CB and probably even fewer end-users.
• The most important and most asked-for feature of the release - linting - is near the end of the text, and some readers may even miss it completely, especially since the sidebar is showing only two levels of headers.
• I think putting "new lazy vals" in the same category as known source incompatibility will be confusing. One of them always requires changes in the source code of affected projects, and the other should be practically transparent for the user and not require any action except for extraordinary cases that can be considered bugs.
• There is a split between "Should I update..." and "Known incompatibilities", which should be grouped together as they are targeting the same group of readers, and reading both of them are required to have a full picture of migration.

If others agree, I'm ok with removing the second example from the boundary/break section.

[julienrf]

I think Sébastien’s suggestion makes sense. You could start with a section “Release Highlights” (just before “Changes with compatibility concerns”) with a summary of the high-impact changes for the end-users (like sbt does). I also agree with removing some content from the boundary/break section.

[sjrd]

• especially since the sidebar is showing only two levels of headers.

To address that specific concern, you can remove the heading "Changes in 3.3.0" and move everything under it one level up. It's the release notes for 3.3.0, so we already know that "changes" are about 3.3.0.

[prolativ]

Maybe we should not comment out these erroneous lines as the purpose of the snippet is to show compilation errors?

[sjrd]

@Kordyjan I see the conversation has a bit stalled regarding the ordering of things. At the end of the day, this is a matter of opinion about what message you want to send first. You're the one in charge, here, so if you prefer to send the positive stuff first, by all means do it.

Irrespective of the ordering, @julienrf's suggestion of having a highlights section with links to every section (in a table of contents kind of way) sounds like a good idea.

[Kordyjan]

I think the sticky navigation on desktop / table of content on mobile serves as a good outline with links:

[julienrf]

The content is fine to me, even though there are still some relevant (IMHO), unaddressed comments. Could you please show how the image is rendered on desktop screens and mobile devices?