On Fri, Aug 16, 2013 at 5: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 > > I like this, as it separates the fast-moving, feature-based semantic version of any given component from the API level, and interoperability promises, of the "Cadence Version". What, then, is the granularity of the Cadence Version intended to be? Is is the "3" in Cordova 3.0, and will stay at 3 until it hits 4 next year? (Or, just as descriptively, we can say that it is at "Cordova Fancy-Pants" now, and eventually progress to "Cordova Enraged-Wombat") Or is it going to have major and minor components as well, and advance roughly monthly, as before? > 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. > >> > > > >> > > >> > > > > >
