Too much to discuss in one thread, I am starting a new thread to discuss plugin versioning. Cheers, Jesse
@purplecabbage risingj.com On Fri, Aug 16, 2013 at 2:41 PM, Andrew Grieve <agri...@chromium.org> wrote: > After the discussion on the group hangout + some sleeping, I think we're > ready for a proposal... So here it is! > - It does *not* propose any changes to our Deprecation policy. That's for > another thread (which I'll get to on Monday if no one else does) :) > - It does not contain how we store version numbers. That's covered here: > http://wiki.apache.org/cordova/StoringRepoVersionsDesign > > Once we get to a consensus, I'll transfer this to the wiki. Please review & > comment! > > There are two kinds of versions: > 1. "SemVer" (www.semver.org) > - Used by platforms, plugman, cli > 2. "CadVer" (just made that up :P "Cadence Version") > - Used by cli, mobile-spec, cordova-js > > There are two kinds of releases: > 1. Patch releases > - Pretty much any repo can release a patch release to fix bugs at any > time (but should have good reason) > 2. Cadence releases > - These follow the 10 releases per year, as enumerated on: > http://wiki.apache.org/cordova/RoadmapProjects > > cordova-plugins: > - Commit only to the `dev` branch > - Use semver for them. > - If the version on master is "3.0.0", then the version on dev will > start at "3.0.1-dev". > - If any commit goes in that add a feature, then change the version on > dev to "3.1.0-dev" > - If any commit goes in that makes an non-backwards-compatible change, > then change the version on dev to "4.0.0-dev" > - Release plugins at most once a week (Thursdays?) > - This *does* mean that a change that goes in Wednesday could end up > being released the next day. > - Release plugins all at the same time so that we can blog the release > notes. > - Release process: > 1. Create a JIRA issue to track the status of the release. > a. Comments should be added to this bug after each top-level step > below is taken > 2. For each plugin that has unreleased commits on their `dev` branch: > a. Update its CHANGELOG file with a prettified version of "git log" > b. Update its plugin.xml version by removing the "-dev" suffix > c. Merge dev -> master (without pushing) > d. Update its plugin.xml version by incrementing the micro and adding > "-dev" (as described above) > 3. Combine all plugin changelogs into a Release announcement blog post > on cordova-website. > a. Steps for this exist in cordova-website's README.md > 4. Test > a. Create mobilespec using the old versions of plugins > b. Perform a "plugin upgrade" for plugins that have changes (right > now, this means doing a `plugin remove` followed by a `plugin add` > c. Run through mobilespec, ensuring to do manual tests that relate to > changes in the changelog > 5. Push! > a. Push all branches > b. Push the blog post > > cordova-plugman: > - Commit to master always > - Release only when necessary. > - Release process: > 1. For releases that increment the minor or major, email the dev list > to let others know about your intent to release (include changelog) > a) Wait for at least one +1 > 2. Increment the version within package.json > 3. Update RELEASENOTES.md with the changes for this release > 4. Push to npmjs.org > * In order to push, you must be given push access to the npm module. > * To do so, ask one of the existing module maintainers (listed here: > https://npmjs.org/package/plugman) > 5. Post a release announcement on the cordova blog (for feature > releases only) > a. Steps for this exist in cordova-website's README.md > b. Not necessary for patch releases, but feature releases should > mention significant bugs fixed by previous patch releases. > > No JIRA: The process is light-weight enough that a JIRA issue isn't > necessary for tracking. > > > cordova-cli: > - Commit to master, release from release branches (2.9.x, 3.0.x, etc) > - Versioned using "$COROVA_VERSION-$CLI_VERSION" > - E.g. 3.0.0-0.5.1 > - The first version component is the "cadence version", and has its > minor incremented whenever the platform repository that it lazy loads by > default is changed > - E.g. 3.0.0 uses cordova-blackberry@3.0.0, cordova-ios@3.0.0, > cordova-android@3.0.0 > - E.g. 3.1.0 uses cordova-blackberry@3.1.0, cordova-ios@3.0.1, > cordova-android@4.0.0 > - E.g. 3.2.0 uses cordova-blackberry@3.1.1, cordova-ios@3.1.0, > cordova-android@4.0.1 > - E.g. 3.2.1 uses cordova-blackberry@3.1.2, cordova-ios@3.1.0, > cordova-android@4.0.1 > - The version number of cordova-cli will be the version number that we > advertise on our website, blogs & docs > - Platform version numbers will use semver, and not be referenced > - Release process for patch releases: > 1. cherry-pick commits from master -> latest release branch > 2. Increment package.json's micro version > 3. Update RELEASENOTES.md > 4. Push to npmjs.org > * In order to push, you must be given push access to the npm module. > * To do so, ask one of the existing module maintainers (listed here: > https://npmjs.org/package/cordova) > - Release process for minor version > - Same as patch release, and in addition: > 1. Email the dev list to let others know about your intent to release > (include changelog) > a. Wait for at least one +1 > 2. Post a release announcement on the cordova blog (for feature > releases only) > a. Steps for this exist in cordova-website's README.md > b. Not necessary for patch releases, but feature releases should > mention significant bugs fixed by previous patch releases. > - Release process for major version: > - Refer to platform release process. > > cordova platforms, mobile-spec, cordova-js: > - Same as before (as documented on > http://wiki.apache.org/cordova/CuttingReleases) > - Except: > - Platforms versions to use semver. This *does* mean that they will > diverge from each other. > - cordova-js and cordova-mobile-spec to use the "cadence version" > (first part of cordova-cli's version) > - No longer update cordova-app-template > - Blog post will include changelog for all changes since previous > platforms release. > - JIRA issue should have a comment that lists the platform versions > that are referenced by the cadence version. > > JIRA workflow: > - When issues are closed, the "fixed version" should be set to the > cadence version. > > > Andrew > > > On Thu, Aug 8, 2013 at 4:18 PM, Andrew Grieve <agri...@chromium.org> > wrote: > > > > > > > > > On Wed, Aug 7, 2013 at 8:49 PM, Michael Brooks <mich...@michaelbrooks.ca > >wrote: > > > >> > > >> > Plugins and CLI tools I think we should just ship continuously. The > >> > > Why do you think these should be shipped continuously instead of on a > > regular cadence? Note that I think they should be as well, but I'm trying > > to figure out why the tools & plugins are different from the platforms. > > > > > >> > only question that remains in the 'how' of that is versioning. Mike > >> > Brookes has advocated semver schema here wherein we version platforms > >> > separately from the tools using a compound version number. An example > >> > of this might be 3.0.0-0.14.3 wherein 3.0.0 represents our platforms > >> > while 0.14.3 represents the CLI tool itself. > >> > >> > >> I only advocate semver for node modules and you can expect that I'll be > >> pushing this on cordova-cli soon. :) > >> > >> Node modules use semver. Regardless of whether it's effective or not, > it's > >> what the community uses and as developers we should attempt to respect > and > >> adhere to it. > >> However, Cordova uses a different type of versioning scheme. > >> > >> The CLI tool needs to represent both of these versioning schemes. > >> > >> - The Cordova version is most important, because it describe what > version > >> of Cordova the CLI uses. > >> - The node module version is important to modules consuming cordova-cli. > >> You have no idea how frustrating cordova-cli's current versioning is wrt > >> to > >> the phonegap-cli. > >> > >> This is why a version such as 3.0.0-0.10.4 works extremely well. It's > >> distributing version 3.0.0 of Cordova. The node module itself is version > >> 0.10.4. It's also semantically valid in semver, so it's compatible with > >> npm. > >> > >> Michael > >> > >> > >> On Wed, Aug 7, 2013 at 1:27 PM, Andrew Grieve <agri...@chromium.org> > >> wrote: > >> > >> > On Wed, Aug 7, 2013 at 12:49 PM, Brian LeRoux <b...@brian.io> wrote: > >> > > >> > > I think keeping the cadence on the core platforms makes sense. That > is > >> > > where the bulk of logic lives, it is susceptible to 3rd party issues > >> > > like new iDEs and SDKs, and having that regular cadence in lockstep > >> > > makes issue tracking easier to discuss with the community. > >> > > I agree that keeping the number of different version numbers to a minimum > > makes things easier to track. > > I don't really follow your logic about IDEs and SDKs... This would be an > > argument to *not* synchronize releases I think, since iOS/Android/WP/BB > do > > not synchronize their SDK releases :P > > I don't think we can apply the cadence argument to platforms, but not to > > tools & plugins. Why would platforms be different in this respect? > > > > > > > >> > > Plugins and CLI tools I think we should just ship continuously. The > >> > > only question that remains in the 'how' of that is versioning. Mike > >> > > Brookes has advocated semver schema here wherein we version > platforms > >> > > separately from the tools using a compound version number. An > example > >> > > of this might be 3.0.0-0.14.3 wherein 3.0.0 represents our platforms > >> > > while 0.14.3 represents the CLI tool itself. > >> > > > >> > > I am not a fan of semver as that it is almost wholly conceptual and > >> > > thusly non-enforcable. It is a nice framework for reasoning but ppl > >> > > ignore half of the rules devaluing its promise. Also, it was > conceived > >> > > originally as a solution for globally installed packages which isn't > >> > > really an issue in modern situations. That said, having a versioning > >> > > scheme that exists, is well documented, and generally understood are > >> > > all positives for me. It would mean our deprec policy could push the > >> > > version numbers up quickly (which is fine). > >> > > > >> > > It is important to remember the reason for versioning, for our case, > >> > > is issue tracking and resolution but as our ecosystem grows it will > >> > > also play a very important role in dependency management. Especially > >> > > between plugins. More discreet versions: the better. > >> > > With the latest <engine> tag work being done ( > > https://issues.apache.org/jira/browse/CB-4490), platforms as well as > > plugins will be checked using semver. These checks will likely work > better > > if we try and follow semver. AFAICT, we mostly do already follow it, with > > the exception of our deprecation policy. > > > > > >> > > > >> > > (Andrew I think you should start a separate thread about killing off > >> > > cordova-js and moving into platforms for loading now that we have > >> > > mostly removed the plugins. I am very much in favor!) > >> > > > >> > Yeah, I regretted this almost immediately. Since this thread is > >> focusing on > >> > the platforms, I'll do just that! > >> > > >> > > >> > > > >> > > > >> > > On Tue, Aug 6, 2013 at 1:43 PM, Andrew Grieve <agri...@chromium.org > > > >> > > wrote: > >> > > > Want to have this as a discussion starter. > >> > > > > >> > > > We've previously established that: > >> > > > 1. Releases for plugman & CLI will not be tied to platform > releases > >> > > > 2. Releases to plugins will not be tied to platform releases > >> > > > > >> > > > That's not to say we shouldn't sometime co-ordinate them with > >> platform > >> > > > releases, but I think there would need to be a compelling reason > to > >> > > couple > >> > > > them. > >> > > > > >> > > > I'm wondering if it makes sense to not tie platform releases > >> together > >> > > > either? E.g. Allow an update to cordova-ios separately from > >> > > > cordova-blackberry10. > >> > > > > >> > > > Possible Advantages: > >> > > > - Releases will (hopefully) occur more frequently. Don't need to > >> wait > >> > > for > >> > > > synchronization with other platforms to do a release. > >> > > > > >> > > > Possible Disadvantages: > >> > > > - Might make for too many releases & spam our users with release > >> > notes > >> > > > too often > >> > > > - Might make us lazy and release platforms too infrequently > >> > > > - Might make version numbers for platforms not correspond > >> date-wise > >> > > with > >> > > > version numbers of other platforms (e.g. 3.1 ios != 3.1 android) > >> > > > > >> > > > > >> > > > Other considerations: > >> > > > cordova-js is a common piece here. Perhaps that could be pulled > >> out > >> > as > >> > > > well? > >> > > > > >> > > > Option 1: Bundle the exec bridge, platform bootstrap & plugin > loader > >> > with > >> > > > the platform, and have the rest available as a plugin. > >> > > > Option 2: Bundle exec bridge + platform bootstrap with the > platform, > >> > > bundle > >> > > > the plugin loader with plugman, put the rest in a plugin > >> > > > > >> > > > For reference, the only non-exec-bridge / start-up code I can see > >> is: > >> > > > ./cordova.js <--- hooks addEventListener + has exec bridge logic > >> > > > ./common/argscheck.js <--- strictly a helper for plugins > >> > > > ./common/base64.js <--- exec bridge depends on this > >> > > > ./common/builder.js <--- should be folded into modulemapper.js > >> > > > ./common/channel.js <--- start-up code needs this > >> > > > ./common/init.js <--- start-up code > >> > > > ./common/modulemapper.js <--- start-up code > >> > > > ./common/pluginloader.js <--- loads plugins on start-up > >> > > > ./common/urlutil.js <--- recently added helper for plugins > >> > > > ./common/utils.js <--- mostly misc stuff that may be mostly > >> unused? > >> > > > > >> > > > There's also: > >> > > > ./windows8/windows8/commandProxy.js > >> > > > which I assume is exec bridge releated. > >> > > > > >> > > > I think that argscheck & urlutil would be well-suited as > stand-alone > >> > > > plugins that other plugins depend on. > >> > > > >> > > >> > > > > >
