[Spacewalk-devel] Policy for backward compatibility and deprecation of APIs
mmccune at redhat.com
Mon Jul 28 11:53:37 EDT 2008
Brad Buckingham wrote:
> 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:
> 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 ...
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...
mmccune AT redhat.com
Engineering | Portland, OR
RHN Satellite | 650.567.9039x79248
More information about the Spacewalk-devel