[Cordova Wiki] Update of "UniversalProjectProposal" by brianleroux

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Cordova Wiki" for change notification.

The "UniversalProjectProposal" page has been changed by brianleroux:
http://wiki.apache.org/cordova/UniversalProjectProposal

New page:
= Universal Project Proposal

This document sets forth a proposal for an officially supported structure for Apache Cordova projects. Cordova client projects support the native development for the platform being targeted. For example, an Cordova/iOS project is only supported by Xcode and by extension OS X. Likewise, a Cordova/Android project will only work in an environment configured with the Android SDK. This isn't a problem, in fact this a key strength of Cordova, however sharing {{{www}}} code between projects has given cause for three patterns which have different complexity tradeoffs.

  1. symlink www 
  2. git submodule (or perhaps svn external) www
  3. brute force copy and paste automated build step

Symlinks are supported on all platforms, however to be success a formal project structure needs to be enforced. Currently this is the implementing developers concern and thus leaves the [burden of platform tooling|http://www.tricedesigns.com/2012/02/16/linked-source-files-across-phonegap-projects-on-osx/] to them. We can do better! 

Using submodules or externals can prove to be complex and problematic. It also enforces a tooling choice which could prove exclusive. We can do better.

The brute force copy and paste into target directory environments seems blunt, however this is the most easily supported and least surprising of all the options. It is the simplest possible solution to the problem. It shares the same problems with symlinks, in burdening developers to cut their framework tools, and it is the most common technique employed by developers for sharing code between platform projects. 

== Proposed Structure


    /AppName ......... Project name; not programmatically meaningful.
    |-cordova-1.5/ ... Cordova dist.
    |-test/ .......... Place for developer app tests.
    |-src/ ........... Native app src.
    `-www/ ........... Typical Cordova project files.
      |-config.xml
      `-index.html
  

== How do we get there?

The simplest thing to get us started, we need a tool for:

  * project generation
  * updating between versions of cordova
  * updating generated native src
  * command line brute force copy/paste

== New Directions

Once we have basic project structure that enables sharing of code between projects and a consistent directory structure to work against we can begin to automate common development workflow tasks such as: compiling, debugging, testing, releasing and other things in between. As an added benefit projects generated with Cordova create a consistent, predictable, easy to understand and therefor extend software project. A number of conventions are introduced removing the need for mobile developers to relearn their tools or, worse, rebuild them for every project.

== Prior Art

[https://github.com/brianleroux/cordova|Brian LeRoux created a prototype, not coincidentally called Cordova.]