[XviD-devel] versioning

[Edouard Gomez]

peter ross (suxen_drol@hotmail.com) wrote:
> api modifications
> =================
> if your new xvid feature/patch requires an api modification, follow these 
> simple rules:
> 
> - increment the minor version number by 1
> - append your api field(s) to the end-of the api structure.
> - NEVER remove an api field from the structure; if you nolonger need it, 
> just ignore it
> - perform a version test before accessing the field as demonstrated above 
> in encoder.c (if necessary provide a default value)
> 
> some api modifications, like bframes, will break api-compatibility. in this 
> case we would have no choice but to increment the major version number. 
> whenever we do this, we can also:
> - reset the minor version to zero & remove prior version tests
> - remove deprecated(usused) fields, and/or reorganise the structures for 
> readability
> 

Seems to be reasonnable. But...

1- If the API is stable long  enough (i mean no major changes during a
long time)  this would be  logical to reorgonize the  structures. This
means we should also consider some sort of "stabilization period" that
would force  us to break  compatibility incrementing major  version to
allow us to reorganize the structures.

2-  We  should  use  an  extension member  (pointer  to  an  extension
structure)  just  as  divx   does.   This  way,  the  main  structures
(XVID_ENC_PARAM or  XVID_ENC_FRAME) do not change  from client's point
of view. This results exactly the  same than adding the members at the
end, but i think it's  nicer because this way, developers know exactly
what features are part of the stable API (in the normal structure) and
which  ones are  not (in  the  extension member).   The major  version
defines what  is in  the normal structure  and the minor  version what
XviD  uses in  the extension  member. Your  minor changes  rules would
apply only  on the  extension member (adding  members at the  end, and
ignoring deprecated members).

regards

-- 
Edouard Gomez