Add breaking change/deprecations documentation and update process

[leafpetersen]

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 (and have agreed to as part of a larger effort around unifying breaking change policies) provide a similar page for Dart. We would like to finish this by the end of Q3 if possible. This issue is to track the overall arc of work, including process updates and documentation changes. The specific tasks that I believe are involved here are as follows:

• Add a new web page (presumably on dart.dev?) and populate it with past and currently planned breaking changes and deprecations: Add Breaking changes page  site-www#5048
  • https://dart.dev/resources/breaking-changes
• Update the breaking change policy documentation to link to the new web page. #52883
• Update the breaking change process documentation with steps to ensure that new breaking changes and deprecations, when approved, get listed on the web page. #52884
• Update the release process to include a step to move released breaking changes to the appropriate entry on the web page. #52885

@itsjustkevin Do you run the breaking change flow? I think the second and third entries above might fall onto you? The fourth might be you, or @athomas ? Would you like me to file separate issues for these?

@MaryaBelanger @atsansone Is the first task something that you can/should handle, or is there someone else I should ping? Would you like me to file a separate tracking issue somewhere?

@Hixie do you think we should include Dart breaking changes on the Flutter page? Or just add a link to the new Dart page?

@devoncarew is there anything we should do for Dart maintained packages here as well?

cc @mit-mit @lrhn @vsmenon

[Hixie]

@Hixie do you think we should include Dart breaking changes on the Flutter page? Or just add a link to the new Dart page?

I would just add a link from https://docs.flutter.dev/release/breaking-changes to the Dart page. Duplicating the content will just double the chances of mistakes, IMHO.

[MaryaBelanger]

Is the first task something that you can/should handle...? Would you like me to file a separate tracking issue somewhere?

Yeah absolutely. I'll file the issue and link to it here.

(edit: link and removed a question here that we can discuss on the site-www issue)

We would like to finish this by the end of Q3 if possible.

Sounds good, I'll start working on it once you approve the layout/plan I come up with in the site-www issue.

[parlough]

Should breaking changes only behind a new language version be included on this page? Then again when support for that language version is dropped?

[itsjustkevin]

@itsjustkevin Do you run the breaking change flow? I think the second and third entries above might fall onto you? The fourth might be you

Update the breaking change policy documentation to link to the new web page.

Will do once we have the process settled in.

Update the breaking change process documentation with steps to ensure that new breaking changes and deprecations, when approved, get listed on the web page.

@MaryaBelanger I might need to work with you on this one.

Update the release process to include a step to move released breaking changes to the appropriate entry on the web page.

Don't think this one will need work from the release eng team.

[mit-mit]

#48596 is a related issue