Re: not-yet-draft RFC on the new versioning standardsfor PEAR2 (needs PEAR Group sponsor to be official)

Christian Weiske wrote: > Hi Greg, > > >> API 1.0.2/stable, Release 1.0.3/stable <-- bugfix, API bugfix > Just to be clear: > An API bugfix means that e.g. I forgot to add a default value for a > function parameter (like " = null"). Nothing else. No semantic changes. > > - Do method additions count as bug fixes? > I can't think of any other API bugfix cases that do not break BC. > - Renaming and removing methods are clearly not bugfixes, since they > break BC. > - Renaming, adding or removing private properties is completely out of > scope because they are private. > - Protected properties and methods fall under the same rules as public > ones, because they are exposed to extending classes. I define API bugfix as "the program does not match the documentation, and the documentation is correct" Some examples: 1) wrong method name (does not match documentation) 2) wrong class name (does not match documentation) 3) does not implement ArrayAccess, and docs say it does 4) implements different algorithm from what docs say 5) method signature is incorrect 6) the magic variables you can get from __get/__set are different from the docs (i.e. the docs say you can do $obj->foo when in reality the name is $obj->foothing). 7) the docs say that you can do a fluent interface, but the methods return something other than the original object 8) the docs say that a feature is present, but it was never implemented This introduces 2 important details: 1) without documentation, there is no API 2) #1, #2, and #5 will be exceedingly rare when using phpDocumentor, but the others can more easily happen when relying upon things like ArrayAccess and __get/__set/etc. Thus, if the docs say that you can iterate over the object to get a list of things, and the object doesn't implement some form of Iterator, that's an API bug. private = private, this is not API. For API purposes, protected = public, yes. This puts a stronger emphasis on docs to define what people can do with the program. Examples of non-API bugs: 1) the class name changes in both the docs and the next release (BC break) 2) method name or signature changes in both the docs and the next release (BC break) 3) a protected/public method becomes private or is removed entirely (BC break) 4) a previously public/protected method that could be extended becomes final (BC break) This clearer? Greg