From 7232b78778422392e0ffe841853f960d205bc788 Mon Sep 17 00:00:00 2001 From: Daniel Badura Date: Sat, 9 Nov 2024 16:27:03 +0100 Subject: [PATCH] Add docs for our bc promise and our versioning --- .gitignore | 3 +- Makefile | 2 +- docs/mkdocs.yml | 2 + .../our-backward-compatibility-promise.md | 46 +++++++++++++++++++ docs/pages/supported-versions.md | 20 ++++++++ 5 files changed, 71 insertions(+), 2 deletions(-) create mode 100644 docs/pages/our-backward-compatibility-promise.md create mode 100644 docs/pages/supported-versions.md diff --git a/.gitignore b/.gitignore index 387961983..ef267058e 100644 --- a/.gitignore +++ b/.gitignore @@ -9,4 +9,5 @@ infection.log infection.html *.sqlite3 .deptrac.cache -docs_php/ \ No newline at end of file +docs_php/ +docs/.cache \ No newline at end of file diff --git a/Makefile b/Makefile index 2ab2b574f..a836f0029 100644 --- a/Makefile +++ b/Makefile @@ -87,7 +87,7 @@ docs: mkdocs cd docs && python3 -m mkdocs serve .PHONY: mkdocs -mkdocs: ## run mkdocs +mkdocs: ## install mkdocs cd docs && pip3 install -r requirements.txt .PHONY: docs-extract-php diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 790f9a724..2ee820843 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -109,6 +109,8 @@ nav: - Time / Clock: clock.md - Testing: testing.md - CLI: cli.md + - Supported Versions: supported-versions.md + - Our BC Promise: our-backward-compatibility-promise.md - Upgrade from 2.x: UPGRADE-3.0.md - Links: - Blog: https://patchlevel.de/blog diff --git a/docs/pages/our-backward-compatibility-promise.md b/docs/pages/our-backward-compatibility-promise.md new file mode 100644 index 000000000..70c3ffe9d --- /dev/null +++ b/docs/pages/our-backward-compatibility-promise.md @@ -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. diff --git a/docs/pages/supported-versions.md b/docs/pages/supported-versions.md new file mode 100644 index 000000000..76d7b4c04 --- /dev/null +++ b/docs/pages/supported-versions.md @@ -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).