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: <20170726192938.E39D2F1755@git1-us-west.apache.org>
Date: Wed, 26 Jul 2017 19:29:38 +0000 (UTC)
archived-at: Wed, 26 Jul 2017 19:29:41 -0000

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

    https://github.com/apache/cordova-test-platform/pull/1#discussion_r129673561
  
    --- Diff: PlatformRequirements.md ---
    @@ -0,0 +1,173 @@
    +<!--
    +# license: Licensed to the Apache Software Foundation (ASF) under one
    +#         or more contributor license agreements.  See the NOTICE file
    +#         distributed with this work for additional information
    +#         regarding copyright ownership.  The ASF licenses this file
    +#         to you under the Apache License, Version 2.0 (the
    +#         "License"); you may not use this file except in compliance
    +#         with the License.  You may obtain a copy of the License at
    +#
    +#           http://www.apache.org/licenses/LICENSE-2.0
    +#
    +#         Unless required by applicable law or agreed to in writing,
    +#         software distributed under the License is distributed on an
    +#         "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    +#         KIND, either express or implied.  See the License for the
    +#         specific language governing permissions and limitations
    +#         under the License.
    +-->
    +
    +# 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
    +- invoking this script would create a platform-specific, cordova-compatible project shell
    + 
    +## Package Expectations
    + 
    +- Platforms must have a package.json in their root.
    +- Package.json must export a 'main'. `"main": "src/cordova/Api.js"`
    +    - A 'main' must exist, and it must be an instance of the `PlatformApi` with methods as you define later.
    +    - 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. It interpolates metadata, such as application name or description from a `Cordova` project's config.xml into the format expected by the platform. See [config.xml documentation](https://cordova.apache.org/docs/en/latest/config_ref/).
    +    - The `PlatformApi` class should be implemented by each platform that wants to use the new API flow.
    +    - Platforms that implement their own `PlatformApi` instance should implement all prototype methods of this class to be fully compatible with `cordova-lib`.
    --- End diff --
    
    This should probably be "must implement all prototype methods", not "should"? Can we be explicit about which of these methods are required? Off the top of my head, a platform _needs_ `create`, `requirements`, `prepare`, `addPlugin` and `removePlugin`... are those the only necessary ones? `build`, `run` and others may not be required. But perhaps it is worth having implementers create, at the minimum, functions that return resolved promises for the method that are considered "no-op" for a platform.


---
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