Closed gunnsth closed 4 weeks ago
I think the compatibility proposal looks good. Maybe we can also add some notes regarding the pitfalls of the acceptable minor changes we allow:
Adding func/type/var/const at package scope
- safe in all scenarios.Adding a field to a struct
/Adding a method to a type
- although unlikely, this could cause ambiguity compiler issues if the type is embedded and a new field/method with the same name is added by the user.The creator package is prone to visual changes, not only due to bugs being resolved but also to new features which are introduced. For example, the styled paragraph did not wrap across pages before. Now it does. Visually, this is a breaking change, but one that a user would expect/prefer over the previous behavior.
With reference to https://blog.merovius.de/2015/07/29/backwards-compatibility-in-go.html it seems like the compatibility we want to keep is as follows.
We should add the following to our developer guidelines.
Compile-time compatibility
Acceptable non-major changes:
Major changes, i.e. requiring major version update:
Run-time compatibility
Changes in code can lead to changes in output PDF. It is tricky to promise that outputs won't change.
In general we strive to maintain unchanged output of same code. To this end we
In some (rare cases), we may decide that it is OK that the output rendering can change:
Customers can have a say in this process also by contacting us and clarifying what code needs to be particularly stable. To this end test cases for specific cases can be developed and added to the test corpus.