Notes about Prawn 1.0 roadmap

[practicingruby]

Hello!

Thanks for building an extension to Prawn. I'm filing this issue to let you know that we're currently working towards a stable 1.0 release of Prawn, and I want to invite you to be part of the discussion around that.

We will only have one more major release before 1.0 is shipped: it will be labeled 0.15 and it will be cut on 2014-02-16.

The functionality of the 0.15 release will be largely the same as what we ship in 1.0, so if you want to test your project against the newest Prawn code, that would be a good time to do it. You can also get a head start by trying out what is on master now, and reporting any problems you encounter.

If your project is sufficiently up to date and is able to run on the latest Prawn code, the next step would be to take a look at our API compatibility plans, which are described in detail here:

https://groups.google.com/forum/#!topic/prawn-ruby/dbTSnlDhED0

Here's the very quick summary:

• If your project is using stable APIs and ONLY stable APIs, it will be safe for you to lock your Prawn dependency to "~> 1.0".
• If your project is using stable and extension APIs, keep an eye out for deprecation warnings, and lock your gem to a range of known good minor Prawn versions. (i.e. ">= 1.0", "<=1.x"). We want to eventually apply semantic versioning to our extension API as well, but we're not there yet.
• The use of experimental APIs in your extensions is not recommended unless you consider your own code to be experimental as well. Instead, work with us to figure out what it would take to get these experimental APIs stabilized or extracted.

I know this is a little bit confusing, and my hope is that in the not too distant future we'll be able to cut a Prawn 2.0 release that has much better support for downstream dependencies.

Until that time, what we lack in stability we'll try to make up in support for your project. Use the Prawn mailing list to contact us about any concerns or breakage, help us work on API stabilization, and let us know when you need extension points to support your project.

Thanks! -greg

[pointlessone]

@sandal I've just pushed v0.1.2. It's compatible with Prawn 1.0 API.

Though, it doesn't use extension API. It replaces 2 public methods in Prawn::Graphics::Patterns. I'm not sure how that is treated from the Prawn side. This extension doesn't change API but changes how the call is handled internally.

[pointlessone]

@sandal BTW, both fill_gradient and stroke_gradient are marked as Stable API but signal deprecated behavior. Stable API is described as one that will not be changed in a backwards-incompatible manner during 1.x lifetime, but message states that the deprecated call versions will be removed in 1.1. Should we remove it before the final 1.0?

[practicingruby]

@cheba Those deprecations are very old and were added before we had a release policy. But I agree, it would be best to remove the deprecated behavior in each of those methods before 1.0.

I did that with a couple other graphics calls, must have missed this one. Please either send in a pull request or file an issue in Prawn, and we'll get this taken care of.

[practicingruby]

@cheba As for the methods you replace, if you keep the behavior the same you might be OK, but I don't trust Prawn's behaviors to be especially well defined, and when there is undefined or clearly wrong behavior the API might change even during 1.x to correct it. I'm mostly thinking of things like accidental side effects or unconsidered edge cases, not just things we want to change for the sake of making the interface better.

If we can find a way to introduce extension points to call your code, I'd be open to it! For example, I wouldn't mind inserting a blank method that's intended to be rewritten by extensions to add behavior, or to accept a block and pass it along to some other method to be called later in extension code. I'm not familiar with this particular add-on though, so I'd need some more direction.