Backporting changes in libraries
================================

I.e. how to create a 1.x release after 2.0 has been released.

Definitions
-----------
* earlier version = earlier release date
* lower version = lower version number
* more recent version = more recent release date
* higher version = higher version number

The short answer
================
* At any point in time, there should be only one version of the
  main.slul file (inteface file) for ALL versions of a library.
  The most recent interface file can be used to target earlier versions.
* Do NOT "patch" the interface file in lower-versioned branches.
  Instead, add any changes to the 
* The order of versions matters:
    - Order of \api_defs
    - Order of versioned struct fields
    - Order of versioned enum values
    - In all of these cases, the items should come in time order (i.e.
      release date order), and NOT in order of version numbers.
* All higher versions inherit declarations from lower versions that
  are also earlier. The lower versions can be both normal versions or
  backport versions.
 

XXX there are two problems here:
* the \slul version line does not have a since version!
  so backports to lower versions would become impossible if it was
  required to have ALL currently released versions in backports.
* a newer version can extend types (add fields in structs, or add values
  is enums). but in case of a backport, it may be necessary to extend
  types, but without making all earlier changes available in the older
  version.
  For example (with psuedo-code):
    - 1.0 released.   T=enum { a }
    - 1.1 released.   T=enum { a b }
    - 2.0 released.   T=enum { a b c }
    - 2.1 released.   T=enum { a b c d }
    - 1.2 released.   T=enum { a b X d }   (backport of 2.1 to 1.x)
  In this case, clients of the library that target v1.2 need to be compatible
  with 2.1 and newer also, in addition to 1.2 and newer. So "d" has to have
  the same value!!
  Similarly, if the type was a struct, then there would have to be padding
  where "c" is the the higher versions.
* how to backport a version after-the-fact?
    - since {2.1, 1.2}          ...but is there a simpler way?

Backports should NOT be done of the interface file. Instead, everone should
use the most recent (or a sufficiently recent) version of the interface.
When building using the most recent interfaces of the dependencies, it is
possible to target any earlier versions. So there is no need for backports
of the interface.


The long answer
===============

The module header
-----------------
SLUL uses a strict time-based ordering of versions, in addition to the
version numbers. This is represented by the order of the \api_def attributes.

    \api_def 1.0
    \api_def 2.0
    \api_def 1.1      # <--- must come in time-based order!

I.e. it is not allowed to insert versions before already released versions!

The interface
-------------
Backports should NOT be done of the interface file. Instead, everone should
use the most recent (or a sufficiently recent) version of the interface.
When building using the most recent interfaces of the dependencies, it is
possible to target any earlier versions. So there is no need for backports
of the interface.

There are two requirements that are of importance:

* The interface files can always be up to date, even if targeting an
  earlier version.
* Higher versions are compatible with lower versions.

This means that someone who builds a modules

xxxx SLUL requires that the latest version of an module's interface file is always
backwards compatible with any older version (i.e. earlier released, NOT lower
version number).

So backports need to contain