cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From filmaj <...@git.apache.org>
Subject [GitHub] cordova-test-platform pull request #1: Doc requirements for platform api exp...
Date Wed, 26 Jul 2017 19:29:38 GMT
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


Mime
View raw message