[
https://issues.apache.org/jira/browse/CB-8900?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14561340#comment-14561340
]
ASF GitHub Bot commented on CB-8900:
------------------------------------
Github user TimBarham commented on a diff in the pull request:
https://github.com/apache/cordova-docs/pull/292#discussion_r31159121
--- Diff: docs/en/edge/platform_plugin_versioning_ref/index.md ---
@@ -0,0 +1,82 @@
+---
+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.
+---
+
+# Platforms and Plugins Version Management
+From version 4.3.0 onwards, Cordova provides the ability to save and
restore platforms and plugins.
+
+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.
+
+The 'save' command stores details about the app's platform and plugin
versions in config.xml.
+The 'restore' step happens automatically when a **'cordova prepare'** is
issued, making use of information previously saved in the config.xml file.
+
+One scenario where save/restore capabilities come in handy is in large
teams that work on an app, with each team member focusing on a platform or
plugin. This feature makes it easier to share the project and reduce the amount
of redundant code that is checked in the repository.
+
+
+## Platform Versioning
+
+### Saving platforms
+To save a platform, you issue the following command :
+
+ $ cordova platform add <platform[@<version>] | directory | git_url>
--save
+
+After running the above command, the resulting config.xml looks like :
+
+ <?xml version='1.0' encoding='utf-8'?>
+ ...
+ <engine name="android" spec="^4.0.0" />
+ ...
+ </ xml>
+
+
+Some examples :
+ * **'cordova platform add android --save'** => retrieves the pinned
version of the android platform, adds it to the project and then updates
config.xml.
+ * **'cordova platform add android@3.7.0 --save'** => retrieves the
android platform, version 3.7.0 from npm, adds it to the project and then
updates config.xml.
+ * **'cordova platform add https://github.com/apache/cordova-android.git​
--save'** => clones the specified cordova-android git repository, adds the
android platform to the project, then updates config.xml and point its version
to the specified git-url.
+ * **'cordova platform add C:/path/to/android/platform --save'** =>
retrieves the android platform from the specified directory, adds it to the
project, then updates config.xml and point to the directory.
+
+### Mass saving platforms on an existing project
+The '--save' flag describe above is only useful when you remember to use
it during the platform addition.
+If you have a pre-existing project and you want to mass-save all existing
platforms in it, you can use :
+
+ $ cordova platform save
+
+
+### Updating / Removing platforms
+It is also possible to update/delete from config.xml during the commands
'cordova platform update' and 'cordova platform remove' :
+
+ $ cordova platform update <platform[@<version>] | directory | git_url>
--save
+ $ cordova platform remove <platform> --save
+Some examples :
+ * **'cordova platform update android --save'** => In addition to
updating the android platform to the pinned version, update config.xml entry
+ * **'cordova platform update android@3.8.0 --save'** => In addition to
updating the android platform to version 3.8.0, update config.xml entry
+ * **'cordova platform update /path/to/android/platform --save'** => In
addition to updating the android platform to version in the folder, update
config.xml entry
+ * **'cordova platform remove android --save'** => Removes the android
platform from the project and deletes its entry from config.xml.
+
+
+### Restoring platforms
+ * Platforms are automatically restored from config.xml when the
**'cordova prepare'** command is run.
+ * If you add a platform without specifying a version/folder/git_url, the
version of the platform that would get added would be one compatible to the one
in config.xml **if found**.
--- End diff --
How about something like:
If you add a platform without specifying a version/folder/git_url, the
version to install is taken from config.xml, if found.
> Document Platform and Plugin Version Management
> -----------------------------------------------
>
> Key: CB-8900
> URL: https://issues.apache.org/jira/browse/CB-8900
> Project: Apache Cordova
> Issue Type: Task
> Components: Docs
> Reporter: Omar Mefire
> Assignee: Omar Mefire
>
> This issue is to track work done on documenting the new feature 'platform and
> plugin version management'.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscr...@cordova.apache.org
For additional commands, e-mail: issues-h...@cordova.apache.org
