Merge pull request #63 from audreyso/CB-11982proposal
CB-11982 proposal for creating a new cordova config command
diff --git a/README.md b/README.md
index e7a039f..1da7f79 100644
--- a/README.md
+++ b/README.md
@@ -30,7 +30,7 @@
| [Platform project](proposals/PlatformProject.md) | Some ideas adopted into the Cordova Platform API work.
| [Plugin version fetching - improve plugin versioning story](proposals/plugin-version-fetching.md) | Completed & part of Cordova 6.1
| [New information architecture for Cordova](proposals/NewInformationArchitecture.md) | Completed and live on docs.cordova.io.
-| [Add Telemetry to Cordova CLI](proposals/Telemetry.md) | In Progress
+| [Add Telemetry to Cordova CLI](proposals/Telemetry.md) | Completed
| Ideas for improving documentation [[1]](proposals/ImprovedDocumentation.md) [[2]](proposals/ImproveCordovaDocumentation.md) | Most of the recommendations completed |
| [CI for PRs submitted for cordova plugins](proposals/ci-for-plugin-prs.md) | Completed
| [Unified cordova-fetch proposal](https://github.com/cordova/cordova-discuss/blob/master/proposals/fetching.md) | Completed
diff --git a/proposals/GithubMove.md b/proposals/GithubMove.md
new file mode 100644
index 0000000..88c0e15
--- /dev/null
+++ b/proposals/GithubMove.md
@@ -0,0 +1,84 @@
+# Github Move
+
+https://issues.apache.org/jira/browse/INFRA-14347
+
+## To Github -> Platforms (4)
+
+- cordova-browser
+- cordova-ios
+- cordova-android
+- cordova-windows
+
+## To Github -> Tools and Docs (11)
+
+- cordova-cli
+- cordova-coho
+- cordova-common
+- cordova-create
+- cordova-fetch
+- cordova-js
+- cordova-lib
+- cordova-node-xcode
+- cordova-paramedic
+- cordova-plugman
+- cordova-docs
+
+## To Github -> Plugins (26)
+
+- cordova-plugin-inappbrowser
+- cordova-plugin-camera
+- cordova-plugin-geolocation
+- cordova-plugin-file
+- cordova-plugin-device
+- cordova-plugin-wkwebview-engine
+- cordova-plugin-dialogs
+- cordova-plugin-network-information
+- cordova-plugin-screen-orientation
+- cordova-plugin-globalization
+- cordova-plugin-vibration
+- cordova-plugin-battery-status
+- cordova-plugin-test-framework
+- cordova-plugin-media-capture
+- cordova-plugin-compat
+- cordova-plugin-console
+- cordova-plugin-splashscreen
+- cordova-plugin-statusbar
+- cordova-plugin-whitelist
+- cordova-plugin-file-transfer
+- cordova-plugin-media
+- cordova-plugin-contacts
+- cordova-plugin-device-motion
+- cordova-plugin-device-orientation
+- cordova-plugin-legacy-whitelist
+- cordova-plugins
+
+## NOT Moving -> Misc (11)
+
+- cordova-template-reference
+- cordova-test-platform
+- cordova-serve
+- cordova-medic
+- cordova-mobile-spec
+- cordova-labs
+- cordova-registry-web
+- cordova-registry
+- cordova-weinre
+- cordova-app-harness
+- cordova-app-hello-world
+
+## NOT Moving -> Platforms (14)
+
+- cordova-electron
+- cordova-amazon-fireos
+- cordova-firefoxos
+- cordova-osx
+- cordova-windows-phone
+- cordova-wp7
+- cordova-wp8
+- cordova-tizen
+- cordova-ubuntu
+- cordova-webos
+- cordova-qt
+- cordova-bada
+- cordova-bada-wac
+- cordova-blackberry
diff --git a/proposals/autosave-by-default.md b/proposals/autosave-by-default.md
new file mode 100644
index 0000000..4c7c634
--- /dev/null
+++ b/proposals/autosave-by-default.md
@@ -0,0 +1,42 @@
+# Autosave by default for cordova@7 Proposal
+Status : Proposed
+
+## Current
+To save or remove dependencies, users must include the --save flag.
+
+Examples:
+cordova platform add ios --save
+cordova plugin add cordova-plugin-camera --save
+
+## Proposal
+Autosave will be the default option.
+Example: cordova platform add ios
+This command will automatically save the ios platform.
+Include a --no-save flag to not save.
+Example: cordova platform add ios --nosave
+This command will allow the ios platform to NOT be saved.
+
+### Notes
+Autosave will only be used in the cli right now (not cordova-lib).
+If you're using cordova-lib directly, you will still need to use the
+--save flag.
+
+### Future Goals
+Include a global config to turn autosave off for cordova.
+https://issues.apache.org/jira/browse/CB-11982
+
+### Links
+https://issues.apache.org/jira/browse/CB-12008
+
+### Motivation
+ Our analytics show --save usage is pretty low (presumably due to people not knowing about it). By having autosave as the default, users won’t have to worry about remembering to save. If users don’t want to save, there are options to opt out of saving with the new --nosave flag.
+
+### Use Cases/Tests:
+1. Cordova platform add ios, expect save to be true.
+2. Cordova platform remove ios, expect save to be true.
+3. Cordova plugin add cordova-plugin-camera, expect save to be true.
+4. Cordova plugin remove cordova-plugin-camera, expect save to be true.
+5. Cordova platform add ios --nosave, expect save to be false.
+6. Cordova platform remove ios --nosave, expect save to be false.
+7. Cordova plugin add cordova-plugin-camera--nosave, expect save to be false.
+8. Cordova plugin remove cordova-plugin-camera --nosave, expect save to be false.
diff --git a/proposals/save-restore.md b/proposals/save-restore.md
new file mode 100644
index 0000000..762cd30
--- /dev/null
+++ b/proposals/save-restore.md
@@ -0,0 +1,104 @@
+# Unified Cordova npm save & restore Proposal
+- Status: In Progress
+
+## Current
+
+Existing save/restore functionality
+
+1. `cordova plugin add/rm PLUGINNAME||gitURL||localPlugin --save`
+ - adds/rms `<plugin name="cordova-plugin-device" spec="../../cordova-plugin-device" />` to `config.xml`.
+ - plugin add: https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cordova/plugin.js#L210-L235
+ - plugin rm: https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cordova/plugin.js#L291-L298
+ - plugin variables: https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cordova/plugin.js#L156-L175 & https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cordova/plugin.js#L445-L464
+
+2. `cordova platform add/rm Platform||gitURL||localPath --save`
+ - adds/rms `<engine name="ios" spec="~4.2.1" />` to `config.xml`
+ - platform rm: https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cordova/platform.js#L247-L263
+ - platform add: https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cordova/platform.js#L227-L238
+
+3. `cordova platform/plugin save`
+ - adds installed but not saved plugins + platforms to `config.xml`
+ - platforms: https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cordova/platform.js#L247-L263
+ - plugins: https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cordova/plugin.js#L409-L451
+
+4. autosave for platforms and plugins (didn't test, not documented)
+ - manually create .cordova/config.json, add `"auto_save_plugins":"true"` and `"auto_save_platforms":"true"`
+ - https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cordova/platform.js#L76
+ - https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cordova/plugin.js#L538-L542
+
+5. `cordova prepare` restores missing plugins and platforms based on `config.xml`
+ - https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cordova/restore-util.js
+ - https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cordova/prepare.js#L46
+ - https://github.com/apache/cordova-lib/blob/master/cordova-lib/src/cordova/prepare.js#L66
+
+## Proposal:
+
+* Support saving and restoring plugins/platforms in `package.json`.
+* `config.xml` is used preferences, `package.json` is used for saving & restoring.
+* Introduce a new `cordova` key in `package.json` that stores an array of saved platforms and a plugins object containing saved plugins. The `cordova` key will also store plugin variables, with the key being the plugin name and the value being an object that contains the variable information. The `cordova` key is required for restoring.
+
+Example:
+```javascript
+{
+...
+ "dependencies": {
+ "cordova-plugin-device": "^1.1.3",
+ "cordova-android": "^5.2.2",
+ "cordova-ios": "https://github.com/apache/cordova-ios"
+ },
+ //new cordova key
+ "cordova": {
+ "platforms": ["andoid","ios"],
+ "plugins": {
+ //store plugin variables if present
+ "cordova-plugin-facebook4": {"APP_ID":"123456", "APP_NAME":"myApp"},
+ "cordova-plugin-device": {}
+ }
+ }
+...
+}
+```
+
+* `--save` should save to `package.json` as well as `config.xml`. This is already possible with `cordova-fetch`. `cordova plugin/platform add/rm --save --fetch` will update `config.xml` and `package.json` if it exists. The `--fetch` flag allows us to pass the `--save` flag down to our `npm install PLUGIN/PLATFORM` command. Plugins and platforms get added as regular dependencies in `package.json` this way. The plan is to make `--fetch` default in **cordova@7**.
+* `cordova plugin/platform add/rm --save` will add/rm the plugin/platform to the new `cordova` key. If your plugin has variables, they will also be added/removed to the `cordova` key in this step.
+* restoring: Look in both `config.xml` and `package.json` for plugin and platform dependencies. Use `cordova` key from `package.json` to restore. Restoring currently happens on a prepare. Restoring may become its own command in **cordova@7**. Read the proposal for that [here](https://github.com/cordova/cordova-discuss/pull/5://github.com/cordova/cordova-discuss/pull/54).
+* autosave: remove functionality. Have docs telling users they can set autosave in npm config if they want it. `npm config set save=true`. `cordova-fetch` will use system *npm*, so this *should* work, but we will have to test it.
+* `cordova platform/plugin save`: Adds existing, unsaved platforms/plugins to `package.json`. Edits need to be made to the `cordova` key and `dependencies` key.
+
+My plan is to add the new save/restore `package.json` logic alongside the existing `config.xml` logic. If your project has a `package.json`, it will start saving to it as well as `config.xml`.
+
+### Notes
+
+* cordova plugin fetching logic will still be respected. If you don't specify a plugin version, the proper version based on `cordovaDependencies` will be fetched.
+* cordova platform fetching logic will stay intact. cordova will grab the pinned platform version unless a different version is specified.
+* cordova plugin dependency resolution will work as it currently does. This includes making sure a plugin doesn't install twice.
+
+### New Requirements
+
+* Need to create a easy way to migrate `config.xml` saved platforms and plugins into `package.json`. I'm thinking this happens during the restore phase. Alternatively, we could create a new command to do it (`cordova install`). In the PR, this is done during the restore phase (prepare)
+* Automatically add `package.json` to existing cordova projects which don't have it. This would happen in `prepare`. **cordova@7** feature.
+* After `cordova prepare`, the restore code will make platforms and plugins in `package.json` and `config.xml` match. The two files should contain the same information. In case of conflicts (say between spec or plugin variables), `package.json` wins.
+
+### Quirks
+
+* Running `npm install` on your projects will fetch the dependencies in `package.json`, but a `cordova prepare` (restore) will be needed to install them to your cordova project.
+* Running `npm install cordova-plugin-device` will fetch the plugin, but won't install it. `cordova plugin add cordova-plugin-device --save` will still be required. Same goes for platforms. Positive is, the plugin/platform will already be fetched.
+* cordova git subdirectories syntax will not be supported anymore for adding plugins. Ex: http://cordova.apache.org/docs/en/latest/reference/cordova-cli/index.html#plugin-spec
+* If you add a plugin/platform with the `--save --fetch` flags, the spec will be saved as `^4.2.0` vs `~4.2.0`. This means we are telling our users it is safe to do minor plugin and platform updates when they have to restore. Our current policy has been to only allow patch updates. This is due to us letting npm handle the install under the hood.
+* If you add a plugin/platform with `--fetch` and then later want to restore the platform/plugin, you will have to use the `--fetch` flag. `cordova prepare --fetch`. This is because `--fetch` uses npm under the hood which saves gitURL + fileURL specs differently than how we have traditionally saved them in `config.xml`. If you try to restore platforms/plugins that were added via `--fetch` from gitURLs or fileURLs, and don't use `--fetch`, an error is expected. Original specs from `config.xml` don't have any problems working with `--fetch` for restore.
+
+### Future goals
+
+* **Cordova@8** will drop save/restore support from `config.xml` and only use `package.json`. This should give ample time to downstreams and IDEs to prepare.
+
+### Links
+
+* https://issues.apache.org/jira/browse/CB-12001
+* https://issues.apache.org/jira/browse/CB-11960
+* PR: https://github.com/apache/cordova-lib/pull/499
+
+### Motivation
+
+1) Remove technical debt. We would remove a bunch of code in regards to managing our depenendencies and instead rely on **npm** to do the work.
+2) Update to a more modern/expected system for users to manage their dependencies
+3) We are going to add a `package.json`. Having a `package.json` may also encourage users to use other node modules in their development.
