[Spacewalk-devel] Policy for backward compatibility and deprecation of APIs

Mike McCune mmccune at redhat.com
Mon Jul 28 11:53:37 EDT 2008


Brad Buckingham wrote:
> Team,
> 
> One of the things that we have on the Spacewalk roadmap is to continue 
> to evolve and improve the APIs that are available in Spacewalk.  As this 
> occurs, we'll certainly find the need to modify existing APIs which 
> might include adding/removing/changing parameters, return values and 
> even the namespace/package that an API may be part of.  However, as we 
> do this, we need to minimize the impact to the users.  That said, we 
> need to define a policy or approach for how we handle changes that 
> impact the users.
> 
> Reference: the current working document on changes coming in the API can 
> be found at:
>     https://fedorahosted.org/spacewalk/wiki/ApiAdditions
> 
> Below is a high-level proposal.  Please look it over and let's discuss 
> over the group.
> 
> 1. An API will be "backward compatible" from one major release to the 
> next (e.g. Spacewalk 1.0 to 2.0), unless the API was defined as 
> "Deprecated" in the previous major release.
> 
> 2. An API is considered "backward compatible" so long as it doesn't 
> require the user to change code that uses the API when upgrading from 
> one Spacewalk release to the next.
> 
>     For example, a user wrote a script using a non-deprecated API based 
> on Spacewalk 1.0.  Upon receiving Spacewalk 2.0, the user's script 
> continues to work without modifying the script's usage of the API.
> 
> 3. An API may be defined as "deprecated" during a Spacewalk release.  
> Once an API is marked as deprecated, it will remain in Spacewalk until 
> the next major release.

I would think we may want to clarify this.  If we mark a call as 
deprecated in 1.9 would it then be removed in 2.0?  That seems a bit ... 
short.

Perhaps:

3. An API may be defined as "deprecated" during a Spacewalk release.
Once an API is marked as deprecated, it will remain in Spacewalk for the 
duration of one major release.  For example a method marked Deprecated 
in 1.5 will remain in Spacewalk until version 2.5.

Is this too hard to keep track of?  We could also adopt a policy that 
you can only mark methods as Deprecated at the start of a major release, 
say during the 1.0, 2.0, 3.0 phases...

-- 
Mike McCune
mmccune AT redhat.com
Engineering               | Portland, OR
RHN Satellite             | 650.567.9039x79248




More information about the Spacewalk-devel mailing list