[OPEN-ILS-DEV] Deprecating APIs (was: osrfAppSessionMakeRequest(): eliminate param_strings?)

[Dan Scott]

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.