cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Brian LeRoux...@brian.io>
Subject Re: New directory structure in cordova-cli's future branch
Date Wed, 22 May 2013 21:35:40 GMT
There are two paths. I argue there is no functional benefit and that
this change is purely aesthetic. Aesthetics are important but I'd
argue folder structure is the last part of the developer aesthetics we
should worry about and especially not beneficial enough to justify a
breaking change.

Today:

./
|- merges/
|- platforms/
|- plugins/
'- www/
    |- index.html
    '- config.xml

Proposed:

./
|- platforms/
|- plugins/
'- app/
    |- merges/
    |- www/
    |       '- index.html
    '- config.xml




On Wed, May 22, 2013 at 1:47 PM, Filip Maj <fil@adobe.com> wrote:
> I'm reviving this discussion re: additional app/ folder in the
> cli-generated project structure.
>
> To recap, there were two main discussions:
>
> A)
> http://apache.markmail.org/thread/syo24cwvhpkxqfdm#query:+page:1+mid:j76xli
> hsfjmvwtoi+state:results
> B) http://www.mail-archive.com/dev@cordova.apache.org/msg05775.html
>
> Arguments for moving to app/:
>
>  - easier to version control relevant / non-build-artifact app bits
>  - aesthetics
>
> Arguments against it:
>
>  - we break shit for users
>  - config.xml location and PhoneGap Build compatibility (but I don't see
> this as a valid argument against. This is an easy problem to solve for us
> Adobe folk and the tooling can handle the trivial steps of going up one
> directory to grab the right file before interfacing with Build)
>
> Also worth noting: people we're not against it for architectural reasons,
> in fact, most people were favorable for the change to app/.
>
> So, with plugman stabilizing and my focus moving to cli work, I feel I
> have a good grasp of both projects and the direction they are going, here
> is my suggestion on how to move forward with this:
>
> 1. cordova-cli's master branch, which will soon merge future work in, will
> revert to the old /www-based structure, then
> 2. In 3.0 we make the change, where landing such a breaking change is
> easier and we'll have a bunch of press/noise about the release out there
> too so communicating this change would be easier.
>
> If there are any other arguments for/against the app/ based structure, now
> is the time to bring it up. We can give this some more time to bake, but
> after 2.8 is released, I'd like to call a vote on whether we should move
> to this structure or not in 3.0.
>
> On 4/16/13 8:31 AM, "Michal Mocny" <mmocny@chromium.org> wrote:
>
>>I should also add.  I appreciate that this is a change, and every change
>>has some learning overhead and we shouldn't stuff everything possible in
>>all the time.
>>
>>However, I think 3.0 and cli are a big change, and we should do the big
>>re-org all at once, so lets decide this now in a way we wont regret.
>>Thats
>>why we are being picky, I guess.  I like knowing that the root of the
>>project has cordova-only artifacts and your app-repo is just a
>>subdirectory
>>somewhere.  Then, the exact location and exact contents are way more
>>flexible.
>>
>>-Michal
>>
>>
>>On Tue, Apr 16, 2013 at 11:18 AM, Michal Mocny <mmocny@chromium.org>
>>wrote:
>>
>>> Okay, we've got options, so lets try to distill the details.
>>>
>>> First, some of the other (perceived) benefits of an app folder are:
>>> * we do a raw cp -r of the www/ folder, and so that should have only
>>> platform agnostic and "necessary" files.
>>> * merges folder was removed from www/ because it did not meet above
>>> criteria, and config.xml is another candidate
>>> * there also potentially exist docs/ (useful for shared apps, like
>>> mobile-spec), platform specific resource files (icons, splash screen),
>>>etc
>>> * a git repository is already basically mirroring the concept of the
>>>"app
>>> folder"
>>>
>>> So, I've come up with the following potential workflows for starting
>>>with
>>> an existing app:
>>>
>>> #1: "your app repo is moved into some subdirectory of a cordova project
>>>--
>>> its exact location is basically a cordova artifact"
>>>   cordova create Foo
>>>   cd Foo
>>>   cordova app add [--link] git-repo/local-repo (nicely akin to plugin
>>>add)
>>>   cordova plugin/platforms add ...
>>>
>>> #2: "your app repo becomes a cordova project in-place"
>>>   git clone FooApp (this repo contains merges/ and www/)
>>>   cordova create FooApp Foo (cli should not clobber existing folders)
>>>   cd FooApp
>>>   set up .gitignore for cordova artifacts (cordova should try not to
>>> introduce new artifacts)
>>>   cordova plugin/platforms add ...
>>>
>>> #3: "what we have now"
>>>   git clone FooApp
>>>   cordova create Foo
>>>   cp -R FooApp/{www,merges,...} Foo  (or ln -s)
>>>   cd Foo
>>>   cordova plugin/platforms add ...
>>>
>>> (Please let me know of more workflows)
>>>
>>> Workflow #1 I think is very clean, and requires an app folder concept
>>>(we
>>> could maybe use a temporary intermediate folder to get around this, but
>>> why).
>>> Workflow #2 essentially your app repo is the app folder concept, but now
>>> the cordova artifacts also go inside it.  Would require minimal changes
>>>to
>>> cordova-cli to not clobber, and requires gitignore.
>>> Workflow #3 is what we have now, which I think is the worst option for
>>>app
>>> management, but can work with or without an app folder.
>>>
>>>
>>> Also, I think it would be great if apps had both plugin and platform
>>> dependancies, such that you could distill workflow #1 down to:
>>>
>>>   cordova create Foo
>>>   cd Foo
>>>   cordova app add git-repo
>>>
>>> .. and it would run the plugin/platform add automatically.  Can even get
>>> that down to a single "cordova create git-repo" line.  That would make
>>> sharing apps, such as mobile-spec-test, really trivial.
>>>
>>> -Michal
>>>
>>>
>>> On Tue, Apr 16, 2013 at 9:19 AM, Andrew Grieve
>>><agrieve@chromium.org>wrote:
>>>
>>>> So, reading through the thread Braden linked to:
>>>> http://www.mail-archive.com/dev@cordova.apache.org/msg05775.html
>>>>
>>>> There are two advantage that were brought up:
>>>> 1. config.xml (configuration) does not live along side of app resources
>>>> 2. It will make it easier to package apps
>>>>   - E.g. zip the app/ directory and install it into the app-harness
>>>> (instead of zipping www + merges). Likewise for phonegap build.
>>>>   - E.g. cordova-mobile-spec would contain the contents of app/. With
>>>>our
>>>> current setup, it would contain www/ merges/, and have the CLI place
>>>>build
>>>> artifacts within the repo's directory instead of as a sibling to it.
>>>>
>>>> I think everyone acknowledged the benefits, but there was still
>>>> not consensus over whether it was "worth it".
>>>>
>>>> I don't really feel strongly about it. Braden says it's easy to change
>>>> code-wise. Does anyone want to go to bat for it?
>>>>
>>>>
>>>>
>>>> On Mon, Apr 15, 2013 at 6:59 PM, Brian LeRoux <b@brian.io> wrote:
>>>>
>>>> > I'd rather we did not go ahead w/ the new directory structure. It
>>>> offers no
>>>> > functional benefit, and comes at an upgrade cost for ppl using the
>>>>CLI
>>>> > tools today.
>>>> >
>>>> >
>>>> > On Mon, Apr 15, 2013 at 12:46 PM, Andrew Grieve <agrieve@chromium.org
>>>> > >wrote:
>>>> >
>>>> > > Just catching up on the past week of emails and it's not clear
that
>>>> there
>>>> > > was a consensus here. By the sounds of it though:
>>>> > >
>>>> > > 1. Lots of users are using Cordova-CLI (master branch)
>>>> > > 2. Cordova-CLI's "future" branch has non-backwards-compatible
>>>>changes.
>>>> > > 3. One of these changes is the directory structure.
>>>> > >
>>>> > > The main debate is on how to message these changes to users. What
>>>>we
>>>> > should
>>>> > > do is:
>>>> > >
>>>> > > 1. Have an upgrade guide. (e.g. paths are now relative to
>>>>plugin.xml)
>>>> > > 2. Ensure that our error handling shows useful messages when they
>>>> result
>>>> > > from an old-way-of-doing-things (e.g. your app's structure doesn't
>>>> > match.)
>>>> > >
>>>> > > Rather than printing out the commands to run to convert their
>>>>project,
>>>> > > maybe we could have them in the upgrade guide and have the error
>>>> messages
>>>> > > point to the guide?
>>>> > >
>>>> > >
>>>> > >
>>>> > >
>>>> > > On Wed, Apr 10, 2013 at 5:47 PM, Tim Kim <timkim85@gmail.com>
>>>>wrote:
>>>> > >
>>>> > > > Braden I have merged master and the future branch:
>>>> > > > https://github.com/timkim/plugman/tree/future_master_merge
>>>> > > >
>>>> > > > I think it's about ready to merge back in to future. I've
gotten
>>>>the
>>>> > > > android-one-install and the ios-config-xml-install (minus
one
>>>>weird
>>>> > test
>>>> > > I
>>>> > > > don't understand) working.
>>>> > > >
>>>> > > >
>>>> > > > On 10 April 2013 14:42, Anis KADRI <anis.kadri@gmail.com>
wrote:
>>>> > > >
>>>> > > > > As far as I am concerned I don't really have a strong
opinion
>>>>on
>>>> this
>>>> > > > > topic. As I said in the previous thread, I do like this
new
>>>> directory
>>>> > > > > structure and if you have it there and tested then fine.
We
>>>>break
>>>> > shit
>>>> > > > all
>>>> > > > > the time it's not like this change is one too many. What
>>>>matters
>>>> is
>>>> > to
>>>> > > > > communicate it to our users and give them an upgrade
path to
>>>>this
>>>> new
>>>> > > app
>>>> > > > > structure (the Cordova docs are a good place for that).
>>>> > > > >
>>>> > > > > However, I agree with Brian that there are more important
>>>>things
>>>> to
>>>> > > > tackle
>>>> > > > > right now. Now sure what you had on your list but since
js only
>>>> > modules
>>>> > > > are
>>>> > > > > in Plugman right now (untested) The next big thing that
is
>>>>going
>>>> to
>>>> > be
>>>> > > > > non-trivial is: plugin dependencies (which will in some
ways
>>>> involve
>>>> > > > > discovery I think). We should have a discussion about
that
>>>> (hangout,
>>>> > > IRC,
>>>> > > > > connect...whatever). I have a couple of ideas about that.
>>>> > > > >
>>>> > > > > Tim is working on fixing/adding/updating plugman tests
and it
>>>> looks
>>>> > > like
>>>> > > > > he's making good progress on it.
>>>> > > > >
>>>> > > > > -a
>>>> > > > >
>>>> > > > >
>>>> > > > > On Wed, Apr 10, 2013 at 11:53 AM, Michael Wolf <
>>>> > > Michael.Wolf@cynergy.com
>>>> > > > > >wrote:
>>>> > > > >
>>>> > > > > > +1
>>>> > > > > >
>>>> > > > > > I get the intention, however anything we can do
to reduce
>>>>this
>>>> type
>>>> > > of
>>>> > > > > > breaking change should be done.   These type of
changes
>>>>should
>>>> be
>>>> > > > > > considered for major releases only so users can
plan for
>>>>them.
>>>> > > > > >
>>>> > > > > > mw
>>>> > > > > >
>>>> > > > > > On 4/9/13 5:05 PM, "Jesse" <purplecabbage@gmail.com>
wrote:
>>>> > > > > >
>>>> > > > > > >+1 to the sanity plea of devgeek Tommy
>>>> > > > > > >
>>>> > > > > > >Also, if it didn't happen on this list, ....
>>>> > > > > > >'Consensus' should always be tracked back to
a thread here,
>>>> > > regardless
>>>> > > > > of
>>>> > > > > > >meetings, hangouts, irc, bbs, ...
>>>> > > > > > >
>>>> > > > > > >
>>>> > > > > > >
>>>> > > > > > >
>>>> > > > > > >@purplecabbage
>>>> > > > > > >risingj.com
>>>> > > > > > >
>>>> > > > > > >
>>>> > > > > > >On Tue, Apr 9, 2013 at 1:48 PM, tommy-carlos
Williams
>>>> > > > > > ><tommy@devgeeks.org>wrote:
>>>> > > > > > >
>>>> > > > > > >> Sorry, but as someone that helps users
everyday, the
>>>>almost
>>>> > "it's
>>>> > > > > alpha,
>>>> > > > > > >> they shoulda seen it coming" tone of this
is a bit
>>>>upsetting.
>>>> > > > > > >>
>>>> > > > > > >> It reminds me of before the deprecation
policy, etc when
>>>> > PhoneGap
>>>> > > > > would
>>>> > > > > > >> completely break everything whenever a
new version came
>>>>out.
>>>> > > > > > >>
>>>> > > > > > >> I feel like we have come a long way since
then (with a
>>>>ways
>>>> > still
>>>> > > to
>>>> > > > > go,
>>>> > > > > > >> no question about it).  I would hate to
be the one in IRC
>>>> and on
>>>> > > the
>>>> > > > > > >>Google
>>>> > > > > > >> Group list having to explain this to everyone
using the
>>>>cli.
>>>> > > > > > >>
>>>> > > > > > >> I was under the impression that the cli
was "shipping"
>>>>now,
>>>> not
>>>> > > > just a
>>>> > > > > > >> little side thing. I know that quite a
few people are
>>>>using
>>>> it
>>>> > for
>>>> > > > > real
>>>> > > > > > >> apps (myself included). If that is true,
then we have a
>>>>duty
>>>> to
>>>> > at
>>>> > > > > least
>>>> > > > > > >> think very carefully before breaking something
and come up
>>>> with
>>>> > a
>>>> > > > good
>>>> > > > > > >>plan
>>>> > > > > > >> for easing that transition.
>>>> > > > > > >>
>>>> > > > > > >> - tommy
>>>> > > > > > >>
>>>> > > > > > >> On 10/04/2013, at 1:40, Braden Shepherdson
<
>>>> braden@chromium.org
>>>> > >
>>>> > > > > wrote:
>>>> > > > > > >>
>>>> > > > > > >> > This mailing list post is, or will
shortly be, indexed
>>>>by
>>>> > Google
>>>> > > > and
>>>> > > > > > >> > others. Any newcomers will see the
new docs and create
>>>>new
>>>> > > > projects.
>>>> > > > > > >> >
>>>> > > > > > >> > As I mentioned on IRC, existing users
are either
>>>>accepting
>>>> or
>>>> > > > > ignoring
>>>> > > > > > >> the
>>>> > > > > > >> > "alpha" warnings that this software
is new and under
>>>>heavy
>>>> > > > > > >>development,
>>>> > > > > > >> and
>>>> > > > > > >> > if they want to jump on it early they're
going to have
>>>>to
>>>> > expect
>>>> > > > > some
>>>> > > > > > >> pain.
>>>> > > > > > >> >
>>>> > > > > > >> > That said, I don't really know of
any better way to
>>>> socialize
>>>> > > it.
>>>> > > > Is
>>>> > > > > > >> there
>>>> > > > > > >> > anywhere where a brief blog post on
this would make
>>>>sense?
>>>> > > > > > >> >
>>>> > > > > > >> > I don't know how many people are using
these tools and
>>>>not
>>>> on
>>>> > > the
>>>> > > > > > >>mailing
>>>> > > > > > >> > list, though certainly some turn up
on IRC occasionally.
>>>> > > > > > >> >
>>>> > > > > > >> > Braden
>>>> > > > > > >> >
>>>> > > > > > >> >
>>>> > > > > > >> > On Tue, Apr 9, 2013 at 11:24 AM, Filip
Maj
>>>><fil@adobe.com>
>>>> > > wrote:
>>>> > > > > > >> >
>>>> > > > > > >> >> How will we communicate this change
to our existing
>>>>users?
>>>> > > > > > >> >>
>>>> > > > > > >> >> On 4/9/13 5:22 PM, "Braden Shepherdson"
<
>>>> braden@chromium.org
>>>> > >
>>>> > > > > wrote:
>>>> > > > > > >> >>
>>>> > > > > > >> >>> I've just pushed a change
to the future branch that
>>>> changes
>>>> > > the
>>>> > > > > > >> directory
>>>> > > > > > >> >>> structure to:
>>>> > > > > > >> >>>
>>>> > > > > > >> >>> app/
>>>> > > > > > >> >>>   merges/
>>>> > > > > > >> >>>       android/
>>>> > > > > > >> >>>       ios/
>>>> > > > > > >> >>>   www/
>>>> > > > > > >> >>>   config.xml
>>>> > > > > > >> >>>
>>>> > > > > > >> >>> As was discussed at our video
conference meeting a
>>>> couple of
>>>> > > > weeks
>>>> > > > > > >>ago,
>>>> > > > > > >> >>> this has a number of advantages:
>>>> > > > > > >> >>> - config.xml is no longer
in the www/ directory
>>>> > > > > > >> >>> - One can easily version control
the whole app/
>>>> directory,
>>>> > and
>>>> > > > get
>>>> > > > > > >> their
>>>> > > > > > >> >>> web assets, merges and so
on into the repo.
>>>> > > > > > >> >>> - That repo can contain additional
information: a
>>>> README.md,
>>>> > > > > > >> supplementary
>>>> > > > > > >> >>> documentation, tests, whatever.
The CLI will ignore
>>>> anything
>>>> > > > > > >>outside of
>>>> > > > > > >> >>> the
>>>> > > > > > >> >>> merges and www directories.
>>>> > > > > > >> >>>
>>>> > > > > > >> >>>
>>>> > > > > > >> >>> The downside is that this
is a breaking change:
>>>>running
>>>> the
>>>> > > new
>>>> > > > > > >> version of
>>>> > > > > > >> >>> the tools on an old project
will fail (but I think in
>>>>a
>>>> > > harmless
>>>> > > > > > >>way)
>>>> > > > > > >> >>> until
>>>> > > > > > >> >>> you rearrange the directories.
You can do that with
>>>>the
>>>> > > > following
>>>> > > > > > >> >>> commands:
>>>> > > > > > >> >>>
>>>> > > > > > >> >>> $ mkdir app
>>>> > > > > > >> >>> $ mv www/config.xml app
>>>> > > > > > >> >>> $ mv www app
>>>> > > > > > >> >>> $ mv merges app
>>>> > > > > > >> >>>
>>>> > > > > > >> >>> All docs and tests are updated
as well. Any problems
>>>> should
>>>> > be
>>>> > > > > > >> reported on
>>>> > > > > > >> >>> JIRA and assigned to me.
>>>> > > > > > >> >>>
>>>> > > > > > >> >>> Braden
>>>> > > > > > >> >>
>>>> > > > > > >> >>
>>>> > > > > > >>
>>>> > > > > >
>>>> > > > > >
>>>> > > > >
>>>> > > >
>>>> > > >
>>>> > > >
>>>> > > > --
>>>> > > > Timothy Kim
>>>> > > >
>>>> > >
>>>> >
>>>>
>>>
>>>
>

Mime
View raw message