On Wed, 9 Oct 2013 14:33:05 -0700 James Peach 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
+1 with a couple of suggested add-ons: 1) New API should be committed into experimental.h and moved into ts.h after a couple of weeks (3-4?) - this should be compulsory for API which didn't follow this new process, and encouraged for API which has. The goal is to give a bit more time for comments before we commit ourselves to supporting the API for a fairly long period.... Frankly - I like experimental.h - even though it is a bit of a cruft bucket. As long as the cruft is limited to the API layer, cleaning it up occasionally seems like a fair price for maintaining flexibility. 2) Adding a suggestion for new API to be integrated into a sample plugin - giving users a good sample to copy. --Uri
