From d95ec6edf1ce26f663d06c65149daa3d928e3619 Mon Sep 17 00:00:00 2001 From: Michel Fortin Date: Thu, 7 Feb 2013 08:26:37 -0500 Subject: [PATCH] Added Public API and Versionning Policy to readme file. --- Readme.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/Readme.md b/Readme.md index aa15829..7d12f27 100644 --- a/Readme.md +++ b/Readme.md @@ -95,6 +95,35 @@ To do this, you must set the `empty_element_suffix` variable of the parser object to ">". +Public API and Versionning Policy +--------------------------------- + +Version numbers are of the form *major*.*minor*.*patch*. + +The public API of PHP Markdown consist of the two parser classes `Markdown` +and `MarkdownExtra`, their constructors, the `transform` and `defaultTransform` +functions and their configuration variables. The public API is stable for +a given major version number. It might get additions when the minor version +number increments. + +**Protected members are not considered public API.** This is unconventionnal +and deserves an explanation. Incrementing the major version number every time +the underlying implementation of something changes is going to give nonsential +version numbers for the vast majority of people who just use the parser. +Protected members are meant to create parser subclasses that behave in +different ways. Very few people create parser subclasses. I don't want to +discourage it by making everything private, but at the same time I can't +guarenty any stable hook between versions if you use protected members. + +**Syntax changes** will increment the minor number for new features, and the +patch number for small corrections. A *new feature* is something that needs a +change in the syntax documentation. Note that since PHP Markdown Lib includes +two parsers, a syntax change for either of them will increment the minor +number. Also note that there is nothigng perfectly backward-compatible with the +Markdown syntax: all inputs are always valid, so new features always replace +something that was previously legal, although generally non-sensial to do. + + Bugs ----