If you would use a different helloworld app template (which is now possible to specify in both CLI and old workflow), then the pre-generatred platform config.xml template would likely be the wrong one, and thus this bundling for self documentation would be a disservice.
I don't see very much value in documentation for bundling the config.xml inside the platform template (when do we suspect users look at that file, as apposed to whats actually generated inside their project?). Users can read what is generated after adding a platform for their specific app using their chosen flow. I think that since bin/create can mush defaults.xml with app.xml for both flows, it should. On Mon, Sep 9, 2013 at 9:21 AM, Ian Clelland <iclell...@chromium.org> wrote: > On Mon, Sep 9, 2013 at 8:45 AM, Braden Shepherdson <bra...@chromium.org > >wrote: > > > The defaults.xml is only part of the CLI workflow, yes. It has no > relevance > > if you're not using CLI. BUT there is a complete config.xml in the > > bin/create template, and it can of course have the same values as you > would > > get from an unchanged CLI project (defaults.xml + app.xml). The > > configuration values you get from the templates should be the same in > both > > cases, I agree completely. > > > > Yes, I think it's definitely achievable to have the complete template > config.xml be exactly what you would get (modulo whitespace / comments / > etc) from installing the same sample app on the same platform with CLI. > > If we can maintain that standard, then the various files become almost > self-documenting; its easy to look at the final config.xml file in the > template to see how the pieces should fit together, and work out where each > of the tags originally came from. > > It might be worth trying to generate the template config.xml *using* cli, > just to maintain the correspondence between them. > > Ian > > > > Braden > > > > > > On Sun, Sep 8, 2013 at 5:28 AM, James Jong <wjamesj...@gmail.com> wrote: > > > > > Andrew - what I was thinking was pretty much what Michal wrote below. > > > Perhaps it was my interpretation of the original note but I thought > > > defaults was to be applied only in the CLI workflow. > > > > > > -James Jong > > > > > > On Sep 7, 2013, at 1:05 PM, Michal Mocny <mmo...@chromium.org> wrote: > > > > > > > With this proposal as it stands, I think that is already true (at > least > > > for > > > > the initial contents, obviously user can make edits later). > > > > > > > > Ie, defaults.xml + app.xml = initial config.xml for both cases, which > > use > > > > the same helloworld template's app.xml. > > > > > > > > If there are specific differences to the default values that we want, > > we > > > > maybe will want to use a different app.xml for each, but defaults.xml > > > > should be tied to a platform-version not to a workflow. > > > > > > > > -Michal > > > > > > > > > > > > On Sat, Sep 7, 2013 at 7:56 AM, Andrew Grieve <agri...@chromium.org> > > > wrote: > > > > > > > >> James - that's a nice goal, but I don't think it's feasible. Did you > > > have a > > > >> way to do that in mind? > > > >> > > > >> > > > >> On Fri, Sep 6, 2013 at 10:31 PM, James Jong <wjamesj...@gmail.com> > > > wrote: > > > >> > > > >>> I would like to see the defaults be applied in all cases. For > > > >>> consistency, less confusion, and easier documentation. If we add > or > > > >> change > > > >>> the defaults in a release, both workflows should get it. In my > mind, > > > the > > > >>> CLI platform config.xml should be equivalent to the bin/create one. > > > >>> > > > >>> -James Jong > > > >>> > > > >>> On Sep 6, 2013, at 11:06 AM, Michal Mocny <mmo...@chromium.org> > > wrote: > > > >>> > > > >>>> I thought we were adding support for the last bit (ie, app generic > > not > > > >>>> platform specific preferences) to "app.xml" which the helloworld > > > >> template > > > >>>> should ship with and bin/create should apply. > > > >>>> > > > >>>> -Michal > > > >>>> > > > >>>> > > > >>>> > > > >>>> On Fri, Sep 6, 2013 at 10:52 AM, Ian Clelland < > > iclell...@chromium.org > > > >>>> wrote: > > > >>>> > > > >>>>> The template version needs to be a complete config file for the > > > sample > > > >>> app, > > > >>>>> though. You should be able to run bin/create and then build the > > > Hello, > > > >>>>> Cordova app immediately. > > > >>>>> > > > >>>>> defaults.xml is supposed to be stripped right down to just the > > > >>>>> platform-specific options which, in theory, shouldn't need to be > > > >>> specified > > > >>>>> by every app. > > > >>>>> > > > >>>>> At least that's how it works in my head :) The distinction may be > > > less > > > >>>>> important than I'm imagining. > > > >>>>> > > > >>>>> Ian > > > >>>>> > > > >>>>> > > > >>>>> On Fri, Sep 6, 2013 at 9:08 AM, Michal Mocny < > mmo...@chromium.org> > > > >>> wrote: > > > >>>>> > > > >>>>>> If the content or format of defaults.xml and the initial > > config.xml > > > >>> will > > > >>>>> be > > > >>>>>> different then we should ship both -- but I don't think they > will > > > be, > > > >>> so > > > >>>>> I > > > >>>>>> think we just ship the template with a defaults file. > > > >>>>>> > > > >>>>>> -Michal > > > >>>>>> > > > >>>>>> > > > >>>>>> On Thu, Sep 5, 2013 at 11:19 PM, Ian Clelland < > > > >> iclell...@chromium.org > > > >>>>>>> wrote: > > > >>>>>> > > > >>>>>>> On Thu, Sep 5, 2013 at 5:16 PM, James Jong < > wjamesj...@gmail.com > > > > > > >>>>> wrote: > > > >>>>>>> > > > >>>>>>>> defaults.xml - Is that only used by CLI? And not used by > > > >> bin/create > > > >>>>>>>> scripts? > > > >>>>>>>> It was bit unclear to me from the description since both were > > > >>>>> mentioned > > > >>>>>>>> regarding the 2 xml files. > > > >>>>>>>> > > > >>>>>>> > > > >>>>>>> Yes, that's the idea. If you're using the bin/create scripts, > > then > > > >>>>> there > > > >>>>>> is > > > >>>>>>> a complete "config.xml" file in the template that will be used > > for > > > >>> your > > > >>>>>> new > > > >>>>>>> app. This is for strict backwards compatibility with anyone's > > > >> workflow > > > >>>>>> that > > > >>>>>>> doesn't currently include CLI. > > > >>>>>>> > > > >>>>>>> If you are using CLI, then we will construct a new config.xml > > file > > > >> for > > > >>>>>> you > > > >>>>>>> instead, from three sources: defaults.xml, which specifies all > of > > > >> the > > > >>>>>>> platform defaults; the various plugin.xml files, and your app's > > > >>>>>> config.xml > > > >>>>>>> file. The end-result should be the same, but you have a clear > > place > > > >> to > > > >>>>>>> override the defaults for your app that lives outside of your > > > >>> platforms > > > >>>>>>> directory, and the cordova team has a clear place to set those > > same > > > >>>>>>> defaults. > > > >>>>>>> > > > >>>>>>> Ian > > > >>>>>>> > > > >>>>>>> > > > >>>>>>>> > > > >>>>>>>> The new CLI prepare flow makes sense to me. > > > >>>>>>>> > > > >>>>>>>> -James Jong > > > >>>>>>>> > > > >>>>>>>> On Sep 5, 2013, at 2:21 PM, Michal Mocny <mmo...@chromium.org > > > > > >>>>> wrote: > > > >>>>>>>> > > > >>>>>>>>> We briefly discussed JSON and the two thoughts were: > > > >>>>>>>>> > > > >>>>>>>>> (1) We like it, but really what does it buy us? > > > >>>>>>>>> (2) This change is at the moment 100% compatible with all > > current > > > >>>>>>>> workflows > > > >>>>>>>>> (including upgrades from 3.0->3.1), and we think that's > > important > > > >>>>> for > > > >>>>>>>>> headache-less adoption. JSON would obviously not be. > > > >>>>>>>>> > > > >>>>>>>>> > > > >>>>>>>>> Regarding where to store the defaults, we had thought it > would > > be > > > >> a > > > >>>>>>> file > > > >>>>>>>>> bundled with the platform, perhaps in bin/templates? > > > >>>>>>>>> > > > >>>>>>>>> -Michal > > > >>>>>>>>> > > > >>>>>>>>> > > > >>>>>>>>> On Thu, Sep 5, 2013 at 12:38 PM, Brian LeRoux <b...@brian.io> > > > wrote: > > > >>>>>>>>> > > > >>>>>>>>>> The logic flow is much safer in this method. Where do you > > think > > > >>>>>>>> default.xml > > > >>>>>>>>>> should live? (Maybe it doesn't have to exist and defaults > can > > > >> just > > > >>>>>> be > > > >>>>>>>> vars > > > >>>>>>>>>> in the logic that does the processing?) > > > >>>>>>>>>> > > > >>>>>>>>>> Is this our opportunity to move to JSON? > > > >>>>>>>>>> > > > >>>>>>>>>> > > > >>>>>>>>>> On Thu, Sep 5, 2013 at 8:21 AM, Braden Shepherdson < > > > >>>>>>> bra...@chromium.org > > > >>>>>>>>>>> wrote: > > > >>>>>>>>>> > > > >>>>>>>>>>> config.xml as a build artifact for less suffering and > easier > > > >>>>>> upgrades > > > >>>>>>>>>>> Terminology > > > >>>>>>>>>>> > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> “platform config.xml” refers to the platform-specific > > > >>>>> config.xml > > > >>>>>>>>>> files, > > > >>>>>>>>>>> eg. platforms/android/res/xml/config.xml. This is the final > > > >>>>> file > > > >>>>>>> read > > > >>>>>>>>>> by > > > >>>>>>>>>>> Cordova at runtime. > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> “app config.xml” refers to the top-level config.xml found > in > > > >>>>>>>>>>> www/config.xml. > > > >>>>>>>>>>> > > > >>>>>>>>>>> Why the current situation is suffering > > > >>>>>>>>>>> > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> Chiefly, the platforms/foo/.../config.xml files are both > the > > > >>>>>> input > > > >>>>>>>> and > > > >>>>>>>>>>> output of munging by Plugman and the user. This sucks. It > > makes > > > >>>>>>>>>>> automatic upgrades difficult because everybody has a > > customized > > > >>>>>>>>>>> config.xml > > > >>>>>>>>>>> file in their platforms. It also makes plugin rm harder and > > > >>>>> less > > > >>>>>>>>>> robust > > > >>>>>>>>>>> in > > > >>>>>>>>>>> CLI than it needs to be. > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> Currently only some tags in the app config.xml are actually > > > >>>>>>> honoured. > > > >>>>>>>>>>> Others are ignored, and this has tripped up our users. > > > >>>>>>>>>>> > > > >>>>>>>>>>> > > > >>>>>>>>>>> Goals > > > >>>>>>>>>>> > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> bin/create workflow is unchanged. > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> Final content of the platform config.xml file is unchanged, > > > >>>>>> though > > > >>>>>>>> the > > > >>>>>>>>>>> method of building it in the CLI can change. > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> CLI workflow is unchanged, in terms of what a user types. > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> platform config.xml stops being both input and output under > > > >>>>> CLI. > > > >>>>>>> Less > > > >>>>>>>>>>> munging, and easier upgrades. In short, platform config.xml > > > >>>>> files > > > >>>>>>>>>> become > > > >>>>>>>>>>> build artifacts. > > > >>>>>>>>>>> > > > >>>>>>>>>>> What we propose to do about it > > > >>>>>>>>>>> > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> First, adjust the platform template (used by bin/create) to > > > >>>>>> contain > > > >>>>>>>>>> two > > > >>>>>>>>>>> files: > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> defaults.xml, which is versioned, immutable, and tucked > > away > > > >>>>>>>>>>> somewhere (only CLI accesses it) and contains only the > > > >>>>>>>>>>> Cordova-specified > > > >>>>>>>>>>> platform defaults, such as the preferences, any default > > > >>>>>>>>>>> whitelist entries, > > > >>>>>>>>>>> etc. It does NOT contain any <author>, <name> or other > > such > > > >>>>>>> tags. > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> platform config.xml, which is the same as it currently > > is, a > > > >>>>>>>>>> complete > > > >>>>>>>>>>> config.xml for the HelloWorld app. This means behavior > is > > > >>>>>>>> unchanged > > > >>>>>>>>>>> for people who are not using CLI. Plugman still munges > > this > > > >>>>>> file > > > >>>>>>>>>> and > > > >>>>>>>>>>> outputs back to it, same as now. > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> Second, adjust the CLI’s cordova create template so that > its > > > >>>>>>>> top-level > > > >>>>>>>>>>> app config.xml contains <name>, <author>, <content>, etc. - > > > >>>>> tags > > > >>>>>>> the > > > >>>>>>>>>>> user is likely to edit. > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> Third, modify the CLI so that the new cordova prepare flow > > is: > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> Delete the old platform config.xml. > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> Copy the defaults.xml to config.xml. > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> Re-run the Plugman config munging for every plugin, > > > >>>>> modifying > > > >>>>>>> the > > > >>>>>>>>>>> fresh platform config.xml. (The order here is > deliberately > > > >>>>>>>>>> undefined; > > > >>>>>>>>>>> plugins should already not be relying on this.) > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> Run the config munging for the app’s config.xml as well. > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> This results in a freshly built, build-artifact platform > > > >>>>>>>>>> config.xml. > > > >>>>>>>>>>> Users should not be editing it; their top-level app > > > >>>>> config.xml > > > >>>>>>>>>>> has the last > > > >>>>>>>>>>> word and will override any settings the defaults or > > plugins > > > >>>>>>> might > > > >>>>>>>>>>> make. > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> Note that this means we shouldn’t be needlessly > setting > > > >>>>>>>> defaults > > > >>>>>>>>>>> in the app config.xml, since this might prevent > > plugins > > > >>>>>> from > > > >>>>>>>>>>> changing > > > >>>>>>>>>>> things that need changing. > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> Fourth, extend the app config.xml format so that it can > have > > > >>>>>>>>>>> <platform>tags, like a plugin.xml. > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> Into this it can put platform-specific things like > > > >>>>>>> splashscreens, > > > >>>>>>>>>>> preferences and other things, rather than mixing these > > > >>>>>> together > > > >>>>>>> in > > > >>>>>>>>>>> the > > > >>>>>>>>>>> config. > > > >>>>>>>>>>> - > > > >>>>>>>>>>> > > > >>>>>>>>>>> In particular, it can have <config-file> tags in the > usual > > > >>>>>>> format > > > >>>>>>>>>>> > > > >>>>>>>>>> > > > >>>>>>>> > > > >>>>>>>> > > > >>>>>>> > > > >>>>>> > > > >>>>> > > > >>> > > > >>> > > > >> > > > > > > > > >
