Mention stability of symbolizers

[yohanboniface]

As discussed in #99, we'd like to be able to define the stability of each symbolizers.
Mainly because we want to push some unstable symbolizers to start having feedback from Mapnik community, and to declare some of them as deprecated when needed.

We need to push a 8.0.0 version for this.

Todo:

• define which key to use; candidates at this time: stability, status
• define expected values (and default one); candidates at this time: deprecated, experimental, unstable, stable
• document it
• apply status where needed in the reference
• release

@springmeyer what else? Can you just give me some pointers about things to be done, I'll take care of them. :)

[yohanboniface]

@springmeyer should I proceed on that? Anything more that need to be done? :)

[springmeyer]

@yohanboniface - your todos look great. Thank you!

My preference would be status as key and deprecated, stable, unstable, and experimental as values.

proposed definitions:

• stable: property is here to stay and its behavior is not anticipated to change
• unstable: property is here to stay but its behavior/meaning of property may change (.e.g line-offset or text-dy as per Predictable offsetting on polygons mapnik#2851)
• deprecated: property should not be used and will be removed in upcoming Major version of Mapnik (.e.g. marker-type which is replaced by file="shape://marker-name or text-min-distance which is replaced by text-repeat-distance and text-margin)
• experimental: property should not be used and may dissapear, be re-named, or disappear at any time (text-largest-bbox-only as per add text-largest-bbox-only #99)

[yohanboniface]

Thanks :)
Where do you suggest I put those definitions? In the README is fine?

[springmeyer]

Yes, README is good.

[yohanboniface]

@springmeyer we should be ready for 8.0.0. release, unless you want to add more status keys in the reference.
Tell me if you want me to prepare anything more (git tag…) for releasing. :)

[springmeyer]

@yohanboniface - just added you so you can npm publish npm owner add ybon.

Also added a contributing braindump in bc4dc6b.

Please go ahead and tag/publish if you'd like!

Followups needed on my end:

• Ensure Carto does not get tripped up on the new properties
• Ensure Mapbox studio/TileMill do not allow deprecated properties (for now).

[yohanboniface]

Quick suggestion: we can automate the push to npm from Travis when pushing a new tag and tests passe: http://docs.travis-ci.com/user/deployment/npm/

[springmeyer]

@yohanboniface Interesting, not seen that. I've never minded the manual npm publish myself, but I'm open if you think this would streamline things.

[yohanboniface]

Is any action still needed here or can we close?

[springmeyer]

Let's close. Carto has been using this version of mapnik-reference for some time now without issues.