Mailing-List: contact dev-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cordova.apache.org
Received-SPF: pass (nike.apache.org: domain of luoq@polyvi.com designates
 54.238.162.12 as permitted sender)
Date: Fri, 14 Mar 2014 14:27:49 +0800
From: luoq <luoq@polyvi.com>
To: dev <dev@cordova.apache.org>
Message-ID: <etPan.5322a165.27538b89.a4ca@QimatoMacBook-Air.local>
In-Reply-To: <etPan.53222b05.8edbdab.b815@HooperX.local>
References: 
 <CABiQX1XudTfrF5HMyM9h9UYQ2jdZLm3SrYQKPjxUBU9tVw6aWQ@mail.gmail.com>
 <CAEeF2Tf0=9t858Vj_bPoCde7xyJs54j_Q9XPcUYzUptx4=8zsQ@mail.gmail.com>
 <CADVgkyN7m2wdtoW2Jzy_8PKe-1XFpbmA_wwGR4vL48QSUF6=0g@mail.gmail.com>
 <etPan.53222b05.8edbdab.b815@HooperX.local>
Subject: Re: Releasing Platforms Independently
MIME-Version: 1.0
Content-Type: multipart/alternative; boundary="5322a165_526acdf_a4ca"

--5322a165_526acdf_a4ca
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline

=46or docs, why don't you guys use yuidoc or jsduck, such js documentatio=
n tools, to manage docs=3F There is =40since to indicate version, and ric=
h builtin tags to use.

=46urthermore, inline js documentation is much easier to maintain than a =
separate md doc, I believe.

It will be worse that the static markdown docs will get messed and hard t=
o explore when there are lots of versions someday.

Thanks.


=E2=80=94=C2=A0
Best Regards,
Qi LUO
Sent with Air

On 14 March, 2014 at 6:03:18, tommy-carlos (tommy=40devgeeks.org) wrote:

+1 for docs. =20

Pretty big pain point for devs. =20

On 14 March 2014 at 7:01:18 am, Brian LeRoux (b=40brian.io) wrote: =20

I definitely love the idea of making this part of the machine move faster=
, =20
and treating platforms as a dependency of the CLI in theory should not ha=
ve =20
any cross cutting impacts *unless* we decide to change the plugin =20
interface. Our CLI version effectively becomes the 'Cordova' version. Doc=
s =20
needs an overhaul regardless so I see no issue there. =20

How do you guys think we go about tackling this=3F Should we consider =20
starting w/ the Docs since that seems to be the squeakiest wheel=3F =20


On Thu, Mar 13, 2014 at 9:55 AM, Michal Mocny <mmocny=40chromium.org> wro=
te:  =20

> On Thu, Mar 13, 2014 at 11:38 AM, Andrew Grieve <agrieve=40chromium.org=
 =20
> >wrote: =20
> =20
> > I think it would be beneficial if we could release updates to platfor=
ms =20
> > independent from others. Why=3F =20
> > - =46ar easier to do one-off platform releases (e.g. quick turn-aroun=
d on a =20
> > security update, quick turn around on iOS is broken on the latest Xco=
de) =20
> > - Platforms can release on their own schedule (big new features will =
get =20
> > released sooner) =20
> > =20
> > =20
> > This doesn't come without bumps though. I'd like to use this thread t=
o =20
> > explore the idea and to enumerate what would have to change to get th=
ere. =20
> > =20
> > Here are some things I can think of: =20
> > =20
> > Cordova-docs: =20
> > - We have a version drop-down in the top-right corner. =20
> > - I think this would mean getting rid of the version drop down (or =20
> rather, =20
> > not adding new entries to it). =20
> > - Always have people pointed at =22edge=22 =20
> > - =46or things that refer to specific versions, put them inline =20
> > - E.g. like we do for upgrade guides =20
> > - When a new API is introduced & is documented, we'll have to be bett=
er =20
> at =20
> > annotating what version it showed up in. =20
> > =20
> =20
> Huge +1. This is a bit of an effort, sure, but every single damn time I=
 =20
> search for a cordova question I end up on docs for cordova 2.3 or =20
> something, the version switcher takes me to home, and manually editing =
for =20
> =22edge=22 doesn't always match urls. =20
> =20
> =20
> > =20
> > =20
> > Blog posts: =20
> > - We currently do one release announcement for all the platforms. =20
> > - I think it'll actually be a good thing to have shorter & more focus=
ed =20
> > release announcements (one post per platform) =20
> > =20
> =20
> I'm fine with this, but I do still think we want some special outlet to=
 be =20
> =22louder=22 about larger changes much like we have been with monthly c=
adence =20
> releases. =20
> =20
> =20
> > =20
> > =20
> > Mobile-spec: =20
> > - This is on the way out anyway I think, with moving tests into plugi=
ns. =20
> > - Even so, not a big deal to not have this strictly versioned. =20
> =20
> =20
> > =20
> > cordova-js: =20
> > - Platforms will have cordova-js cut at different times. =20
> > - I don't think this is a good or a bad thing. =20
> > - JS versioning stamped at the top of the file: =20
> > - Change to have both platform version as well as JS version availabl=
e =20
> > at runtime. =20
> > - JS version will just be a =22git describe=22 =20
> > =20
> > CLI versioning: =20
> > - It won't make sense to version it as CadVer-SemVer anymore =20
> > - This essentially kills off the idea of CadVer. =20
> > - That scheme wasn't working well anyways since you can't actually =20
> depend =20
> > on the SemVer part of it in a SemVer way (you can't say =20
> > dependency=3D=22>x.x.x-0.2=22) =20
> > - CadVer-SemVer, I think, is causing people to not update their tools=
 =20
> if =20
> > they aren't ready to update their platforms. =20
> > - With this change, we should just have CLI be SemVer only. =20
> > - If we move platforms to NPM, we wouldn't even need to push CLI =20
> updates =20
> > with platforms. =20
> > =20
> =20
> This is another huge benefit, I think. =20
> =20
> =20
> > =20
> > =20
> > =20
> > Anything else=3F Please feel free to add inline here on things I've m=
issed =20
> > out, or on things you'd be concerned about changing. =20
> > =20
> =20
> Thanks for going over this. Sounds to me like this is almost entirely =20
> upside. =20
> =20


--5322a165_526acdf_a4ca--