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 mmocny@google.com designates
 209.85.214.181 as permitted sender)
MIME-Version: 1.0
Sender: mmocny@google.com
In-Reply-To: 
 <CAK_TSXJRvGf6m2u8BeiuAxBWWtyM-_+fr_5LCxvrq=-zyXy6tQ@mail.gmail.com>
References: 
 <CAMk5LLme8qdFkvGxJ9+CKtX1kvfvG5kipzYxyyQXyo-TDmw9bQ@mail.gmail.com>
 <CADVgkyNrLHZ+3EsOq4y4s+HMsEh-CKjSmuUsUhJAd3W9UPtKHA@mail.gmail.com>
 <CAEeF2Tc_zq6OAjPCvTu1BMiQCL9Mr_RgsAVVBY9QnJ8JAk9q-w@mail.gmail.com>
 <05A23401-4C21-41A1-AAC3-3BA626006581@gmail.com>
 <CAK_TSX+yNp4mDTz3jutyauxFor=XdzfVtoRDgyU9oAOGyH6ffg@mail.gmail.com>
 <CAEeF2Tc4LBvcP-uFuDfQnV3Mu6jwv5oHOAyzfVsHeAUdLZE8qA@mail.gmail.com>
 <CAK_TSXL9vzMJE=FBo4kjhboNaCKbRrxhoAsTTj-4=G_ovPkfwA@mail.gmail.com>
 <CAEeF2Td8656YLNZBDSpuQ-uFmisZv8PcFv=HyycH3kn15_aTvQ@mail.gmail.com>
 <FAEAB02F-47B6-4FAF-B3F7-C896D0A24111@gmail.com>
 <CABiQX1UROZVeyqCRsoR+0GOLcZDX7eq=AFBmWOngRqY0Zq96GQ@mail.gmail.com>
 <CAEeF2TfAGmgbwjoBxY6X+CajKLemPS+8+4vrPfShuyxpN7gL_g@mail.gmail.com>
 <596B0F9A-5423-410B-A79E-894005CB30FA@gmail.com>
 <CAMk5LL=D7vxX0WnVW61s9=qZogufhEMvenv_YFkLdgt+TuJZ6g@mail.gmail.com>
 <CAK_TSXJRvGf6m2u8BeiuAxBWWtyM-_+fr_5LCxvrq=-zyXy6tQ@mail.gmail.com>
From: Michal Mocny <mmocny@chromium.org>
Date: Mon, 9 Sep 2013 09:48:27 -0400
Message-ID: 
 <CAEeF2Td3Zig02MHmXdtwx3veJKwi6UuGkgvSQQQjM37EPze9Mw@mail.gmail.com>
Subject: Re: config.xml as a build artifact for less suffering and easier
 upgrades
To: dev <dev@cordova.apache.org>
Content-Type: multipart/alternative; boundary=089e0111bca4c6469b04e5f3a5b7

--089e0111bca4c6469b04e5f3a5b7
Content-Type: text/plain; charset=windows-1252
Content-Transfer-Encoding: quoted-printable

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 <iclelland@chromium.org> wrote=
:

> On Mon, Sep 9, 2013 at 8:45 AM, Braden Shepherdson <braden@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 ea=
ch
> 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 <wjamesjong@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 <mmocny@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 =3D initial config.xml for both cases, w=
hich
> > use
> > > > the same helloworld template's app.xml.
> > > >
> > > > If there are specific differences to the default values that we wan=
t,
> > we
> > > > maybe will want to use a different app.xml for each, but defaults.x=
ml
> > > > should be tied to a platform-version not to a workflow.
> > > >
> > > > -Michal
> > > >
> > > >
> > > > On Sat, Sep 7, 2013 at 7:56 AM, Andrew Grieve <agrieve@chromium.org=
>
> > > wrote:
> > > >
> > > >> James - that's a nice goal, but I don't think it's feasible. Did y=
ou
> > > have a
> > > >> way to do that in mind?
> > > >>
> > > >>
> > > >> On Fri, Sep 6, 2013 at 10:31 PM, James Jong <wjamesjong@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 on=
e.
> > > >>>
> > > >>> -James Jong
> > > >>>
> > > >>> On Sep 6, 2013, at 11:06 AM, Michal Mocny <mmocny@chromium.org>
> > wrote:
> > > >>>
> > > >>>> I thought we were adding support for the last bit (ie, app gener=
ic
> > 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 <
> > iclelland@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 b=
e
> > > >>> 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 <
> mmocny@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 <
> > > >> iclelland@chromium.org
> > > >>>>>>> wrote:
> > > >>>>>>
> > > >>>>>>> On Thu, Sep 5, 2013 at 5:16 PM, James Jong <
> wjamesjong@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 wer=
e
> > > >>>>> 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 use=
d
> > 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 al=
l
> 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 thos=
e
> > same
> > > >>>>>>> defaults.
> > > >>>>>>>
> > > >>>>>>> Ian
> > > >>>>>>>
> > > >>>>>>>
> > > >>>>>>>>
> > > >>>>>>>> The new CLI prepare flow makes sense to me.
> > > >>>>>>>>
> > > >>>>>>>> -James Jong
> > > >>>>>>>>
> > > >>>>>>>> On Sep 5, 2013, at 2:21 PM, Michal Mocny <mmocny@chromium.or=
g
> >
> > > >>>>> 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 <
> > > >>>>>>> braden@chromium.org
> > > >>>>>>>>>>> wrote:
> > > >>>>>>>>>>
> > > >>>>>>>>>>> config.xml as a build artifact for less suffering and
> easier
> > > >>>>>> upgrades
> > > >>>>>>>>>>> Terminology
> > > >>>>>>>>>>>
> > > >>>>>>>>>>> -
> > > >>>>>>>>>>>
> > > >>>>>>>>>>> =93platform config.xml=94 refers to the platform-specific
> > > >>>>> config.xml
> > > >>>>>>>>>> files,
> > > >>>>>>>>>>> eg. platforms/android/res/xml/config.xml. This is the fin=
al
> > > >>>>> file
> > > >>>>>>> read
> > > >>>>>>>>>> by
> > > >>>>>>>>>>> Cordova at runtime.
> > > >>>>>>>>>>> -
> > > >>>>>>>>>>>
> > > >>>>>>>>>>> =93app config.xml=94 refers to the top-level config.xml f=
ound
> 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 a=
nd
> > > >>>>> less
> > > >>>>>>>>>> robust
> > > >>>>>>>>>>> in
> > > >>>>>>>>>>> CLI than it needs to be.
> > > >>>>>>>>>>> -
> > > >>>>>>>>>>>
> > > >>>>>>>>>>> Currently only some tags in the app config.xml are actual=
ly
> > > >>>>>>> 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 unchange=
d,
> > > >>>>>> 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 und=
er
> > > >>>>> CLI.
> > > >>>>>>> Less
> > > >>>>>>>>>>> munging, and easier upgrades. In short, platform config.x=
ml
> > > >>>>> 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 tucke=
d
> > away
> > > >>>>>>>>>>>    somewhere (only CLI accesses it) and contains only the
> > > >>>>>>>>>>> Cordova-specified
> > > >>>>>>>>>>>    platform defaults, such as the preferences, any defaul=
t
> > > >>>>>>>>>>> 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=92s cordova create template so tha=
t
> 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 flo=
w
> > 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=92s config.xml as w=
ell.
> > > >>>>>>>>>>>    -
> > > >>>>>>>>>>>
> > > >>>>>>>>>>>    This results in a freshly built, build-artifact platfo=
rm
> > > >>>>>>>>>> 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=92t 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
> > > >>>>>>>>>>>
> > > >>>>>>>>>>
> > > >>>>>>>>
> > > >>>>>>>>
> > > >>>>>>>
> > > >>>>>>
> > > >>>>>
> > > >>>
> > > >>>
> > > >>
> > >
> > >
> >
>

--089e0111bca4c6469b04e5f3a5b7--