Development Roadmap

Prawn is currently alpha software edging towards beta.

It’s not production ready, and unless you’re willing to keep up with the latest changes in the source, you might want to wait until after an official 1.0 release to work with it. That said, if you’re interested in helping out or knowing what’s left to be done, this is the document for you.

Prawn’s Components.

Currently, Prawn is made up of three components: prawn-core, prawn-format, and prawn-layout.
We have also broken our TTF support out into its own package ttfunk, but this can be considered part of prawn-core. In addition to these three components, we’ll be adding another before 1.0, called prawn-security (for document encryption and password protection.)

All of these components will get installed for you when you do: gem install prawn

Our expectation for Prawn 1.0 is mainly that prawn-core will be very stable and capable. Our other components may still continue to grow and change after the 1.0 release, but will have a baseline level of functionality for everyday PDF needs.

It is important to remember the main goal of this project is to provide a solid foundation for low level PDF work, not to make every PDF reporting task easy out of the box. The key benefit of this approach is that Prawn will be able to evolve to fit the needs of our users through extensions even once the core library has stabilized and cooled down.

There are also two third party extensions: Prawnto (for rails support), and prawn-fast-png (for linking to RMagick). While we find both of these projects excellent, they are not officially maintained by the Prawn developers, and therefore aren’t part of our development roadmap.

Important Things Before 0.5.1

• Freeze all featurework (we need to get this release out!)
• Ensure API docs are up to date
• Update supporting documentation and website
• Write some great release notes that document the changes from 0.4 clearly.

Important Things Before 0.6

• Pull in patches that have been approved, review those that need it.
• Add prawn-security to the prawn metagem
• Bring in transactional rendering and associated features
• Page numbering
• Come up with a hacking guide and some patch guidelines

Important Things Before 1.0

• Rewrite table implementation for greater extensibility
• Allow arbitrary content within table cells (images, vector drawings, etc)
• Fallback font support to make m17n easier
• Improve header / footer support in prawn-layout (similar to PDF::Wrapper)
• Come up with good prawn-grid examples
• Build PDF::Writer compatibility layer (most importantly, to discover what Prawn is missing)
• Investigate issues with tables within stretchy bounding boxes, and bounding box problems in general
• Make stretchy bounding boxes smarter about how they stretch.
• Establish an official and explicit “Developer API” for extensions
• Come up with a list of who contributed what to Prawn
• Write a short manual that shows how to use Prawn the way we do.

Release Schedule

In the past, Prawn’s release cycle was not well defined. However, we’re working on changing that, and this is the new plan.

Git Branches

We maintain two mainline branches meant for public consumption, stable and master.

The stable branch is designed to not change, and represents whatever the current official stable version of Prawn is, with potentially some additional bug fixes and cleanup that hasn’t made it out to a tagged or gem packaged release yet. So if you are interested in using Prawn in production despite our warnings not to, this is the branch you should be tracking. You are of course, responsible for being aware of when a new major release happens, so that you can lock to a particular revision or gem version so that API changes don’t affect you.

The master branch is Prawn’s bleeding edge, and will always represent the codebase you can expect to evolve into the next major release of Prawn. Here, we pay absolutely no attention to API changes, and may break things without warning. Generally speaking, we won’t check purely experimental code into master, and we try to prevent the build from breaking. This means you can certainly make use of it if you’re particularly vigilant, but should be prepared for turbulence.

Every time there is a new major release, master gets merged into stable, and then the process repeats from there.

Release numbering / time frame

Releases from 0.5.1 forward will be time based rather than feature milestone based. We hope this rolling release cycle will make Prawn releases smaller and more manageable for users.

New major releases come in the form of 0.k.1

Prawn 0.5.1 will be a new major release. It will break compatibility with Prawn 0.4, introducing many new features and other goodies.

New releases will be done monthly, starting on 2009-09-15, and will represent everything currently in master that is stable enough for public release. We will repeat this process until we feel we’re ready for a 1.0 release.

Since every new major release will add new stuff, potentially take away old stuff, and break API compatibility, be absolutely sure you read the release notes before an upgrade.

New minor releases come in the form of 0.k.j

As we fix bugs in 0.5, you’ll see releases like 0.5.1, 0.5.2, 0.5.3, etc.
APIs will not change in minor releases, but you should still read the release notes to know what you’re getting yourself into.

So long as you don’t depend on some buggy behavior, it should always be safe to upgrade from a 0.k.j release to a 0.k.j+1 release.
The only notable exception is explained below (release candidates)

Release candidates come in the form 0.k.0.j

Here be dragons

For example, the current version of Prawn at the time of writing is 0.5.0.1, meaning Prawn 0.5, RC 1

Generally speaking, these snapshots are developer previews only and will hopefully be rare in the future (perhaps having one before the 1.0 release). But these releases will not be tagged and are not officially supported, and API changes and feature add/removal can happen at will.

If you accidentally install a release candidate gem, it should be fairly obvious because the gem will tell you upon install. If you wish to avoid this entirely, just build against the stable branch in git, which after 0.5.1, will never contain pre-release code.