Just did some pull requests for docs, and wanted to share that I think there is really good reason to stop versioning our docs.
- One PR fixed broken links in the 3.5.0 docs that pointed to plugin dev branches. --> Any external links in versioned docs may break at any time! - One PR was for the new splashscreen support in cordova-lib --> This won't make it out until the next platform release, even though it's a shipped feature in CLI! Versioning our docs has some merit, but it also causes old versions of docs to have bugs that don't get fixed, and it adds delays to new docs. Because the things we are documenting are released & versioned separately, I think the only sane path forward is to stop versioning the docs (and annotate with "supported in android 3.6.0+"). On Thu, Aug 14, 2014 at 5:28 PM, Brian LeRoux <b...@brian.io> wrote: > Yes, that email was very clearly very rushed! Too much on my plate. > > The ./bin/create scripts generate 'platform' projects. We need to keep > those. They each should use a common seed template for www assets. Ideally > the platform knows about icons and splashscreens too, so higher level > abstracts only need to pass those things down to the platforms. I have no > idea where we are with that part. Its always been a headache and one of the > things keeping ./platforms in version control. > > Higher up the chain I think we should break out the 'create' part of > cordova-lib into a completely separate module that other downstream things > can use. For example, with PhoneGap Developer Apps you don't need the > entire CLI (or any native bits) but just a create command and the > phonegap-connect modules for serving the content to the app (app harness > flow too). > > > > > On Thu, Aug 14, 2014 at 12:59 PM, Andrew Grieve <agri...@chromium.org> > wrote: > >> Could you elaborate Brian? Do you mean to stop support bin/create scripts? >> Or to have all platforms node-depend on a templates module? Have one module >> vs one-template-per-platform? Does this apply to both icons/splashscreens >> as well as default www/? >> >> >> On Thu, Aug 14, 2014 at 3:45 PM, Carlos Santana <csantan...@gmail.com> >> wrote: >> >> > +1 one way of doing it >> > >> > >> > On Thu, Aug 14, 2014 at 1:21 PM, Brian LeRoux <b...@brian.io> wrote: >> > >> > > rather than bundle app-hello-world I'd rather we *extracted* >> > > cordova-project-create from cordova-lib into its own module so thing >> that >> > > create cordova projects only have one way of doing it >> > > >> > > >> > > >> > > On Thu, Aug 14, 2014 at 7:58 AM, Carlos Santana <csantan...@gmail.com> >> > > wrote: >> > > >> > > > Each platform should carry their default contents including set of >> > icons >> > > > and screens for none CLI workflow, the platform can keep taking them >> > from >> > > > app-hello-world as part of it's independent platform release. >> > > > >> > > > For app-hello-world it should be tag and release with the tools (CLI >> > > > release) as it's use as the default template for "create" >> > > > >> > > > Now that I think CLI and config.xml supports icons and screens, the >> > > default >> > > > app created by CLI should include the "res/" icons and screens, >> > > including a >> > > > config.xml configured with proper values pointing to the images. >> > > > This will be easier to end user to figure out on disk what files it >> > needs >> > > > to be modified in the "res/" directory on CLI project. >> > > > >> > > > This can also be optimized that "res/" contents get populated as the >> > > > "cordova platform add" gets executed so user only gets in "res/" and >> > > > "config.xml" only the platforms added. >> > > > >> > > > I was looking into this recently as I'm trying to create a new >> > universal >> > > > www template for IBM Worklight to be use by cordova CLI, but I got >> > brain >> > > > stop on how do I create a git repo that includes all my default icons >> > and >> > > > screens that user will replace, but don't want to pollute their >> cordova >> > > > project with images from a platform their not dealing with yet, and >> how >> > > to >> > > > add those icons and screens when they do an "platform add" for a new >> > > > platform. >> > > > >> > > > Maybe this deserves a new thread. >> > > > >> > > > net is that app-hello-world should be release tad with tools not >> > > platforms >> > > > releases. >> > > > >> > > > >> > > > >> > > > >> > > > >> > > > On Thu, Aug 14, 2014 at 9:48 AM, Michal Mocny <mmo...@chromium.org> >> > > wrote: >> > > > >> > > > > Does hello-world even need to be versioned at all, then? Its just >> > part >> > > > of >> > > > > the platform/cli release, and its assets are voted on as part of >> > that? >> > > > > >> > > > > >> > > > > On Thu, Aug 14, 2014 at 9:43 AM, Andrew Grieve < >> agri...@chromium.org >> > > >> > > > > wrote: >> > > > > >> > > > > > app-hello-world is quite a weird one now. There's two parts to >> it: >> > > > > > 1) default icons & splashscreens - copied into each platform >> > > > > > 2) default www/ - copied into each platform & into lazy_load'ed >> by >> > > CLI >> > > > > > >> > > > > > For 2) - I think we should stop lazy loading. Maybe just copy it >> > into >> > > > the >> > > > > > CLI repo. >> > > > > > >> > > > > > For versioning though - I think the repo should be tagged / >> > versioned >> > > > > > independently whenever it makes sense. >> > > > > > >> > > > > > >> > > > > > On Thu, Aug 14, 2014 at 9:16 AM, Ian Clelland < >> > > iclell...@chromium.org> >> > > > > > wrote: >> > > > > > >> > > > > > > Currently, mobile-spec needs to be tagged with platform >> versions, >> > > > since >> > > > > > it >> > > > > > > contains tests for those platforms, outside of the plugin tests >> > > (like >> > > > > the >> > > > > > > bridge and whitelist tests). As soon as we can move those out, >> > then >> > > > > > > mobilespec becomes a generic test runner for Cordova, and we >> can >> > > just >> > > > > tag >> > > > > > > it independently of platforms. >> > > > > > > >> > > > > > > >> > > > > > > On Wed, Aug 13, 2014 at 6:12 PM, Steven Gill < >> > > stevengil...@gmail.com >> > > > > >> > > > > > > wrote: >> > > > > > > >> > > > > > > > New question >> > > > > > > > >> > > > > > > > How does tagging and versioning for cordova-app-hello-world >> and >> > > > > > > > cordova-mobile-spec look in this new world of independent >> > > releases? >> > > > > > > > >> > > > > > > > Currently: >> > > > > > > > >> > > > > > > > 1) They both get branched and tagged at the beginning of a >> > > cadence >> > > > > > > release. >> > > > > > > > 2) The hello world app is supposed to be manually copied to >> > > > platforms >> > > > > > if >> > > > > > > > changes exist. >> > > > > > > > >> > > > > > > > Suggestions: >> > > > > > > > >> > > > > > > > A) They both get tagged independently of platforms. Won't >> > happen >> > > > > often >> > > > > > > > unless they are changing (the app rarely changes). >> > > > > > > > >> > > > > > > > B) They get tagged platform-version when doing a release. So >> > > mobile >> > > > > > spec >> > > > > > > > would have a tag android-3.6.0 when we are doing the 3.6.0 >> > > release. >> > > > > > > > >> > > > > > > > I think we should stop branching for these two repos. Doesn't >> > add >> > > > > much >> > > > > > > > value. The tag will take us back to the state when the >> platform >> > > was >> > > > > > > > released. >> > > > > > > > >> > > > > > > > Thoughts? Other suggestions? >> > > > > > > > >> > > > > > > > >> > > > > > > > On Fri, Aug 8, 2014 at 11:26 AM, Andrew Grieve < >> > > > agri...@chromium.org >> > > > > > >> > > > > > > > wrote: >> > > > > > > > >> > > > > > > > > On Tue, Jul 29, 2014 at 5:00 PM, Steven Gill < >> > > > > stevengil...@gmail.com >> > > > > > > >> > > > > > > > > wrote: >> > > > > > > > > >> > > > > > > > > > Started creating issues to keep track of all of these >> > things. >> > > > > > > > > > >> > > > > > > > > > Master issue can be seen at >> > > > > > > > > https://issues.apache.org/jira/browse/CB-7221 >> > > > > > > > > > >> > > > > > > > > > Setting CLI to version 4.0.0 sounds good to me. We can >> > > mention >> > > > in >> > > > > > the >> > > > > > > > > > release blog post how platforms are on their own schedule >> > > now. >> > > > > > > > > > >> > > > > > > > > > Option 3 for docs >> > > > > > > > > > - Docs get same version as CLI & get tagged alongside cli >> > > > > releases >> > > > > > > > > > - We can still annotate with "added in X.X.X, removed in >> > > X.X.X" >> > > > > > where >> > > > > > > > it >> > > > > > > > > > makes sense. (like the upgrade guides) >> > > > > > > > > > - Point docs.cordova.io to edge >> > > > > > > > > > - Dropdown will show tagged versions >> > > > > > > > > > Pros: >> > > > > > > > > > - Keeps a public history of older docs at a point in >> time. >> > > Easy >> > > > > to >> > > > > > > use >> > > > > > > > > for >> > > > > > > > > > people who don't want the latest >> > > > > > > > > > - Gives us flexibility in changing docs and not worrying >> > > about >> > > > > > older >> > > > > > > > > > versions. >> > > > > > > > > > >> > > > > > > > > > Thoughts? >> > > > > > > > > > >> > > > > > > > > >> > > > > > > > > Each new version of the docs has significant space >> > requirements >> > > > > since >> > > > > > > we >> > > > > > > > > don't de-dupe images across versions or translations. Not >> the >> > > end >> > > > > of >> > > > > > > the >> > > > > > > > > world, but the repo is already > 1GB, so it is annoying. >> > > > > > > > > >> > > > > > > > > I don't think it's common that we delete docs, so maybe we >> > > could >> > > > > just >> > > > > > > > > create new versions when we do purges? Otherwise, the old >> > > > versions >> > > > > of >> > > > > > > > docs >> > > > > > > > > just have bugs and are strictly worse than the newest set, >> I >> > > > think. >> > > > > > > > > >> > > > > > > > > >> > > > > > > > > >> > > > > > > > > > >> > > > > > > > > > -Steve >> > > > > > > > > > >> > > > > > > > > > >> > > > > > > > > > >> > > > > > > > > > >> > > > > > > > > > >> > > > > > > > > > On Mon, Jul 28, 2014 at 8:26 AM, Michal Mocny < >> > > > > mmo...@chromium.org >> > > > > > > >> > > > > > > > > wrote: >> > > > > > > > > > >> > > > > > > > > > > On Mon, Jul 28, 2014 at 5:41 AM, Gorkem Ercan < >> > > > > > > > gorkem.er...@gmail.com> >> > > > > > > > > > > wrote: >> > > > > > > > > > > >> > > > > > > > > > > > >> > > > > > > > > > > > This has been discussed long enough and even for >> those >> > > > > > downstream >> > > > > > > > > > > > distros and tools who will have to adjust, it is >> better >> > > to >> > > > > > > finalize >> > > > > > > > > it. >> > > > > > > > > > > > >> > > > > > > > > > > > Overall I like the plan, my major concern was with >> > > cadence >> > > > > > > > releaeses >> > > > > > > > > > > gone, >> > > > > > > > > > > > the lack of a >> > > > > > > > > > > > name/tag/version number for Cordova, and a >> description >> > of >> > > > its >> > > > > > > > > contents. >> > > > > > > > > > > > Now, this is >> > > > > > > > > > > > addressed with CLI and package.json file. >> > > > > > > > > > > > >> > > > > > > > > > > > My +1 for this. >> > > > > > > > > > > > >> > > > > > > > > > > > >> > > > > > > > > > > > On Fri, Jul 25, 2014 at 05:25:28PM -0400, Andrew >> Grieve >> > > > > wrote: >> > > > > > > > > > > > > Wanted to start a thread for everyone to share what >> > > > > concrete >> > > > > > > > > changes >> > > > > > > > > > > > they'd >> > > > > > > > > > > > > like to see happen before we start having platforms >> > > being >> > > > > > > > released >> > > > > > > > > in >> > > > > > > > > > > an >> > > > > > > > > > > > > unsynchronized fashion. >> > > > > > > > > > > > > >> > > > > > > > > > > > > I'll start :) >> > > > > > > > > > > > > >> > > > > > > > > > > > > cordova-js: >> > > > > > > > > > > > > - cordova.version returns a value computed from >> the >> > > > > > cordova-js >> > > > > > > > git >> > > > > > > > > > > tag. >> > > > > > > > > > > > > - Let's deprecate this field >> > > > > > > > > > > > > - And create "cordova.platformVersion" >> > > > > > > > > > > > > - And update our release process to have the >> > version >> > > > set >> > > > > > > based >> > > > > > > > > on >> > > > > > > > > > > the >> > > > > > > > > > > > > platform's version rather than the tag within >> > > cordova-js. >> > > > > > > > > > > > >> > > > > > > > > > > > What will be the value for cordova.version during >> > > > deprecation >> > > > > > > > period? >> > > > > > > > > > > > >> > > > > > > > > > > > > >> > > > > > > > > > > > > Cordova-docs: >> > > > > > > > > > > > > - Most of the docs are not actually affected by >> > > platform >> > > > > > > > versions. >> > > > > > > > > > > > > - Mainly though, it's the platform guides that >> are. >> > > > > > > > > > > > > - Two options that I see: >> > > > > > > > > > > > > - 1) Set default version to "edge" & always >> > annotate >> > > > > with >> > > > > > > > "added >> > > > > > > > > > in >> > > > > > > > > > > > > X.X.X, removed in X.X.X" >> > > > > > > > > > > > > - 2) Move guides to live in platform repos and >> > link >> > > to >> > > > > > them >> > > > > > > > from >> > > > > > > > > > > docs. >> > > > > > > > > > > > > >> > > > > > > > > > > > > cordova-cli: >> > > > > > > > > > > > > - Set version to 4.0.0 just to make it so that it >> > > > doesn't >> > > > > > map >> > > > > > > > to >> > > > > > > > > > any >> > > > > > > > > > > > > existing platform versions >> > > > > > > > > > > > >> > > > > > > > > > > > Not sure if this matters. Platforms will catch up to >> > > 4.0.0 >> > > > > soon >> > > > > > > > > enough. >> > > > > > > > > > > > >> > > > > > > > > > > >> > > > > > > > > > > CLI version is currently "3.5.0-0.2.7-dev". We need to >> > > > change >> > > > > it >> > > > > > > to >> > > > > > > > > > > something thats valid semver, and preferably somewhat >> > > > > compatible >> > > > > > > with >> > > > > > > > > the >> > > > > > > > > > > previous versions. Choices I think are: >> > > > > > > > > > > - 3.6.0 >> > > > > > > > > > > - 4.0.0 >> > > > > > > > > > > - A Complete reset >> > > > > > > > > > > >> > > > > > > > > > > I'm also in favour of 4.0.0 given those options. >> > > > > > > > > > > >> > > > > > > > > > > I am mildly concerned that with the looming 4.0 >> releases >> > of >> > > > > > > > platforms, >> > > > > > > > > > > users will think this is a cad-ver update and not >> > > appreciate >> > > > > the >> > > > > > > > change >> > > > > > > > > > of >> > > > > > > > > > > strategy, but partially think that may be a good thing >> > too >> > > > > (slow >> > > > > > > > > > > comfortable transition). >> > > > > > > > > > > >> > > > > > > > > > > >> > > > > > > > > > > > >> > > > > > > > > > > > > >> > > > > > > > > > > > > Release Process: >> > > > > > > > > > > > > - Tag cordova-js for each platform release with >> > > > > > > > > "PLATFORM-VERSION" >> > > > > > > > > > > > > - Rewrite >> > > > > > > > > > > > > >> > > > > > > > > > > > >> > > > > > > > > > > >> > > > > > > > > > >> > > > > > > > > >> > > > > > > > >> > > > > > > >> > > > > > >> > > > > >> > > > >> > > >> > >> https://github.com/apache/cordova-coho/blob/master/docs/cadence-release-process.md >> > > > > > > > > > > > > as "platforms-release-process" >> > > > > > > > > > > > >> > > > > > > > > > > >> > > > > > > > > > >> > > > > > > > > >> > > > > > > > >> > > > > > > >> > > > > > >> > > > > >> > > > >> > > > >> > > > >> > > > -- >> > > > Carlos Santana >> > > > <csantan...@gmail.com> >> > > > >> > > >> > >> > >> > >> > -- >> > Carlos Santana >> > <csantan...@gmail.com> >> > >>
