API Compatibility Notes

Gregory Brown edited this page Feb 18, 2015 · 80 revisions

The versioning policy for Prawn is as follows:

  • Whenever a documented feature is modified in a backwards-incompatible way, we'll bump our major version number.

  • Whenever we add new functionality without breaking backwards compatibility, we'll bump our minor version number.

  • Whenever we cut maintenance releases (which cover only bug fixes, documentation, and internal improvements), we'll bump our tiny version number.

This policy is similar in spirit to Semantic Versioning, and we may end up formally adopting SemVer in the future.

The main caveat is that if a feature is not documented ( either in our API documentation or in the Prawn manual ), you cannot assume anything about its intended behavior. Prawn has a lot of cruft left in it due to piecewise development over nearly a decade, so the APIs have not been designed as much as they have been organically grown.

To make sure that the amount of undefined behavior in Prawn shrinks over time, we'll make sure to review and revise documentation whenever new functionality is added, and also whenever we change existing features. In addition to the information on this page, you should check out [Prawn's API documentation]) for a feature-by-feature reference, and also look at the Prawn manual for usage instructions.