[Cordova Wiki] Update of "Proposal 2012 Separate 2.x Git Branch" by PatrickMueller

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Cordova Wiki" for change notification.

The "Proposal 2012 Separate 2.x Git Branch" page has been changed by PatrickMueller:
http://wiki.apache.org/cordova/Proposal%202012%20Separate%202.x%20Git%20Branch

New page:
= proposal to create a new long-lived git branch for 2.x work =

== tl;dr ==

We don't know what Cordova 2.x is, so create a new 2.x branch
in git where we figure it out, independent of the current
Cordova 1.x code.

== the problem ==

At the current time, the Cordova project is on the cusp of creating a new 1.6 release.  This is following a general cadence of a release per month, a cadence that we set for ourselves a while back.  The 1.6 release is designed to be a seamless upgrade for folks using previous 1.x releases.

At the same time, we are on a path to create a better/stronger/faster version of cordova, that we've tentatively labeled 2.x.  This version is intended to produce a stable public API for folks creating Cordova plugins, as well as provide infrastructure to allow people to easily add and remove plugins within their projects.  And, I assume, EVEN MOAR!

Unfortunately, we don't know the exact shape of 2.x at this point.  There are some sketches of what we want to it be, spread across the wiki, mailing lists, bug lists, and our brains.

The current strategy to handle seamless 1.x release upgrades and the new 2.x functionality, is to work on both, at the same time, in the same git branch.  IOW, each 1.x release also will contain incremental steps that take us to 2.x.

Now, for the 2.x functionality we're adding to the 1.x release, which is true?

 1. any 2.x functionality we add in the 1.x stream MUST NOT CHANGE UNTIL 2.(x+1)
 1. any 2.x functionality we add in the 1.x stream CAN CHANGE AT WILL

If we go 1), we are locking down 2.x functionality before seeing all of 2.x bits working together. We have to make all the design decisions for 2.x functionality as we add them to 1.x, before seeing the whole thing working together.  No chance at refactoring the 2.x functionality.

If we go 2), then as folks migrate from 1.x to 1.(x+1), they will be confronted with upgrading from the old 1.x version of the 2.x functionality, to the new 1.(x+1) version of the 2.x functionality.  For every 1.x release until the final 2.x release

Neither of those choices are appealing to me.

== a proposed solution ==

Rather than try to work on seamless 1.x upgrades and new 2.x stuff in the same git branch, create a new 2.x git branch for all the 2.x work.

Specifically:

Cordova 1.x releases:

 * will be based out of the current master branch(es), as before
 * will will be seamless upgrades from 1.(x-1) releases
 * will only contain bug fixes for previous 1.x releases
 * will not contain any references to the 2.x releases, meaning, no deprecation notices
 * will continue their monthly release cadence

Cordova 2.x work:

 * will be in a new "2.x" git branch (prolly a "2.x" branch for every relevant repo)
 * will not contain any unofficial defacto 1.x API, unless it happens to - by luck - be the exact same API between 1.x and 2.x.
 * is "clean slate / green field", in that there is no assumption about the way 1.x used to work.

The basic idea is separation of concerns.  We want to continue to provide stable, seamless 1.x releases, and also ship a 2.x release with stable API and functionality.  Working on both at the same time is painful, both for us and our users.  Working on them separately means you don't need to worry about version 1.x when you're working on 2.x, and vice versa.  And specifically, we don't need to add 2.x-isms to the 1.x stream, nor 1.x-ism to the 2.x stream.  

In addition, if after working on the 2.x work for an extended time, if we find that we need to change the "API" that we had been working on, we have not affected anyone using the 1.x streams.

== q&a ==

<<BR>> '''Q''': But we'll have to rebase fixes in 1.x back into 2.x!  HATE!
<<BR>> '''A''': Yeah, not a whole lot of fun.  In my view, the alternative is worse.

<<BR>> '''Q''': When do we rebase fixes from 1.x into 2.x?  As we find them, or after we're done with the shape of 2.x, but before actually finalizing 2.x?
<<BR>> '''A''': "it depends" and TBD and use your noggin.  We can track changes we made in 1.x as things that need to go into 2.x, using JIRA, or whatever, and do 'em all at the end of the 2.x release.  Or do them as we go.  We'll figure it out.

<<BR>> '''Q''': But I was almost done with the cordova-js integration for platform-xyz, and now you say we can't put it in 1.x because "no new API"!  Wat?
<<BR>> '''A''': Use your noggin.  The idea is to keep 1.x stable.  If you feel compelled to make enhancements to 1.x, go wild, but keep in mind the goal for 1.x is to provide seamless upgrades from 1.(x-1).  Please test a lot!  And also keep in mind that you'll be need to rebase that 1.x work into the 2.x stream.

<<BR>> '''Q''': When do we do deprecation?  Do we do deprecation at all?
<<BR>> '''A''': Yes, the last 1.x release will contain deprecation, because the last 1.x release means we're done with 2.x, and then we'll know what 2.x is, and can tell people how to migrate.

<<BR>> '''Q''': Do we have separate 1.x and 2.x teams?
<<BR>> '''A''': Of course not!  As an Apache project, no one is directing anyone's work (modulo if your "boss" is also also a Cordova committer!).  Work just on 1.x, work just on 2.x, work on both, whatever.

<<BR>> '''Q''': What is the cadence for 2.x?
<<BR>> '''A''': I would say "none".  As 2.x starts to gel, we can start looking for good points to make "drops" available for people who want to follow along, but not be involved in day-to-day development (eg, 3rd party plugin developers).  Presumably, plenty of warning that "we have not finalized the 2.x API", until the actual 2.x release.  As we approach the finish line, we'll plan up some release candidates.

<<BR>> '''Q''': [add your question here!]