-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add docs for our bc promise and our versioning
- Loading branch information
1 parent
5b7c7b1
commit 7232b78
Showing
5 changed files
with
71 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -9,4 +9,5 @@ infection.log | |
infection.html | ||
*.sqlite3 | ||
.deptrac.cache | ||
docs_php/ | ||
docs_php/ | ||
docs/.cache |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,46 @@ | ||
# Our Backward Compatibility Promise | ||
|
||
Our top priority is to ensure that upgrading your projects is seamless. To support this, we guarantee backward | ||
compatibility (BC) for all minor releases. This approach aligns with the principles | ||
of [Semantic Versioning](https://semver.org/). In essence, Semantic Versioning dictates that only major releases (like | ||
5.0, 6.0, etc.) can introduce changes that break backward compatibility. Minor releases (such as 5.1, 5.2, etc.) may add | ||
new features but must maintain the existing API structure of that version branch (for example, 5.x). | ||
|
||
To monitor if PRs are introducing BC breaks, we are | ||
using [roave/backward-compatibility-check](https://github.com/Roave/BackwardCompatibilityCheck) in our CI. This great | ||
tool notifies us if a BC break would be introduced by merging a given PR. It makes preventing these breaks in minor or | ||
patch versions so much easier. Big kudos to the [roave](https://roave.com/) team for this tool! | ||
|
||
If we know that we will break bc in the next major version, we will include deprecation messages in the code base to | ||
assist with the transition to the next major release. | ||
|
||
Not all BC breaks impact application code in the same way. While some require substantial changes to your classes or | ||
architecture, others may only involve minor adjustments, such as renaming a method. | ||
|
||
## Exceptions | ||
|
||
### Internal | ||
|
||
Some our classes or methods may be marked with `@internal`. These are then not covered by our backward compatibility | ||
promise. This is done to ease the development for us and should not impact you as a user in any kind. At the time of | ||
writing this hold only true for one of our classes. | ||
|
||
### Named Arguments | ||
|
||
There is also one exception we are doing regarding our BC policy: Name arguments. These are only covered for | ||
constructor parameters of our Attributes. Using PHP named arguments might break your code when upgrading to newer | ||
versions. | ||
|
||
### Experimental Features | ||
|
||
Sometimes we want to introduce more complex features or feature where we are not sure how the API should look like. In | ||
these cases we will mark the classes/methods as `@experimental`. We are doing this to get a better grip on how the | ||
feature could look like and to retrieve more feedback on them. Doing this period they are not covered by our backward | ||
compatibility promise. | ||
|
||
In our docs the features are marked like this: | ||
|
||
??? example "Experimental" | ||
|
||
This feature is still experimental and may change in the future. | ||
Use it with caution. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,20 @@ | ||
# Our supported versions | ||
|
||
Our top priority is to ensure that our library is as good as it can be. To be able to do this only the newest major | ||
version is considered to be in active development. This means new features only go in there and not in earlier major | ||
releases. The only exception would be, if this new feature would ease the upgrade to the next major version. | ||
|
||
If critical security issue would be discovered in our past major versions we will try our best to fix them there. They | ||
may be cases where this is not feasible to do this, and therefore an upgrade would be the task for you to do. | ||
|
||
## PHP Versions | ||
|
||
We will drop the support for PHP versions as soon as they go EOL in our next minor release. If you are running this PHP | ||
version do not worry, you can still use our library. You only won't get any updates until you update your PHP version. | ||
This is also done to ensure that our development efforts are not consumed by supporting old PHP versions which should | ||
not be used anymore. | ||
|
||
## Versioning | ||
|
||
For more information about our versioning you should | ||
read [our backward compatibility promise](./our-backward-compatibility-promise.md). |