Sorry, I'm a little late to the party here...
On Mon, Apr 28, 2014 at 4:35 PM, Marcel Kinard <cmarc...@gmail.com> wrote: > How about this: > > 1) No API changes within a minor version bump. We try (maybe we could do better at this) to follow the guidelines at http://www.semver.org for all of the cordova subprojects, *except* for the main platform's version number, which we've kind of declared to be a "marketing" version number. According to semver, the rule should be "No API changes with only a patch version bump. Only backwards-combatible API changes with a minor version bump." In practice, this means that the patch version gets incremented with bug fixes, and any *new* APIs can be added with a minor version increment. Any backwards-incompatible changes *require* a major version bump. > For example, we're looking at some "consistency improvements" to the > globalization plugin that would change the return values. That should > trigger a major version bump, even if the signatures/parms don't change. If the API signatures don't change, then we'd have to consider what *is* changing? If it's just the output, and it's incorrect in version A and correct in version B, then that sounds like a bug fix. If the output is different in a meaningful way then maybe that's minor, maybe major. (I would suggest that it's minor only if the output is definitely *better* in every case with the new version, but can still be consumed in exactly the same way) > As a consumer of Cordova, you should be able to have some confidence that > if there isn't a major version bump, you shouldn't need to change your > calling code. > > Absolutely. If any change to client code is required, there should be a major version bump. (Within reason: any bug could be depended on by someone; see https://xkcd.com/1172/) > 2) When doing an upgrade of plugins or platform, if there is a major > version bump to any of those components, the CLI should make it really > clear (a warning) that there may be a breaking change(s) and give them the > opportunity to abort the upgrade. > +1. We really need this. Maybe, like Debian, an upgrade should only ever upgrade within the same major release, and a harder upgrade command would be required for upgrading the major. Of course, this is all wishful thinking right now, since there's no upgrade command at all. The "upgrade" path is currently "remove plugin; re-add plugin", and I don't think that that flow should ever keep old metadata around. > 3) Keep the Upgrading Guides in the docs complete. So if they want to look > at what needs to change, these docs should at least give them a feel for > the order of magnitude, or better yet exactly what would be required. > > We are doing 1 & 3 already, correct? > > On Apr 28, 2014, at 2:49 PM, Josh Soref <jso...@blackberry.com> wrote: > > > Shazron wrote: > > > >> See: https://groups.google.com/d/msg/phonegap/II0qo-dSFWs/Fj8jkemGSbUJ > > > > While I haven't written it, I've contemplated the metadata required for > an > > update check that could tell you when a given api breaks. > > > >> because the API for device.platform changed and returned "ios" instead > >> of "iPhone"/"iPad", > > > > In principle, this would have been flagged to discourage updating the > > plugin, and in theory a solver could have identified the last version > from > > before this break. >
