BREAKME.md

If you are responsible for maintaining a semver-versioned piece of software, you might have come across a scenario where you believe a breaking change would lead to a better design, but you can’t because it would break the existing users of your software.

This is a need that we sometimes have when working on any of the Tuist repositories, and I found it a bit annoying having to note them down in issues that can get lost over time. The need for introducing a breaking change, and the rationale behind it, needs to be part of the Git history of the repository, close to the changes that prompted the developers to consider it. Therefore, I decided to introduce a new convention across Tuist repositories: a BREAKME.md file.

As its name suggests, it contains a list of breaking changes that we would like to introduce in the future. Every change should include what needs to be changed, and the rationale behind it. When working on future releases, developers can refer to this file to understand the breaking changes that we have been considering.

With that file, I feel more comfortable proposing breaking changes, since I know that they won’t get lost in the noise of issues and pull requests.