Document release compatibility

[gunnsth]

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:

• Adding func/type/var/const at package scope
• Adding a field to a struct
• Adding a method to a type

Major changes, i.e. requiring major version update:

• Removing exported func/type/var/const at package scope
• Adding a method to an exported interface
• Removing an exported field from a struct
• Removing an exported method from a type
• Changing an exported function/method signature

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

• Implement test cases that output PDFs that are rendered and compared with previous golden images.

In some (rare cases), we may decide that it is OK that the output rendering can change:

• When there is a bug fixed (for example margin was calculated incorrectly).
• The new output looks visually OK compared to the previous. Visually OK means that at least 2 developers have looked at the previous versus new and thought of ways customers could be affected.

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.

[adrg]

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.