Hi all,
I'd like to propose that we add formal API reviews to out development process.
The rationale for this is:
- API is important enough that we should go to extra effort to make it
consistent and straightforward to use
- API changes require long term compatibility support
- we already have too much underdocumented, unsupported API (eg.
experimental.h)
So the process I propose is that for each API change, the committer should post
a message to the dev@ list that
1) references the relevant jira ticket
2) explains the motivating problem and rationale
3) shows the actual API change itself (ie. API signatures, etc)
4) documents the semantics of the proposed API
5) notes any ABI or compatibility implicates
After a comments period (1 or 2 days), the committer would add the API. If
there were comments or suggestions, then the committer would address those as
necessary. I'm ambivalent about whether this process should be compulsory, but
I think that we should encourage it.
An example of an (somewhat terse) API review post would be:
<http://mail-archives.apache.org/mod_mbox/trafficserver-dev/201202.mbox/%[email protected]%3E>.
cheers,
James
