Add Breaking changes page

[MaryaBelanger]

Part of dart-lang/sdk#52828:

Add a new web page and populate it with past and currently planned breaking changes and deprecations.

Flutter documents past and upcoming breaking changes in a nicely discoverable web page here...While the same information is available for Dart via the CHANGELOG, we'd like to provide a similar page for Dart.

Plan:

• The goal is just to have a breaking changes page that's easily accessible/discoverable for users (currently, the change log is the only place that info is collected). We don't need to recreate Flutter's whole implementation.

• The CHANGELOG will stay in the sdk repo, and won't be duplicated on the site in any way.

• The new page will be modeled after Flutter's:

  • "Not yet released to stable" section for planned breaking changes
  • "Released in Dart x.x.x" sections, descending order, most recent at top

• Past breaking changes per release will need to be pulled in to the new page to populate past release sections.

• For now, we've decided to link to the change's corresponding issue (like the change log does now).

  • I think we should revisit this; individual migration guides per breaking change seem like they could be very useful.
    • But, there are so many very very minor breaking changes, requiring a page be written for each one is too much.
  • I've personally found in the past that change issues aren't always a straightforward means of understanding the work, outcome, steps to take, etc.
    • But, breaking change issues have always followed a more stringent outline than others, so it's probably ok.
  • At the very least, evaluating whether a page might need to be written should be part of the new breaking change process.

[MaryaBelanger]

I'm going to revise the initial proposal and my questions based on some context I've gained:

• CHANGELOG is definitely not leaving the sdk repo, no perceivable value of duplicating it on dart.dev at the moment
• Breaking changes page will be just an index for the most part
• Link to issues of the changes
• Part of the process can be determining whether a more long form individual breaking change page will be necessary.
  • In those cases, we can use the template Flutter uses

So, new questions are:

• Structure of the breaking changes page
  • Do we want a Not yet released section like the flutter page?
• Assuming it will still be the engineers responsibility as part of the breaking change process to add the bullet point and link to the breaking changes page
• Placement of the new page in the sidenav
  • I like Flutter's new sidenav organization of these pages:
    
    But that might be overkill for now, since this is basically just adding a single index to point off the site. Possibly just put it under Resources.

TODO:

• Create the new page and decide it's placement in the side nav
• Populate release sections with past a currently planned breaking changes, linked to issues.

[parlough]

Do we want a Not yet released section like the flutter page?

I do think this is useful as it gives users a chance to prepare and make preparatory changes for breaking changes, potentially avoiding issues completely, or at the very least to be aware of it so it doesn't come out of nowhere.

Link to issues of the changes

So you think the breaking change index should only link to the issues? Or just for the breaking changes from before this plan?

I was originally thinking each breaking change would have its own page with background information and migration guide, even if small for consistency, similar to the Flutter version. Then that page could link to the related issues and change lists/pull requests. However, perhaps it makes sense for simple ones to just link to the issue, not sure.

Edit: Thinking about it more, perhaps keeping it in the issues and linking to them is easier while reducing duplication. We would just need to make sure the issues are clear about migration path.

[MaryaBelanger]

So you think the breaking change index should only link to the issues? Or just for the breaking changes from before this plan?

So, I just asked some of the Dart team leads and they said this is what they were imagining. I was previously imagining what you described, the way Flutter does it, because I think that's a really useful kind of documentation. But my question was more along the lines of "do you see your engineers writing that kind of documentation and will that be part of the official breaking change process" and the answer was basically no, along the lines of:

• The majority of their breaking changes are not so significant that a page like that would have enough info to fill out even minimally.
• (I'm adding this one/projecting, but I feel like the general vibe is...) That's kind of a lot to ask / could turn into significant overhead for engineers for the return that content would add to typical Dart breaking changes.

They did say they might consider an optional step in the release process that would ask whether a page dedicated to the topic would be useful. I think that could even be something I could circle back with engineers on, if I see a breaking change added that I think could use a long-form page but maybe they opted against it, I can ask them to do so anyway.

We would just need to make sure the issues are clear about migration path.

Definitely, and that's something we could call out in the index page intro too, e.g. "Click on the change link for migration steps, etc." If we find that's often not enough for users, or users are following those links but still have questions, we should revisit making the dedicated pages part of the official process

[parlough]

Thanks for the clarification. That makes sense and sounds great to me! Especially with a clear question during the process if a dedicated page is necessary.

[MaryaBelanger]

@leafpetersen do we want to do something like Flutter's "Deprecated APIs removed after..." entries in Dart's breaking changes list too (e.g.)?

[Hixie]

IMHO, GitHub/Gerrit PRs and issues are not really suitable for user-facing documentation. They're appropriate for people who want to become part of the team and contribute. It's like giving someone galley proofs instead of a bound volume when buying a book. Or having theatre crew wear jeans and a t-shirt and walk onto the stage to move the set between acts. It's just uncouth. :-)

Another reason I would avoid sharing issue links in user-facing documentation is that we have literally millions of users and if even 0.01% of our users comment on each issue we link to, that's still >100 comments per issue.

FWIW, part of the reason Flutter has the rule about writing migration guides (which are expensive to write) is to discourage us from making breaking changes. The more expensive we make breaking changes for us, the more careful we are about making them. The overhead is intentional.

[leafpetersen]

@MaryaBelanger This is great, thanks! I left a number of smaller comments. My main feedback is that I think we should include deprecations in the list. For deprecations, there are two steps.

• First, we deprecate a thing. This is not a breaking change (by our policy), but I think it would be useful to include on this page since it is essentially advance notice of an upcoming breaking change. Something like [Deprecation]: Remove the FooBar.baz constructor.
• Second, we eventually remove the deprecated API. This doesn't need any special marking, it's just an ordinary breaking change at that point (usually unversioned).

[leafpetersen]

@Hixie

Another reason I would avoid sharing issue links in user-facing documentation is that we have literally millions of users and if even 0.01% of our users comment on each issue we link to, that's still >100 comments per issue.

I hear the concern about getting overwhelmed by comments, but I feel fairly strongly that at least for the time being we should link to the breaking change issue somewhere in the documentation. There should be a path for users to comment and provide feedback. If and when we reach the point where the volume of comments is too high, we can reconsider.

IMHO, GitHub/Gerrit PRs and issues are not really suitable for user-facing documentation.

This is fair. We have in general on the Dart side adopted a bit more of a "close to the metal" approach than Flutter has, but I'm open to making this a bit more polished (i.e. have a dedicated subpage). My main concerns are 1) not making people do to much pointless busywork writing up the same text in two different places (the issue, and then the doc page), and 2) ensuring that we have a process in place to keep things in sync and up to date.

For 1) - I'm not interested in imposing busy work on people just to discourage them from doing breaking changes. Doing a breaking change is already highly punitive, it usually requires some poor soul to propose, document, and make the change, break flutter, revert the change, try to fix flutter, repeat for a while; then do the same for google3, etc etc. Adding busy work is a non-goal, and writing the same text twice in two different places feels like busywork (proposers of breaking changes already have to fill out an issue with details, mitigation, etc). So if we do this, I'd like it to be quite low overhead. @MaryaBelanger would it be easy to just provide a simple template and a quick workflow, so that when a change is approved, the proposer could just take the already written text from the github issue and fairly quickly fill in a template and upload it as a PR? An alternative would be to just create that page at the start and have the github issue just link to the web page, but I'm concerned about losing history on proposals that get rejected.

For 2), @itsjustkevin thoughts on this?

[MaryaBelanger]

Updating remaining ToDo for me (7/24):

• Add "deprecations" section/call-out styling to Add breaking changes page #5061
• Write instructions for adding to breaking changes page, including the guidelines already written in 5061 description
  • Will live in site-www somewhere
• Create a template for individual breaking change pages, also in site-www, for engineers to copy and paste their breaking change issue contents into, link to it from the instructions page
  • Will match the breaking change issue template exactly
• Update sdk process page step 3 to point to instructions here
• Update sdk process page step 1 to emphasize importance of using the breaking change issue template exactly as templated, maybe add notes/directions to the template itself to help enforce the standardization