-
Notifications
You must be signed in to change notification settings - Fork 688
API Compatibility Notes
Prawn consists of a mixture of stable, well-supported features and more experimental features that are likely to change over time. We are going to spend a good amount of effort throughout our 1.x release line stabilizing things, but this document should give you an idea of what to expect when upgrading Prawn to newer versions.
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.
Prawn's version numbers consist of the usual version format, i.e. MAJOR.MINOR.TINY.
- Stable API features will only break compatibility when the MAJOR version changes.
- Extension API features can break compatibility on MINOR releases, but deprecation warnings will be displayed in an official stable release for at least 30 days before a change is made.
- Experimental API features can break compatibility on any MINOR release, without advanced notice.
- Prawn Internals are subject to change at any time, even in TINY releases. Do not depend on them. Any features not included in our API documentation should be considered internals.
If you are writing a Prawn extension, it's recommended to stick to the Stable + Extension APIs.
If you are writing a Prawn application, it's recommended to stick to Stable APIs only if you do not want to actively read release notes and possibly change your code on each MINOR update.
Using experimental APIs is encouraged for testers and folks working on projects they don't mind updating when new stuff breaks old code.
Below is a list of all namespaces with public functionality in Prawn, based on the level of APIs they support (as of Prawn 0.15):
| Namespace | Stable API | Extension API | Experimental API |
|---|---|---|---|
| Document | YES | YES | YES |
| Graphics | YES | - | - |
| Graphics::CapStyle | YES | - | - |
| Graphics::Color | YES | - | - |
| Graphics::Dash | YES | - | - |
| Graphics::JoinStyle | YES | - | - |
| Graphics::Patterns | YES | - | - |
| Graphics::Transformation | YES | - | - |
| Graphics::Transparency | YES | - | - |
| Images | YES | - | - |
| Measurements | YES | - | - |
| Outline | YES | - | - |
| SoftMask | YES | - | - |
| Stamp | YES | - | - |
| Text | YES | - | - |
| BoundingBox | YES | - | |
| Images::Image | - | YES | - |
| Images::JPG | - | YES | - |
| Images::PNG | - | YES | - |
| ImageHandler | - | YES | - |
| ::Prawn | - | YES | - |
| Text::Formatted::Box | - | YES | YES |
| Text::Formatted::Parser | - | YES | - |
| Document::ColumnBox | - | - | YES |
| Document::Security | - | - | YES |
| Font | - | - | YES |
| ::Numeric | - | - | YES |
| Repeater | - | - | YES |