Re: Breaking BC / Changing API / Deprecating

Joe Stump 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 - >

yes

Foo_Bar2). Or change the API without doing the same. Does this simply

not true. You can add new features with impunity.

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.

It's the same idea, except you can't prevent users from upgrading to 2.0.0 if they simply wish to grab bugfixes. This is a problem I've encountered many times, and although it makes our jobs marginally more difficult it makes the user's jobs much easier (cutting and pasting is a pain on changing the package name, but not a big one).

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

Every package is unique. A generic document would only confuse the issue. Perhaps a simple email to pear-qa is the best recommendation any document can make. I would think requesting developers to specify the problem: "I want to do X with this package, but it would break BC, any ideas?" Then, pear-qa readers might find an obvious solution that doesn't break BC. This has already happened many times, fyi.

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).

As you state, this would be really annoying for developers. As such, I can't imagine anyone wasting tons of time breaking BC and releasing major versions every 2 months. As such, what will happen instead is better initial design and careful consideration of API concerns, resulting in end-user benefit. The main thing I hope this will do has already started to happen. Authors are more wary about applying the "stable" label to a package than they used to be. As a consequence, the quality of code in PEAR has risen dramatically, along with the both participation and the number of high-quality packages. Greg