The change is not purely aesthetic; it means that the "my app" portions of the structure are now contained in a single directory, and easier to version control.
This change gets more expensive every day. If we're ever going to do it, it should be done now, I believe. It seems like the (not universally supported) consensus from the first pass at this thread was to keep the app/ dir but have automatic detection and ask-then-automatic conversion. If that approach is still acceptable, I will implement that support today before we tag CLI for 2.8. Braden On Thu, May 23, 2013 at 12:30 AM, Michal Mocny <mmo...@chromium.org> wrote: > Fil, good summary, thanks for that. I also agree with your proposal. > Would it be possible to just support both options starting now, and > "deprecate" www/ at the top level in 3.0? > > Brian, this isn't just aesthetics, but its true that either option can, > with varying difficulty, be made to work for all use cases. > > Migration path is trivial but will be paid by all users, still, workflows > will change completely with 3.0 anyway, this being the least of the > changes. Which decision is more likely to be regretted a year from now? > > -Michal > > > On Wed, May 22, 2013 at 10:11 PM, Andrew Grieve <agri...@chromium.org > >wrote: > > > I don't really think this directory change is a big deal. We break things > > in almost every release (e.g. loading pages of http), yet we're having so > > much debate over alpha tool. > > > > The migration path is: mkdir app && git mv www merges app && git mv > > app/www/config.xml app > > > > I think the least amount of work here is to just console.log an error > > message with this command if the app/ directory is not found. > > > > > > On Wed, May 22, 2013 at 9:28 PM, Tommy-Carlos Williams > > <to...@devgeeks.org>wrote: > > > > > Is it bad that I both agree vehemently with Brian's calling it not > > > beneficial enough to justify, but also really really like the proposed > > > structure better that the current one? hehe. > > > > > > *so… conflicted...* > > > > > > - tommy > > > > > > On 23/05/2013, at 7:35 AM, Brian LeRoux <b...@brian.io> wrote: > > > > > > > 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 <f...@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" <mmo...@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 < > mmo...@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 > > > >>>> <agri...@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 < > > > agri...@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 <timki...@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.ka...@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.w...@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" <purplecabb...@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 > > > >>>>>>>>>>> <to...@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 < > > > >>>>> bra...@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 > > > >>>>> <f...@adobe.com> > > > >>>>>>> wrote: > > > >>>>>>>>>>>>> > > > >>>>>>>>>>>>>> How will we communicate this change to our existing > > > >>>>> users? > > > >>>>>>>>>>>>>> > > > >>>>>>>>>>>>>> On 4/9/13 5:22 PM, "Braden Shepherdson" < > > > >>>>> bra...@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 > > > >>>>>>>> > > > >>>>>>> > > > >>>>>> > > > >>>>> > > > >>>> > > > >>>> > > > >> > > > > > > > > >
