Re: Breaking BC / Changing API / Deprecating

On 7/19/05, Joe Stump <joe@joestump.net> wrote: > Guys, > > I've heard from the QA team that you can't break backwards > compatibility without creating an entirely new package (ie. Foo_Bar - > > Foo_Bar2). Or change the API without doing the same. Does this > simply sound retarded to anyone else? Isn't this what version numbers > are for? Yes, but this policy was put in place to save the users. If they upgrade to a new version of a package with BC breaks then their scripts will stop working. Remember that PEAR is sometimes installed by people who are simply getting dependencies to another package. They could easily, unwittingly, install a version which is incompatible. This is (part of) why BC rules exist. > > Imagine if every time the Linux kernel API was changed Linus changed > sys calls from foo() to foo2() and so forth. The Linux kernel is an etirely different beast. First of all you have to know (somewhat) what you're doing to upgrade to a new one. It's not as simple as "pear upgrade-all". Second, the kernel's API doesn't really change. At least not the exposed API. The internal API can change in all sorts of ways and it won't affect programs which run on top of it. If an external change is made a huge deal is made out of it. > > I've also heard that it's OK to break BC, change the API, deprecate, > etc. as long as it's a major point release (ie. 1.0.0 -> 2.0.0). This > makes *much* more sense, IMO. Yes, this is true. However you're missing that switching to a new major revision also means that you release a new package with the new version # on the end. > > Are there any docs that outline how to go about breaking BC and > changing the API in your package? I think it simply doesn't pass the > sniff test to constantly be creating new packages that are exactly > the same as the old ones save for a few changes in the API. > Especially if care is taken to release a major point release as > "alpha" and push it through to stable as other packages update > themselves (or just keep relying on the older 1.x series). > See many may discussions on this list in the past for more. There should also be a doc on the website that talks about this (if not in the Manual, try looking for RFCs in the proposals). -- Justin Patrin