Mailing-List: contact dev-help@cordova.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cordova.apache.org
From: filmaj <git@git.apache.org>
To: dev@cordova.apache.org
Reply-To: dev@cordova.apache.org
References: <git-pr-1-cordova-test-platform@git.apache.org>
In-Reply-To: <git-pr-1-cordova-test-platform@git.apache.org>
Subject: [GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Content-Type: text/plain
Message-Id: <20170721191131.86D14DFCC1@git1-us-west.apache.org>
Date: Fri, 21 Jul 2017 19:11:31 +0000 (UTC)
archived-at: Fri, 21 Jul 2017 19:11:38 -0000

Github user filmaj commented on a diff in the pull request:

    https://github.com/apache/cordova-test-platform/pull/1#discussion_r128837232
  
    --- Diff: PlatformRequirements.md ---
    @@ -0,0 +1,144 @@
    +
    +# New Platform Checklist
    + 
    +## Stand-alone scripts
    + 
    +bin/create scripts
    +- bin/create _(typically a node script)_
    +- bin/create.bat for windows
    +    - windows .bat file typically just calls bin/create with node
    + 
    +bin/update
    +- not entirely sure this code is run, or needs to exist with newish non-destructive platform updates
    + 
    +## Package Expectations
    + 
    +- Platforms must have a package.json in their root.
    +- Package.json exports a 'main', usually `"main": "src/cordova/Api.js"`
    +    - This allows other modules to simply require() the path to this platform and get access to the Api.
    + 
    +## Api (Platform) Expectations
    +- The PlatformApi class
    +    - The PlatformApi class is an abstraction around a particular platform that exposes all the actions, properties, and methods for this platform so they are accessible programmatically.
    +    - It can install & uninstall plugins with all source files, web assets and js files.
    +    - It exposes a single 'prepare' method to provide a way for cordova-lib to apply a project's setting/www content to the platform.
    +    - The PlatformApi class should be implemented by each platform that wants to use the new API flow. For those platforms, which don't provide their own PlatformApi, there will be a polyfill in cordova-lib.
    +    - Platforms that implement their own PlatformApi instance should implement all prototype methods of this class to be fully compatible with cordova-lib.
    +    - The PlatformApi instance should define the following field:
    +        - platform : This is a String that defines a platform name.
    + 
    +- Api.js exports static functions
    +    - there is currently a requirement that the file be called Api.js (todo:change that)
    + 
    + 
    +- Api.js exports static function `updatePlatform(destination, options, events);`
    +    - PlatformApi.updatePlatform = function (cordovaProject, options) {};
    +    - The `updatePlatform` method is equal to the bin/update script. It should update an already installed platform. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
    +    - cordovaProject: This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
    +    - options : This is an options object. The most common options are :
    +        - options.customTemplate : This is a path to custom template, that should override the default one from platform.
    +        - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
    +     - The `updatePlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
    + 
    +- Api.js exports static function `createPlatform(destination, cfg, options, events);`
    +    - PlatformApi.createPlatform = function(cordovaProject, options) {};
    +    - The `createPlatform method` is equal to the bin/create script. It should install the platform to a specified directory and create a platform project. It should accept a CordovaProject instance, that defines a project structure and configuration, that should be applied to the new platform, and an options object.
    +    - cordovaProject : This is a CordovaProject instance that defines a project structure and configuration, that should be applied to the new platform. This argument is optional and if not defined, that platform is used as a standalone project and not as part of a Cordova project.
    +    - options : This is an options object. The most common options are :
    +        - options.customTemplate : This is a path to custom template, that should override the default one from the platform.
    +        - options.link : This is a flag that should indicate that the platform's sources will be linked to the installed platform instead of copying.
    +    - The `createPlatform` method must return a promise, which is either fulfilled with a PlatformApi instance or rejected with a CordovaError.
    + 
    +The way most platforms work is somewhat tricky.  The Api.js could be anywhere in the platform repo, ex. /templates/cordova/Api.js .  When a new project is created for the platform, the platform copies this file (and supporting files ) to destination/cordova/Api.js.  The project expectations demand that the Api.js file be available at /projectRoot/platforms/platform-name/cordova/Api.js.
    + 
    +A call to the platforms static Api.createPlatform will
    +1. Copy template files to destination (according to cfg, options).
    +1. Copy the file Api.js (and supporting modules) to destination/cordova/Api.js.
    +1. Return a promise that will eventually resolve with an instance of the newly copied Api.js.
    +    - This step is a bit confusing because at this point in time we have 2 Api.js in memory, one from the platform folder which has static methods, and one from the new project folder which has instance methods.
    --- End diff --
    
    Sounds like we have more work here in terms of wording and understanding the API... I think we should consolidate on terminology around how to differentiate between Platform and Project-specific API - that would help handle any potential confusion.


---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@cordova.apache.org
For additional commands, e-mail: dev-help@cordova.apache.org