You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cordova.apache.org by omefire <gi...@git.apache.org> on 2015/05/22 21:00:21 UTC

[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

GitHub user omefire opened a pull request:

    https://github.com/apache/cordova-docs/pull/292

    CB-8900: Documentation for the platform save / restore feature

    This PR's goal is to document the platform save / restore feature.
    I'll soon send another one for the plugin side of things.

You can merge this pull request into a Git repository by running:

    $ git pull https://github.com/omefire/cordova-docs CB-8900

Alternatively you can review and apply these changes as the patch at:

    https://github.com/apache/cordova-docs/pull/292.patch

To close this pull request, make a commit to your master/trunk branch
with (at least) the following in the commit message:

    This closes #292
    
----
commit 6aa8e8ffba648be2a895ac10eda8e7c908fce806
Author: Omar Mefire <om...@microsoft.com>
Date:   2015-05-18T18:04:05Z

    CB-8900: Documentation for the platform save / restore feature

----


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by omefire <gi...@git.apache.org>.
Github user omefire commented on the pull request:

    https://github.com/apache/cordova-docs/pull/292#issuecomment-106483923
  
    I've also added documentation for plugins.


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by omefire <gi...@git.apache.org>.
Github user omefire commented on the pull request:

    https://github.com/apache/cordova-docs/pull/292#issuecomment-105600671
  
    PR updated with code review comments !
    Please, take another look.


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by omefire <gi...@git.apache.org>.
Github user omefire commented on the pull request:

    https://github.com/apache/cordova-docs/pull/292#issuecomment-105635705
  
    @TimBarham 


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by TimBarham <gi...@git.apache.org>.
Github user TimBarham commented on the pull request:

    https://github.com/apache/cordova-docs/pull/292#issuecomment-104768868
  
    You should also describe what happens if you add a platform (via `cordova platform add`) that has an entry saved in `config.xml` (specifically that if you add the platform using some "@" spec, that will be used and will overwrite the entry in `config.xml`, and if you add the platform without any "@" spec, we will use whatever is saved in `config.xml`). Also, as of 5.0.0, a platform version is saved to `config.xml` using the caret prefix, which means you won't necessarily get the exact version you saved, but it should be a *compatible* version.


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by TimBarham <gi...@git.apache.org>.
Github user TimBarham commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/292#discussion_r30933383
  
    --- Diff: docs/en/edge/platform_plugin_versioning_ref/index.md ---
    @@ -0,0 +1,70 @@
    +---
    +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. <br />
    +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. <br />
    +When a save command is issued, the config.xml file is used to reference details about platforms and plugins versions that should be used with the app. The 'restore' step happens automatically when a **'cordova prepare'** is issued. Restoration makes 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" />
    +        ...
    +    </widget>
    +
    +
    +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>> --save
    --- End diff --
    
    Strictly speaking, shouldn't this be:
    
        $ cordova platform update <platform[@<version>]> --save
    
    (should it also include `directory` and `git_url` - does update work with those?)


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by omefire <gi...@git.apache.org>.
Github user omefire commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/292#discussion_r31052233
  
    --- Diff: docs/en/edge/platform_plugin_versioning_ref/index.md ---
    @@ -0,0 +1,70 @@
    +---
    +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. <br />
    +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. <br />
    +When a save command is issued, the config.xml file is used to reference details about platforms and plugins versions that should be used with the app. The 'restore' step happens automatically when a **'cordova prepare'** is issued. Restoration makes 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" />
    +        ...
    +    </widget>
    +
    +
    +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>> --save
    --- End diff --
    
    Yes, it does.


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by TimBarham <gi...@git.apache.org>.
Github user TimBarham commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/292#discussion_r30929325
  
    --- Diff: docs/en/edge/platform_plugin_versioning_ref/index.md ---
    @@ -0,0 +1,70 @@
    +---
    +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. <br />
    +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. <br />
    +When a save command is issued, the config.xml file is used to reference details about platforms and plugins versions that should be used with the app. The 'restore' step happens automatically when a **'cordova prepare'** is issued. Restoration makes use of information previously saved in the config.xml file.
    --- End diff --
    
    I don't think this reads well (`config.xml file is used to reference details`). Perhaps rearrange the sentence a bit - something like *The save command will store details about the app's platform and plugin versions in config.xml*. Also... not sure what our approach in docs is typically... but should command names be in monospace? As in `save` and `cordova prepare` etc?


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by TimBarham <gi...@git.apache.org>.
Github user TimBarham commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/292#discussion_r31158610
  
    --- 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.
    --- End diff --
    
    Typo: 'describe**d**'


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by purplecabbage <gi...@git.apache.org>.
Github user purplecabbage commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/292#discussion_r30932290
  
    --- Diff: docs/en/edge/platform_plugin_versioning_ref/index.md ---
    @@ -0,0 +1,70 @@
    +---
    +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. <br />
    +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. <br />
    +When a save command is issued, the config.xml file is used to reference details about platforms and plugins versions that should be used with the app. The 'restore' step happens automatically when a **'cordova prepare'** is issued. Restoration makes use of information previously saved in the config.xml file.
    --- End diff --
    
    +1 <br/> has no place in a markdown file


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by asfgit <gi...@git.apache.org>.
Github user asfgit closed the pull request at:

    https://github.com/apache/cordova-docs/pull/292


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by TimBarham <gi...@git.apache.org>.
Github user TimBarham commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/292#discussion_r30932058
  
    --- Diff: docs/en/edge/platform_plugin_versioning_ref/index.md ---
    @@ -0,0 +1,70 @@
    +---
    +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. <br />
    +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. <br />
    +When a save command is issued, the config.xml file is used to reference details about platforms and plugins versions that should be used with the app. The 'restore' step happens automatically when a **'cordova prepare'** is issued. Restoration makes use of information previously saved in the config.xml file.
    --- End diff --
    
    Instead of using a `<br>` here, can you just leave a blank line? The resulting paragraph spacing is much nicer. Like this:
    
    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.


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by TimBarham <gi...@git.apache.org>.
Github user TimBarham commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/292#discussion_r31158552
  
    --- 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.
    --- End diff --
    
    Note that this doesn't actually work. When adding a platform from a location (other than a local folder), you currently have to specify the platform name. So this should be:
    
    **cordova platform add android@https://github.com/apache/cordova-android.git​ --save**


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by TimBarham <gi...@git.apache.org>.
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.


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by omefire <gi...@git.apache.org>.
Github user omefire commented on the pull request:

    https://github.com/apache/cordova-docs/pull/292#issuecomment-104746042
  
    I'll soon send another one for the plugin side of things.


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by omefire <gi...@git.apache.org>.
Github user omefire commented on the pull request:

    https://github.com/apache/cordova-docs/pull/292#issuecomment-106483600
  
    Thanks @TimBarham  for reviewing. I've addressed your comments.


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


[GitHub] cordova-docs pull request: CB-8900: Documentation for the platform...

Posted by TimBarham <gi...@git.apache.org>.
Github user TimBarham commented on a diff in the pull request:

    https://github.com/apache/cordova-docs/pull/292#discussion_r31158760
  
    --- 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 :
    --- End diff --
    
    "mass-save all" is a bit superfluous - how about just "you want to save all existing platforms" (although "existing" is perhaps a little unclear - perhaps "installed" or "currently added" or something).


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