docs: add breaking changes policy document - #3147
Conversation
Introduce breaking_changes.rst, documenting S-COREs policy for breaking changes.
github-project-automation
Bot
added this to
TLC - Technical Lead Circle and S-CORE Roadmap
|
The created documentation from the pull request is available at: docu-html |
| There may be rare cases where a breaking change cannot be avoided, even if deprecation was considered. | ||
| In such cases: | ||
|
|
||
| * The commit introducing the breaking change **must** clearly state that it contains a breaking change, |
There was a problem hiding this comment.
Here I would suggest adding some sort of distinct tag to the git commit below the commit message like "BREAKING CHANGE", like described here
| #. The functionality that the new addition is meant to replace is marked as deprecated (e.g. via | ||
| language-specific deprecation attributes/annotations, documentation notes, and/or compiler or linter | ||
| warnings), so that users are made aware of the planned removal as early as possible. | ||
| #. Users are given a **grace period** during which both the deprecated and the new functionality are |
There was a problem hiding this comment.
we have to specify the length of the grace period. for example for semver usually deprecated symbols are only removed on major releases.
| behaving unchanged. Only once the announced grace period (e.g. tied to a number of releases or a | ||
| deadline stated in the deprecation message) has elapsed may the deprecated overload be removed. | ||
|
|
||
| Handling Unavoidable Breaking Changes |
There was a problem hiding this comment.
I would welcome if we add a section for purposefully unstable API:
Sometimes new features are introduced with an API where not enough experience is gained yet. Forcing migration paths via deprecations at that moment will slow down development significantly.
Such APIs should be marked either in code or in the release notes as unstable/experimental.
This is a warning to users, that depending on these APIs is a maintenance risk on their side, since API may break at any moment in any way without notice or migration paths.
2 participants
Introduce breaking_changes.rst, documenting S-COREs policy for breaking changes.