[XviD-devel] versioning

[peter ross]

>From: Edouard Gomez <ed.gomez@wanadoo.fr>
>Reply-To: xvid-devel@xvid.org
>To: xvid-devel@xvid.org
>Subject: Re: [XviD-devel] versioning
>Date: Wed, 24 Jul 2002 12:02:43 +0200
>
>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).
>


a fair comment, but i think it adds unnessasary structures to xvid.h. (KISS: 
lets keep it stupidly simple) why dont we just document better?

eg:

typedef struct
{
	int version;

	/*  --- XVID_VERSION(3,0) --- */
	int general;
	void *bitstream;
	int length;

	void *image;
	int stride;
	int colorspace;

	/*  --- XVID_VERSION(3,1) --- */
	int time_incr;		// [out] time increment

	/*  --- XVID_VERSION(3,2) --- */
	int postproc_algo;	// [in] post processing algorithm
}
XVID_DEC_FRAME;

we are a "little-way" away from v3.0, so if you've got some interesting 
"version" ideas SPEAK UP.

-- pete



_________________________________________________________________
MSN Photos is the easiest way to share and print your photos: 
http://photos.msn.com/support/worldwide.aspx