Communicating breaking changes

** Note: This page is currently a work in progress **

How do we communicate breaking changes?

In order to inform our users of breaking changes in FluidFramework, we utilize the BREAKING.md file located in the root of the repository. For each breaking change, there should a corresponding note explaining the change. These notes fall into two categories: Breaking Changes and Upcoming Changes.

Breaking Changes vs Upcoming Changes

Breaking changes are changes included in the release version it is listed under. For example, if a breaking change note is under the "2.0.0 Breaking Changes" section, then that change will be included in major release 2.0.0. An important note to remember is that breaking changes will only be present in major releases.

Upcoming changes are changes that will not be present in the next major release but will be eventually manifest in a future major release. A common example is announcing the deprecation of an API that will be removed in a future release.

Writing a breaking change note

Notes on breaking, upcoming, and otherwise interesting changes go here. They will be reviewed and published along with each release. Published changelogs may be found on the docs site at fluidframework.com.

Upcoming changes include anything expected to become a breaking change in the future. It can include deprecations, optional to required transitions, etc. They should be added to the section for the version in which they are being announced.

Breaking changes include anything that a consumer upgrading to the specified version must account for as part of the upgrade process. It can include expected compile time breaks, runtime compatibility breaks, etc. They should typically be announced as an upcoming change in an earlier version before becoming a breaking change.

Communicating the reasoning for a breaking change

It's important to communicate to our users why a breaking change took place and how it will ultimately benefit them. We do this because it will give users more motivation to bump their version of FluidFramework despite the extra work it may take to integrate the breaking changes included. We often will need to provide a more in-depth explanation, which is too long for a breaking change note in BREAKING.md. Instead, we should write it in the What's New section on FluidFramework.com.

Writing a change note

Use the following guidelines when constructing a breaking change note in BREAKING.md:

• Provide a concise title. It should be clear what the topic of the change is.
• Ensure the affected packages are named or clearly identifiable within the body.
• Provide guidance on how the change should be consumed if applicable, such as by specifying replacement APIs.
• Consider providing code examples as part of guidance for non-trivial changes.
• Avoid using code formatting in the title (it's fine to use in the body).
• To explain the benefit of your change, use the What's New section on FluidFramework.com.

Below is an example of a breaking change note using these guidelines.

## 2.0.0 Breaking changes

  - [Remove connected property from IContainer](#Remove-connected-property-from-IContainer)

### Remove connected property from IContainer

The `connected` field will be removed from `IContainer` in the `@fluidframework/container-definitions` package. 
It was deprecated in 1.0.0 and will be removed in 2.0.0. 
Please use `IContainer.connectionState` instead (see example below). Note: `ConnectionState` can be imported from @fluidframework/fluid-framework.


```diff
- if (container.connected) {
+ if (container.connectionState === ConnectionState.Connected) {
    console.log("Container is connected");
}
```