+1 On Thursday, October 17, 2013, Alan M. Carroll wrote:
> +1 > > > On Oct 9, 2013, at 2:33 PM, James Peach <[email protected]<javascript:;>> > 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 > > > > >
