cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ste...@apache.org
Subject [3/3] docs commit: CB-12591 : added examples and revised basck on feedback
Date Mon, 01 May 2017 21:45:22 GMT
CB-12591 : added examples and revised basck on feedback

 This closes #689


Project: http://git-wip-us.apache.org/repos/asf/cordova-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-docs/commit/f523ccbb
Tree: http://git-wip-us.apache.org/repos/asf/cordova-docs/tree/f523ccbb
Diff: http://git-wip-us.apache.org/repos/asf/cordova-docs/diff/f523ccbb

Branch: refs/heads/master
Commit: f523ccbb2e66f068047703178de287bf6f707ccf
Parents: 336883a
Author: Audrey So <audreyso@apache.org>
Authored: Wed Mar 29 16:06:23 2017 -0700
Committer: Steve Gill <stevengill97@gmail.com>
Committed: Mon May 1 23:45:12 2017 +0200

----------------------------------------------------------------------
 .../dev/platform_plugin_versioning_ref/index.md | 59 +++++++++++++++++---
 1 file changed, 52 insertions(+), 7 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-docs/blob/f523ccbb/www/docs/en/dev/platform_plugin_versioning_ref/index.md
----------------------------------------------------------------------
diff --git a/www/docs/en/dev/platform_plugin_versioning_ref/index.md b/www/docs/en/dev/platform_plugin_versioning_ref/index.md
index 5a3bb09..653933a 100644
--- a/www/docs/en/dev/platform_plugin_versioning_ref/index.md
+++ b/www/docs/en/dev/platform_plugin_versioning_ref/index.md
@@ -27,7 +27,7 @@ From version 4.3.0 onwards, Cordova provides the ability to save and restore
pla
 
 This feature allows developers to save and restore their app to a known state without having
to check in all of the platform and plugin source code.
 
-When adding a platform or plugin, details about the app's platform and plugin versions are
automatically saved in config.xml and package.json.
+When adding a platform or plugin, details about the app's platform and plugin versions are
automatically saved in config.xml and package.json. It is possible to add a platform or plugin
by editing package.json or config.xml directly, assuming you know the right tags + syntax.
It is not possible to remove plugins or platforms in this manner. The recommended method of
adding and removing plugins and platforms is with the command line cordova commands `cordova
plugin add|remove ...` and `cordova platform add|remove ...` to avoid any out of sync issues.
 
 The 'restore' step happens automatically when a **'cordova prepare'** is issued, making use
of information previously saved in the config.xml and package.json files.
 
@@ -55,7 +55,7 @@ After running the above command, the resulting config.xml looks like :
 After running the above command, the resulting package.json looks like :
 
 ```bash
-"cordova": {"platforms": ["android",]},"dependencies": {"cordova-android": "~4.0.0",}
+"cordova": {"platforms": ["android"]},"dependencies": {"cordova-android": "^4.0.0"}
 ```
 The '--nosave' flag prevents adding and deleting specified platforms from config.xml and
package.json. To prevent saving a platform, you issue the following command :
 
@@ -67,13 +67,12 @@ Some examples :
 
   * **'cordova platform add android'** => retrieves the pinned version of the android
platform, adds it to the project and then updates config.xml and package.json.
   * **'cordova platform add android@3.7.0'** => retrieves the android platform, version
3.7.0 from npm, adds it to the project and then updates config.xml and package.json.
-  * **'cordova platform add android@https://github.com/apache/cordova-android.git​'** =>
clones the specified cordova-android git repository, adds the android platform to the project,
then updates config.xml and package.json and points its version to the specified git-url.
+  * **'cordova platform add https://github.com/apache/cordova-android.git'** => npm installs
the specified cordova-android from the git repository, adds the android platform to the project,
then updates config.xml and package.json and points its version to the specified git-url.
   * **'cordova platform add C:/path/to/android/platform'** => retrieves the android platform
from the specified directory, adds it to the project, then updates config.xml and package.json
and points to the directory.
   * **'cordova platform add android --nosave'** => retrieves the pinned version of the
android platform, adds it to the project, but does not add it to config.xml or package.json.
   * **'cordova platform remove android --nosave'** =>  removes the android platform from
the project, but does not remove it from config.xml or package.json.  
 
 ### Mass saving platforms on an existing project
-
 If you have a pre-existing project and you want to save all the currently added platforms
in your project, you can use :
 
 ```bash
@@ -116,8 +115,30 @@ Suppose your config.xml file contains the following entry:
 
 If you run the command **'cordova platform add android'** (no version/folder/git_url specified),
the platform 'android@3.7.0' (as retrieved from config.xml) will be installed.
 
+**Example for order of precedence for restoring platforms:**
+
+Suppose your config.xml has this platform and version:
+```bash
+<engine name="android" spec=“1.0.0” />
+```
+
+Suppose your package.json has this platform and version:
+
+```bash
+"cordova": {"platforms": ["android"]},"dependencies": {"cordova-android": "4.0.0"}
+```
+
+When prepare is run, package.json’s contents are giving precedence and both config.xml
and package.json are updated so that they have identical platforms and variables. Notice how
package.json's version (4.0.0) has **replaced** config.xml's version (1.0.0).
 
+After running **'cordova prepare'** , the resulting config.xml looks like :
+```bash
+<engine name="android" spec=“4.0.0” />
+```
 
+After running **'cordova prepare'** , the resulting package.json looks like :
+```bash
+"cordova": {"platforms": ["android",]},"dependencies": {"cordova-android": "4.0.0"}
+```
 ---
 
 ## Plugin Versioning
@@ -143,7 +164,7 @@ After running the above command, the resulting config.xml looks like :
 After running the above command, the resulting package.json looks like :
 
 ```bash
-"cordova": {"plugins": ["cordova-plugin-console",]},"dependencies": {"cordova-plugin-console":
"~1.0.0",}
+"cordova": {"plugins": ["cordova-plugin-console"]},"dependencies": {"cordova-plugin-console":
"^1.0.0"}
 ```
 
 The '--nosave' flag prevents adding and deleting specified plugins from config.xml and package.json.
To prevent saving a plugin, you issue the following command :
@@ -156,11 +177,10 @@ Some examples :
 
   * **'cordova plugin add cordova-plugin-console'** => retrieves the pinned version of
the console plugin, adds it to the project and then updates config.xml and package.json.
   * **'cordova plugin add cordova-plugin-console@0.2.13'** => retrieves the android plugin,
version 0.2.13 from npm, adds it to the project and then updates config.xml and package.json.
-  * **'cordova plugin add https://github.com/apache/cordova-plugin-console.git'** => clones
the specified console plugin git repository, adds the console plugin to the project, then
updates config.xml and and package.json and points its version to the specified git-url.
+  * **'cordova plugin add https://github.com/apache/cordova-plugin-console.git'** => npm
installs specified console plugin from the git repository, adds the console plugin to the
project, then updates config.xml and and package.json and points its version to the specified
git-url.
   * **'cordova plugin add C:/path/to/console/plugin'** => retrieves the console plugin
from the specified directory, adds it to the project, then updates config.xml and package.json
and points to the directory.
 
 ### Mass saving plugins on an existing project
-
 If you have a pre-existing project and you want to save all currently added plugins in the
project, you can use :
 
 ```bash
@@ -199,3 +219,28 @@ Suppose your config.xml file contains the following entry:
 
 If you run the command **'cordova plugin add cordova-plugin-console'** (no version/folder/git_url
specified), the plugin 'cordova-plugin-console@0.2.11' (as retrieved from config.xml) will
be installed.
 
+**Example for order of precedence for restoring plugins:**
+
+Supposed your config.xml has this plugin and version:
+
+```bash
+<plugin name="cordova-plugin-splashscreen"/>
+```
+Suppose your package.json has this plugin and version:
+
+```bash
+"cordova": {"plugins": {"cordova-plugin-splashscreen" : {} } },"dependencies": {"cordova-plugin-splashscreen":
"1.0.0"}
+```
+When prepare is run, package.json’s contents are giving precedence and both config.xml
and package.json are updated so that they have identical plugins and variables. Notice how
package.json's version (1.0.0) is now in config.xml.
+
+After running **'cordova prepare'** , the resulting config.xml looks like :
+
+```bash
+<plugin name="cordova-plugin-splashscreen" spec="1.0.0"/>
+```
+
+After running **'cordova prepare'** , the resulting package.json looks like :
+
+```bash
+"cordova": {"plugins": {"cordova-plugin-splashscreen" : {} } },"dependencies": {"cordova-plugin-splashscreen":
"1.0.0"}
+```
\ No newline at end of file


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


Mime
View raw message