+1
On Wed, Oct 9, 2013 at 5:33 PM, James Peach <jpe...@apache.org> 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/%3cf17998c6-67d2-4457-aa82-51293b89f...@apache.org%3E > >. > > cheers, > James > > > -- Theo Schlossnagle http://omniti.com/is/theo-schlossnagle
