cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Braden Shepherdson <bra...@chromium.org>
Subject Re: New directory structure in cordova-cli's future branch
Date Wed, 10 Apr 2013 15:36:39 GMT
First, note that this change is in the future branch. The future branch has
several other breaking changes aside from this one:
- It changes the plugin spec significantly (adding <js-module>, changing
paths in <source-file> etc. from magic to relative-to-plugin.xml) which
will require updates of any existing plugins.
- It also changes the workflow for plugman significantly (--fetch, install,
--uninstall, --remove) in a way that will break existing scripts, including
Phonegap Build.

We're going to need a way to communicate all of these changes to our plugin
developers and app developers, which I had thought would be part of the 3.0
release when we properly launch these tools.

I was under the impression that these scripts were "release early, release
often"ed, but not really officially supported until Cordova 3.0. They are
under heavy development by myself and others right now, and have not
stabilized in their implementation or interface.

On this change specifically, we did talk about it on the list, and not just
in the meeting, see [1]. That thread didn't have landslide consensus, but
it did seem to support this change, as had the discussion in the meeting.

If we are really concerned about this change breaking things, it would be
easy to add a migration path to the CLI for a few versions. We have three
options:
- Warn the users and explain the change they need to make (Unix shell
commands included?) and let them do it manually.
- Warn the users, explain, and ask if they want us to do it automatically
or would rather do it themselves (eg. if they want to git mv instead of
just mv).
- Support both directory structures for a while (until 3.0?) but trigger a
warning if they're using the old style.

The third is the most difficult, but isn't too bad, since I pulled the
locations of www and config.xml into functions that could be made flexible.
I think it's overkill, though, and that the best approach is a warning with
a script to perform the change if the user wishes.



tl;dr:
- Lots of breaking changes are coming to these tools, no way we can support
old+new for all of them. How are we going to communicate them?
- Are CLI and Plugman alpha, beta, or launched-with-deprecation-policies? I
thought usable alpha, since they are under heavy development and are not
stable.
- How to handle this particular change: warn, warn+script to fix,
warn+handle both ways?


Braden

[1] http://www.mail-archive.com/dev@cordova.apache.org/msg05775.html


On Tue, Apr 9, 2013 at 5:12 PM, Kerri Shotts <kerrishotts@gmail.com> wrote:

> I can't say I have strong feelings one way or the other.
>
> I will say that having config.xml inside www *does* feel odd. So I'd be
> all for moving it to the project's root directory (but that breaks spec. Is
> that good? Bad?). Which is a breaking change, and so we'd still have to
> deal with older projects. But there are times that's going to happen anyway
> (though I think the tone "it's alpha, expect it" is a little odd, since it
> comes off as a shipping product; so I would echo a lot that Tommy wrote. If
> we're going to do that, cordova-cli should have a v0.# instead of v2.6.0 or
> the like.)
>
> Ultimately, I think if the change is breaking, the bare minimum must be a
> well-defined failure *up-front* that indicates to the user that they need
> to do something with their directory structure (the gravy would be letting
> the user say to the script, "yes, I want you to do this for me"). We should
> never rely on a "we hope it fails", because there will be a case where it
> won't, and will seriously screw something up. That will equal several
> unhappy users.
>
> <semi-rant>I know, that if we use this directory structure, that the way
> to get your project up-to-date isn't hard. But there are plenty of users
> who already have an aversion to the command line, and this is going to be
> too much. It's hard enough to convince them to use cordova-cli in the first
> place, the main idea being "it'll be easier to manage your cross-platform
> projects". But there are plenty of users who are still upset that there's
> no GUI way to do this (nor a GUI way to create a single-platform project),
> and so we do risk having too much of a starting obstacle when it comes to
> getting started with Phonegap. Clearly there are loads of users in the
> forum who are not experts when it comes to understanding the command line,
> and I do think that at some point, we need to be sensitive to those needs.
>  </semi-rant>
>
> Finally, let me just say this: I wouldn't use versioning as an argument. I
> can easily tell Git what to ignore, and it does so happily. So to me that's
> a non-starter.
> ___________________________________
> Kerri Shotts
> photoKandy Studios, LLC
>
> On the Web: http://www.photokandy.com/
>
> Social Media:
>           Twitter: @photokandy, http://twitter.com/photokandy
>           Tumblr: http://photokandy.tumblr.com/
>           Github: https://github.com/kerrishotts
>                         https://github.com/organizations/photokandyStudios
>           CoderWall: https://coderwall.com/kerrishotts
>
> Apps on the Apple Store:
>
> https://itunes.apple.com/us/artist/photokandy-studios-llc/id498577828
>
> Books:
>
> http://www.packtpub.com/phonegap-2-mobile-application-hotshot/book
>           http://www.packtpub.com/phonegap-social-app-development/book
>
>
> On Tuesday, April 9, 2013 at 1:51 PM, Braden Shepherdson wrote:
>
> > That's now how I recalled the discussion. It certainly wasn't clear-cut,
> > but I thought the conclusion was that this was fine.
> >
> > Well, then this is now a discussion thread. What are the
> counterarguments?
> >
> > Braden
> >
> >
> > On Tue, Apr 9, 2013 at 2:49 PM, Brian LeRoux <b@brian.io (mailto:
> b@brian.io)> wrote:
> >
> > > :(
> > >
> > > We never had full consensus to do this Braden.
> > >
> > > On Tuesday, April 9, 2013, Filip Maj wrote:
> > >
> > > > For a couple months now the npm package has had about 1000 downloads
> per
> > > > month [1].
> > > >
> > > > We do have upgrade guides in our docs for each version for each
> platform.
> > > > Maybe we could add a CLI section? Then we can reference those guides
> in
> > > > the CLI's readme? Just thinking out loud.
> > > >
> > > > [1] http://npmjs.org/package/cordova
> > > >
> > > > On 4/9/13 5:40 PM, "Braden Shepherdson" <braden@chromium.org(mailto:
> braden@chromium.org)
> > > <javascript:;>>
> > > > 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 (mailto:
> fil@adobe.com)<javascript:;>>
> > > > wrote:
> > > > >
> > > > > > How will we communicate this change to our existing users?
> > > > > >
> > > > > > On 4/9/13 5:22 PM, "Braden Shepherdson" <braden@chromium.org(mailto:
> braden@chromium.org)
> > > <javascript:;>>
> > > > 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
(
> http://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
>
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message