diff options
author | Julian Berman <Julian@GrayVines.com> | 2013-07-28 21:07:05 -0400 |
---|---|---|
committer | Julian Berman <Julian@GrayVines.com> | 2013-07-28 21:07:05 -0400 |
commit | f78acbdc12cd7f8e2f18c45a729d051aa426a9c1 (patch) | |
tree | c8add5f7e8d8595036bdd092d0e31b59caade988 | |
parent | 5670b184af7f738e0811183bbfc9726b2d74d8fb (diff) | |
download | jsonschema-f78acbdc12cd7f8e2f18c45a729d051aa426a9c1.tar.gz |
Add a note about versioning.
-rw-r--r-- | docs/faq.rst | 41 |
1 files changed, 39 insertions, 2 deletions
diff --git a/docs/faq.rst b/docs/faq.rst index 6d039b1..fc6c27b 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -2,8 +2,9 @@ Frequently Asked Questions ========================== -**Why doesn't my schema that has a default property actually set -the default on my instance?** + +Why doesn't my schema that has a default property actually set the default on my instance? +------------------------------------------------------------------------------------------ The basic answer is that the specification does not require that :validator:`default` actually do anything. @@ -54,3 +55,39 @@ If you're interested in a more interesting solution to a larger class of these types of transformations, keep an eye on `Seep <https://github.com/Julian/Seep>`_, which is an experimental data transformation and extraction library written on top of :mod:`jsonschema`. + + +How do jsonschema version numbers work? +--------------------------------------- + +``jsonschema`` tries to follow the `Semantic Versioning <http://semver.org/>`_ +specification. + +This means broadly that no backwards-incompatible changes should be made in +minor releases (and certainly not in dot releases). + +The full picture requires defining what constitutes a backwards-incompatible +change. + +The following are simple examples of things considered public API, and +therefore should *not* be changed without bumping a major version number:: + + * module names and contents, when not marked private by Python convention + (leading underscore) + + * function and object signature (parameter order and name) + +The following are *not* considered public API and may change without notice:: + + * the exact wording and contents of error messages; typical reasons to do + this seem to involve unit tests. API users are encouraged to use + :class:`ValidationError.validator` and friends instead, which are + dependable. + + * the order in which validation errors are returned or raised + + * anything marked private + +With the exception of the last of those, flippant changes are avoided, but +changes can and will be made if there is improvement to be had. Feel free to +open an issue ticket if there is a specific issue or question worth raising. |