diff --git a/0011/README.md b/0011/README.md new file mode 100644 index 0000000..1272384 --- /dev/null +++ b/0011/README.md @@ -0,0 +1,92 @@ +--- +id: 0011 +title: how to announce a breaking change for Tinkerbell +status: published +authors: Gianluca Arbezzano +--- + +## Summary + +A breaking change (short bc break) is a planned update that breaks compatibility +for a feature or a piece of code. What was working before, won't work the same +way after a bc break. They are sometime needed to simplify a functionality, remove +feature not needed or to fix wrong decisions. + +At this stage, where the various services are not released and do not have +semver we can accept BC break. + +We need to have a consolidated way to communicate them. + +## Goals and no-Goals + +Goal: + +* Clarify the way we can communicate bc break across services in Tinkerbell. +* A solution with low overhead that has to work NOW. + +No-Goal: + +* Explain how SemVer manages Bc-Break or how we will communicate bc-break when + SemVer will be in use. +* Explain how a component should communicate bc-break to their community. + +## Content + +Even if we do not expect many BC break the possibility to remove or change a +functionality is a luxury that won't stay for long. We can do it right now, +because we did not release a stable release yet and community is coming with +more and more use cases and requests that will may be better to achieve giving +only one way to do things. + +Even if we don't have a day for the first major release of Tinkerbell or for the +other component I doubt it will be next week, this means that BC break are +expected and the way we communicate them makes the difference between an happy +community manager and somebody who looks for a different solution. + +Every PR that introduce a BC break will get labeled with a `bc-break` label. In +this way we will be able to build a workflow that programmatically will extract +the BC-Break for every component. + +Every PR has to contain as part of the description a section titled: +"how to migrate" teaching the user about how it should pass from a previous +version to a new one when possible. If not possible because the section will +explain why we remove the entire functionality and will offer an alternative if +it exists. + +### How To Migrate + +The "how to migrate" section has to be placed in the PR description. Here a few +things you should include: + +1. You have to be clear about the required steps. +2. You can write a bash script if necessary that can be used to perform + the migration. +3. This chapter is the documentation users will rely on when performing an + update. You should explain how to validate if the migration went right. +4. If a bash script is not enough feel free to implement a new binary, even + better if it has a `--dry-run` approach that can be used to validate the + action that will be performed without having to do them straight away. +5. We know that updates are crucial, and critical, sometime it is better to have + the best written format of what it is required vs a too magic bash script +6. Something like + [coccinelle](https://en.wikipedia.org/wiki/Coccinelle_(software) or [`go + fix`](https://golang.org/cmd/fix/) should be evaluated as well. + +### Share And Aggregate BC Breaks + +With the idea that every component should be independent and interchangeable I +don't want to write as part of this PR how boots, osie will have to communicate +their BC break to the outside, but we need to agree at minimum to be able to +communicate them to the all Tinkerbell community. + +[tinkerbell/sandbox](https://github.com/tinkerbell/sandbox) is the way the +community interacts with Tinkerbell following the documentation (not true yet +but very soon). The sandbox project will follow a semver and it will bump a +major release when required, in general it should report as part of the +changelog the bc-break from the underline component. + +## System-context-diagram + +## APIs + +## Alternatives