Add "Upgrading from older releases" to docs, tweak CHANGES a bit

CHANGES

@@ -2,8 +2,8 @@ Version 2.0 (in development)
 ============================
 
 This release is backwards incompatible with the 1.x release series.
-See the documentation for instructions on how to port existing code to
-Jansson 2.0.
+See the chapter "Upgrading from older versions" in documentation for
+details.
 
 * Backwards incompatible changes:
 
@@ -14,7 +14,7 @@ Jansson 2.0.
     type available, i.e. long long if it's supported, otherwise long.
     Add a typedef json_int_t that defines the type.
 
-  - Change the maximum indentation depth to 32 spaces in encoder. This
+  - Change the maximum indentation depth to 31 spaces in encoder. This
     frees up bits from the flags parameter of encoding functions
     `json_dumpf()`, `json_dumps()` and `json_dump_file()`.
 
@@ -23,8 +23,8 @@ Jansson 2.0.
 
 * New features
 
-  - `json_pack()`, `json_pack_ex()`, `json_vpack_ex()`: Create complex
-    JSON values based on a format string.
+  - `json_pack()`, `json_pack_ex()`, `json_vpack_ex()`: Create JSON
+    values based on a format string.
 
   - `json_unpack()`, `json_unpack_ex()`, `json_vunpack_ex()`: Simple
     value extraction and validation functionality based on a format
@@ -33,12 +33,12 @@ Jansson 2.0.
   - Add column, position and source fields to the ``json_error_t``
     struct.
 
-  - Report the error context for UTF-8 decoding errors in the decoder.
+  - Enhance error reporting in the decoder.
 
-  - Add preprocessor constants that define the library version.
+  - ``JANSSON_VERSION`` et al.: Preprocessor constants that define the
+    library version.
 
-  - Add API for setting custom memory allocation functions:
-    `json_set_alloc_funcs()`.
+  - `json_set_alloc_funcs()`: Set custom memory allocation functions.
 
 * Fix many portability issues, especially on Windows.
 

doc/index.rst

@@ -33,6 +33,7 @@ Contents
    :maxdepth: 2
 
    gettingstarted
+   upgrading
    tutorial
    conformance
    apiref

doc/upgrading.rst

@@ -0,0 +1,76 @@
+.. highlight:: c
+
+*****************************
+Upgrading from older versions
+*****************************
+
+This chapter lists the backwards incompatible changes introduced in
+Jansson 2.0, and the steps that are needed for upgrading your code.
+
+**The incompatibilities are not dramatic.** The biggest change is that
+all decoding functions now require and extra parameter. Most programs
+can be modified to work with 2.0 by adding a ``0`` as the second
+parameter to all calls of :func:`json_loads()`, :func:`json_loadf()`
+and :func:`json_load_file()`.
+
+
+Compatibility
+=============
+
+Jansson 2.0 is backwards incompatible with the Jansson 1.x releases.
+It is ABI incompatible, i.e. all programs dynamically linking to the
+Jansson library need to be recompiled. It's also API incompatible,
+i.e. the source code of programs using Jansson 1.x may need
+modifications to make them compile against Jansson 2.0.
+
+All the 2.x releases are guaranteed to be backwards compatible for
+both ABI and API, so no recompilation or source changes are needed
+when upgrading from 2.x to 2.y.
+
+
+List of incompatible changes
+============================
+
+**Decoding flags**
+    For future needs, a ``flags`` parameter was added as the second
+    parameter to all decoding functions, i.e. :func:`json_loads()`,
+    :func:`json_loadf()` and :func:`json_load_file()`. All calls to
+    these functions need to be changed by adding a ``0`` as the second
+    argument. For example::
+
+        /* old code */
+        json_loads(input, &error);
+
+        /* new code */
+        json_loads(input, 0, &error);
+
+
+**Underlying type of JSON integers**
+    The underlying C type of JSON integers has been changed from
+    :type:`int` to the widest available signed integer type, i.e.
+    :type:`long long` or :type:`long`, depending on whether
+    :type:`long long` is supported on your system or not. This makes
+    the whole 64-bit integer range available on most modern systems.
+
+    ``jansson.h`` has a typedef :type:`json_int_t` to the underlying
+    integer type. :type:`int` should still be used in most cases when
+    dealing with smallish JSON integers, as the compiler handles
+    implicit type coercion. Only when the full 64-bit range is needed,
+    :type:`json_int_t` should be explicitly used.
+
+
+**Maximum encoder indentation depth**
+    The maximum argument of the ``JSON_INDENT()`` macro has been
+    changed from 255 to 31, to free up bits from the ``flags``
+    parameter of :func:`json_dumps()`, :func:`json_dumpf()` and
+    :func:`json_dump_file()`. If your code uses a bigger indentation
+    than 31, it needs to be changed.
+
+
+**Unsigned integers in API functions**
+    Version 2.0 unifies unsigned integer usage in the API. All uses of
+    :type:`unsigned int` and :type:`unsigned long` have been replaced
+    with :type:`size_t`. This includes flags, container sizes, etc.
+    This should not require source code changes, as both
+    :type:`unsigned int` and :type:`unsigned long` are usually
+    compatible with :type:`size_t`.