> On Mar 13, 2018, at 3:58 PM, Greg Mann <g...@mesosphere.io> wrote: > > Sure we can use that as a starting point. The basic policy that we > discussed in the working group was that any public API change should be > advertised on the developer mailing list. If no concerns are raised after > several days, then the change could proceed. If concerns were raised, then > discussion could start on the mailing list and continue in the next meeting > of the API working group if necessary. > > The Traffic Server policy includes a few other concrete details which we > did not discuss. I'll quote it here to make things easy: > > > Due to the importance of getting API right, there is a required review >> process for changes to the Traffic Server API. For every API change, the >> developer should post a message to the dev@ list that >> >> - references the relevant Github Issue or PR >> - explains the motivating problem and rationale >> - shows the actual API change itself (ie. API signatures, etc) >> - documents the semantics of the proposed API >> - notes any ABI or compatibility implicates >> >> After a comments period (1 or 2 days), the committer would add the API. If >> there were any comments or suggestions, then the committer would address >> those as necessary. >> >> New API can be added to experimental.h if the developer believe that it >> might change after some adoption or implementation experience. APIs >> intended for experimental.h should still be reviewed on the mailing list. >> APIs added to experimental.h, or another experimental header, can (and >> should!) get moved to a frozen and stable include file when appropriate. >> It's up to the author to propose a promotion to stable on the mailing list, >> lazy consensus applies here. >> >> It is strongly preferable that a new API to be integrated into a sample >> plugin - giving users a good sample to copy. API documentation and unit >> tests should be provided as a matter of course. >> >> > > I think this is pretty good as-is; replace "Github Issue or PR" with "JIRA > issue or ReviewBoard patch", and remove the portion about 'experimental.h' > and what follows.
I’m generally in favor of this. I think that we all try to raise compatibility and operational issues on the mailing lists, so this seems like a formalization and extension of that practice. Most of the information needed for an API proposal would already be captured in a design document, so in the Mesos context this would be about improving the visibility of changes and widening the feedback net. cheers, James.
