[OPEN-ILS-DEV] Deprecating APIs (was: osrfAppSessionMakeRequest(): eliminate param_strings?)
Dan Scott
dan at coffeecode.net
Fri Dec 11 10:11:31 EST 2009
On Sat, 2009-12-05 at 09:09 -0800, Scott McKellar wrote:
<snip>
> -----------
>
> Migration path:
>
> 1. Create a similar function with a different name and no param_strings
> parameter.
>
> 2. Replace all calls to the old function with calls to the new one.
>
> 3. Eliminate the old one.
>
> 4. Change the underlying function osrfAppSessionMakeLocaleRequest()
> along the same lines. This will be easy because it's not called from
> anywhere else.
>
> 5. Eliminate osrf_message_add_param().
>
> All that's different about osrfAppSessionMakeLocaleRequest() is that it
> takes an additional parameter for locale, and in practice that parameter
> is always NULL. We could eliminate that parameter as well, but since
> it might be useful some day, we might as well keep it around.
I have no concerns about the technical approach for the migration path.
In the future I suggest that we adopt a deprecation policy where we mark
a given API as deprecated (via both the release notes - a "deprecated
API" section- and an OpenSRF log at the warning level, perhaps, with a
standard greppable format like "Deprecated API
<api_name(api_signature)>"?) and push that out in the next release.
After which we reserve the right to remove the API in future major
releases.
More information about the Open-ils-dev
mailing list