+1 > On Oct 9, 2013, at 2:33 PM, James Peach <[email protected]> wrote:
>> 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
