LinuxConf.eu: Documentation and user-space API design

Posted Sep 5, 2007 5:55 UTC (Wed) by lacostej (guest, #2760)
Parent article: LinuxConf.eu: Documentation and user-space API design

It looks like issues are detected within a time frame or +2 releases. Some of the issues reported here also look like no-one really used them, otherwise they would have had their issues revealed.

Could it help to state that a particular system call released in stable n release isn't considered stable until n+2 ? and that we allow breaking it in that time-frame ? That's probably just pushing the problem...

Better would be to wait until it has n reported users (n>=3). So what about only adding new APIs to the kernel until enough people have used them. That should also increase the testing of the non official stable trees.

LinuxConf.eu: Documentation and user-space API design

Posted Sep 5, 2007 6:29 UTC (Wed) by mkerrisk (subscriber, #1978) [Link]

Could it help to state that a particular system call released in stable n release isn't considered stable until n+2 ? and that we allow breaking it in that time-frame ? That's probably just pushing the problem...

This is an idea that has been getting some consideration. It might help matters a little, but it causes other types of pain (e.g., a new interface becomes moderately used by a number of apps, but then a critical design issue causes a interface change at n+2; or, userland developers refrain from using an interface until n+2, because they know it might change).

My hypothesis is that we could get a lot of the benefit, and avoid the sorts of pain I just described, if we could improve and rigorously apply a documentation and testing process for new interfaces (i.e., a process that occurs in parallel with the implementation of the interface, and is completed by the time of initial stable release, rather than after the fact).