Merge pull request #31 from rakatyal/raghav/newIA
New IA for Cordova website
diff --git a/proposals/ImproveCordovaDocumentation.md b/proposals/ImproveCordovaDocumentation.md
new file mode 100644
index 0000000..0b77c8f
--- /dev/null
+++ b/proposals/ImproveCordovaDocumentation.md
@@ -0,0 +1,47 @@
+### Improving Cordova Documentation
+
+For the last few weeks, we have taken measures to get in touch with and understand the experiences of a Cordova user. We put up a survey which received > 900 responses and tried to understand the pain points of working with Cordova. As it was brought up in F2F as well, majority of the users (~100 survey responses) think that the Cordova documentation isn’t up to the mark and is the biggest problem they face. We went through the responses and have summarized them.
+
+We discussed and came up with few guidelines and possible solutions for these problem areas as mentioned. It would be great if you guys could give feedback, provide better solutions and volunteer for some of these.
+
+
+- Incorrectness
+ - Outdated Stuff
+ - Docs don’t reflect changes in plugin versions
+ - Action Items:
+ - Document Scrub: Get rid of outdated/duplicate content
+ - Pin guides to specific versions
+ - Add comments to docs so that people may comment if they find any inconsistency
+ - Write a blog post summarizing all the survey results
+
+- Docs are hard to find
+ - Organization on the website needs to be simplified
+ - Action Items:
+ - Add FAQ section to the website
+ - Work on SEO of docs and website
+ - Draft a proposal to re-organize content on the website
+
+- Plugin docs are all over the place
+ - Action Items:
+ - Pull core plugin docs from github along with centralized docs
+ - Define a consistent structure for plugin docs
+ - Show docs preview on plugin search
+
+- Tutorials needed
+ - Basic app/plugin/platform development
+ - Integration with tools like grunt, gulp, uglify
+ - Release/Publish apps on different platforms
+ - Debugging
+ - How to work with config.xml and plugin.xml
+ - Better examples of plugin API usage
+ - Blog showcasing APIs
+
+- Quality
+ - Plugin docs are usually very limited
+ - Advanced usage/Core understanding docs are absent
+ - Docs are difficult to apprehend for beginners
+ - Action Items:
+ - Write new articles for advanced usage and understanding of Cordova core: understand the working of cli commands, tasks and order of execution of build/run/prepare commands, understanding native bridges
+ - Include sample apps on our website
+ - Go through stackoverflow and find common problems and incorporate docs accordingly
+ - General guidelines to write/review docs
diff --git a/proposals/ImprovedDocumentationGenerator.md b/proposals/ImprovedDocumentationGenerator.md
new file mode 100644
index 0000000..0e2aad8
--- /dev/null
+++ b/proposals/ImprovedDocumentationGenerator.md
@@ -0,0 +1,159 @@
+Doc System Improvement Proposal
+===============================
+
+## Motivation
+
+Our current docs are becoming slightly out of date and not keeping up with our development pace. The current docs system has a high latency and steep learning curve for maintenance, and it has started functionally and visually lagging behind docs for related technologies (see [react][react_docs], [unity][unity_docs], [ember][ember_docs], [angular][angular_docs], [ionic][ionic_docs]).
+
+This proposal aims to accomplish the following three goals for our documentation:
+
+- add a search feature
+- make contribution very easy
+- set up automatic deployment
+
+Below is a formalized list of requirements that are proposed for the Cordova docs.
+
+## Requirements
+
+The following features must be supported by the Cordova docs.
+
+<dl>
+ <dt>"edit on github" buttons</dt>
+ <dd>
+ Can easily submit changes to the docs via a PR on GitHub by clicking on an "Edit this page" button or something similar.
+ </dd>
+ <dt>search</dt>
+ <dd>
+ Can search through the full text of the docs.
+ </dd>
+ <dt>doc versions</dt>
+ <dd>
+ Can browse and change docs for any Cordova version.
+ </dd>
+ <dt>localization</dt>
+ <dd>
+ Can easily translate the docs into and/or read the docs in different languages.
+ </dd>
+ <dt>API docs</dt>
+ <dd>
+ Can automatically get generated docs for public APIs (plugins, cordova-lib, cordova-js).
+ </dd>
+ <dt>analytics</dt>
+ <dd>
+ Can have analytics for the docs website.
+ </dd>
+</dl>
+
+The following features are nice to have in the Cordova docs.
+
+<dl>
+ <dt>easy transition</dt>
+ <dd>
+ Changes to the docs inconvenience people as little as possible.
+ </dd>
+ <dt>good UI</dt>
+ <dd>
+ The UI for the docs is aesthetically pleasing, intuitive to use, and gets relevant information with as little friction as possible.
+ </dd>
+</dl>
+
+## Constraints
+
+<dl>
+ <dt>free</dt>
+ <dd>
+ We don't have a budget outside of our own computing power and engineering resources.
+ </dd>
+ <dt>static</dt>
+ <dd>
+ The generated docs should be static files (unless we find a free hosted solution).
+ </dd>
+</dl>
+
+## Solutions
+
+### [Sphinx][sphinx]/[Readthedocs][rtfd]
+
+Sphinx is a mature and complete documentation system written in Python. All documentation hosted by [readthedocs.org][rtfd] uses Sphinx. Sphinx meets all functional requirements of this proposal.
+
+Pros:
+
+- mature and used by many large software projects; many people know it
+- feature-rich: search, referencing, internationalization, templating, generation, plugins, and many others
+
+Cons:
+
+- needs some knowledge of Python
+- needs migration from Markdown to [reStructuredText][rest]
+- needs migration from Crowdin to Sphinx's own [internationalization tools][sphinx_int]
+
+### [Jekyll][jekyll]
+
+Jekyll is a static site generator written in Ruby. It is used to generate the docs of [React.js][react_docs]. It meets some functional requirements of this proposal.
+
+Pros:
+
+- mature and used for many static websites; many people know it
+- integrates well with other tools
+- has powerful templating for the output
+
+Cons:
+
+- does not have search or internationalization
+
+### [JSDoc][jsdoc]
+
+JSDoc is a mature documentation system written in JS. It is used as a back-end to generate automated source code docs for many JS projects. It meets some functional requirements of this proposal.
+
+Pros:
+
+- mature and widely used; many people know it
+- integrates well with other tools
+
+Cons:
+
+- does not have search or internationalization
+
+### [Current System][cordova-docs]
+
+The current Cordova docs could also be extended to meet the proposed requirements.
+
+Pros:
+
+- no migration required
+
+Cons:
+
+- does not have search or templating
+- non-standard, so the learning curve remains
+
+Proposals
+=========
+
+### Option #1: Sphinx
+
+Sphinx (either with readthedocs.org or without) would provide a complete solution for Cordova's documentation needs. However, it would require a (hefty) migration.
+
+### Option #2: Jekyll + JSDoc + Crowdin
+
+A mix of Jekyll, JSDoc, and the current Crowdin pipeline would suit Cordova's documentation needs. The existing documentation can be migrated to such a system with only moderate effort.
+
+Notes
+=====
+
+[This prior analysis][comparison] was used to decide on a JS documentation framework. Currently no quantitative analysis has been made to compare the solution candidates, but one can be carried out if required.
+
+[react_docs]: https://facebook.github.io/react/docs/getting-started.html
+[unity_docs]: http://docs.unity3d.com/Manual/index.html
+[ember_docs]: http://guides.emberjs.com/v1.12.0/
+[angular_docs]: https://docs.angularjs.org/api
+[ionic_docs]: http://ionicframework.com/docs/
+
+[comparison]: http://blog.fusioncharts.com/2013/12/jsdoc-vs-yuidoc-vs-doxx-vs-docco-choosing-a-javascript-documentation-generator/
+[sphinx]: http://sphinx-doc.org/
+[rtfd]: https://readthedocs.org/
+[rest]: http://docutils.sourceforge.net/rst.html
+[sphinx_int]: http://sphinx-doc.org/latest/intl.html
+[jekyll]: http://jekyllrb.com/
+[jsdoc]: http://usejsdoc.org/
+[cordova-docs]: https://github.com/apache/cordova-docs
diff --git a/proposals/android-n-support.md b/proposals/android-n-support.md
new file mode 100644
index 0000000..90dd47d
--- /dev/null
+++ b/proposals/android-n-support.md
@@ -0,0 +1,46 @@
+# Android N and Cordova
+
+The purpose of this discuss is to highlight the new features of Android N
+that may affect Cordova. I did a brief investigation of the upcoming changes
+and did some minor testing (building a trivial app, running mobilespec, etc).
+I didn't find too many issues, but we should track them as they come up.
+
+You can see a JIRA query for all Android N related issues
+[here][android-n-query]. If you file an issue, be sure to add the "AndroidN"
+label so that it shows up.
+
+
+## Multi-Window Support
+
+This is the big new feature of Android N and one that presents some minor
+problems for existing Cordova apps. When apps that are compiled with the pre-N
+SDK are put into multi-window mode, the user gets a message saying "App may not
+work in multi-window mode". Cordova apps definitely fall into the non-working
+category because they tend to either crash or randomly restart when placed into
+multi-window mode.
+
+The issue is in the way Android handles resizing an app. By default, Android
+just destroys/restarts the current Activity whenever the app changes size.
+Unfortunately, in a Cordova app the webview gets destroyed along with the
+Activity and the app will appear to restart from scratch. In practice, this
+mostly looks like the app randomly restarts sometimes when it's resized. The
+app also sometimes crashes (may be related to the first point
+[here][other-behavior-changes]).
+
+The fix is a really simple one-line change to AndroidManifest.xml and it works
+even with pre-N SDK versions. We just need to make sure that people are aware of
+the issue so that they can either update to newer versions of cordova-android (once
+we've published a fix) or make the change themselves if they're unwilling to update.
+
+I don't think that multi-window support will require any changes to core plugins.
+Some third party plugins that have their own UI might run into issues and may need
+to update, but I haven't done any research. The issue there is that Android assumes
+that any Activity spawned by a multi-window supporting activity also supports
+multi-window, so you could potentially get into a weird state where you add a plugin
+that does not support it and it causes problems. It's something to be aware of.
+Developers can also disable multi-window support by editing AndroidManifest.xml.
+
+
+
+[android-n-query]: https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20(Open%2C%20%22In%20Progress%22%2C%20Reopened)%20AND%20labels%20%3D%20AndroidN
+[other-behavior-changes]: http://developer.android.com/preview/behavior-changes.html#other
\ No newline at end of file
diff --git a/proposals/plugin-version-fetching.md b/proposals/plugin-version-fetching.md
new file mode 100644
index 0000000..4916e03
--- /dev/null
+++ b/proposals/plugin-version-fetching.md
@@ -0,0 +1,130 @@
+# Plugin Version Fetching Proposal
+
+## Overview
+
+This is a proposal to improve the way we fetch plugins from npm. There is a need for us to do something beyond pinning plugin versions in cordova-lib as that does not support third party plugins. If we are solving this problem in Cordova, we can do so in a general way that improves the stability of the entire ecosystem and not just core. This proposal suggests that we add support for a mapping of plugin versions to project requirements in the plugin package.json that the CLI can check against. This would replace the current `<engine>` tag in the plugin.xml.
+
+The reason we insert this into the package.json is that it is possible to get a package.json from npm without fetching the whole package (`npm info <plugin-package-name>`), thus preventing the need to fetch all the versions of a plugin to find a compatible version. This way the pinning information can live in the npm package rather than a centralized location like cordova-lib.
+
+### Proposal
+
+I propose we add this entry to the "cordova" key in the package.json for plugins:
+
+```
+cordovaDependencies:
+{
+ <plugin-version>:
+ {
+ <constraint>: <constraint-version>,
+ ...,
+
+ },
+ ...
+}
+```
+
+#### `<plugin-version>` allowed values
+* Single version (e.g. `1.0.0`)
+* Upper Bound (e.g. `<2.0.0`). This is for BIG breaking changes. For example, if we made a change to some platform that breaks compatibility with all earlier versions of a plugin, we would use this tag to retroactively update their mappings. It won't override earlier tags, just add to them. See [3] for a clarification of this behavior. This is sugar; we could leave it out if we want to keep things simple
+
+#### `<constraint>` allowed values:
+* `cordova`
+* Platforms (e.g. `cordova-android`)
+* Plugins (e.g. `cordova-plugin-camera`)
+
+
+#### `<constraint-version>` syntax:
+* npm semver
+
+Essentially, this compiles the plugin.xml `<engine>` tags for each version of a plugin into one handy list in package.json. Each entry in the object needs to only specify the platform versions it cares about, just like the engine tag. We can also add support for plugin dependency versions (as in the plugin.xml's `<dependency>` tag).
+
+When the user runs `cordova plugin add <plugin-package-name>`, the CLI will check the plugin versions in descending order to examine each constraint entry and determine if the current project can support that plugin version. It will then try and fetch the highest compatible plugin version (see [1] and [2] for high level pseudocode). The CLI must clearly indicate why the user is not getting the latest version of a plugin if it is not compatible with the current project. This can take the form of listing the project requirements for the latest plugin version in some human readable way.
+
+If a plugin version's project requirements information is not specified, the CLI will use the project requirements information for the next version down. For example, consider the following entry:
+
+```
+cordovaDependencies: {
+ "0.0.1": { ... },
+ "1.0.0": { ... }
+}
+```
+
+Here, we have specified the project requirements of two versions of a plugin (0.0.1 and 1.0.0). All versions of the plugin between 0.0.1 and 1.0.0 are assumed to have the requirements as those specified in the 0.0.1 entry. If the current project satisfies the 0.0.1 project requirements, then we get the highest version of the plugin that is greater than or equal to 0.0.1 and less than 1.0.0. This helps us to reduce the size of the mapping if the project requirements don't change across multiple releases.
+
+Fetching should always fall back to the current behavior (fetching latest/pinned plugin versions) if there are no versions of the plugin that the project supports. This is to make sure that if some plugin developer neglects their plugin mapping, their plugin does not become impossible to install without giving a specific version. However, in this case the CLI will deliver a stern warning that the project might not build and explain what project requirements were not satisfied.
+
+### Generating the mapping
+
+We can include a script in plugman to generate the mapping based on old `<engine>` tags in a git repo to make it easier for other developers to opt in. For future releases, the mapping will have to be updated as part of the release step. This should mostly involve us staying up to date with the `<engine>` tag information like we have in the past and updating older versions if there were breaking changes in the platform (with a new upper bound).
+
+While the cordova CLI version can be used as a constraint in the mapping, we should probably default to using platform constraints instead whenever possible. My reasoning here is that it is too easy for the CLI version to go out of sync with a project's installed platforms/plugins. Still, after discussing this with others offline it was made clear to me that it should be available as a constraint because it is more likely that third party plugin developers test against a CLI version rather than individual platforms.
+
+## Pros
+
+* Works for third party and core plugins
+* Keeps plugin platform dependencies in the plugin
+* Allows for more nuanced plugin fetching than pinning does (project's platform versions will be taken into account)
+
+## Cons
+
+* We need to be vigilant in generating this mapping and maintaining plugin.xml when making releases
+
+## Footnotes
+
+#### [1] Plugin Fetching behavior for `cordova plugin add`
+```
+If version is specified by user (i.e. '@'):
+ Fetch that version
+Else if version is specified in config.xml:
+ Fetch that version
+Else:
+ If Cordova dependency constraint mappings are found in plugin's package.json:
+ If some plugin version's constraint mapping is satisfied by current project:
+ Let x = plugin version of highest mapping that is satisfied
+ Let y = plugin version of the next mapping above x (an unsatisfied mapping)
+
+ Fetch highest version of plugin that is >= x and < y
+ Print brief explanation as to why that version was fetched
+ Else:
+ Fetch latest (or pinned) version of plugin
+ Warn user that the project might not build
+ Else:
+ Fetch latest (or pinned) version of plugin (i.e. the current behavior)
+```
+
+##### [2] Logic for determining if a plugin version's constraint mapping is satisfied
+```
+First, AND together all applicable upper range constraints for this plugin version's constraint mapping (see [3])
+
+If Cordova version is constrained and installed version does not satisfy semver constraint:
+ return NotSatisfied
+Else:
+ For each platform/plugin in constraint mapping:
+ If that platform/plugin is installed in project:
+ If project's installed platform/plugin version satisfies the mapped semver constraint:
+ Continue
+ Else:
+ Return NotSatisfied
+ Else:
+ Continue
+
+ Return Satisfied
+```
+
+#### [3] Example for Upper Bound Logic
+
+Consider this mapping:
+
+```
+cordovaDependencies: {
+ "0.0.1": { cordova-ios: ">1.0.0" },
+ "<1.0.0": { cordova-ios: "<2.0.0" },
+ "<2.0.0": { cordova-ios: "<5.0.0" }
+}
+```
+
+Here we specify one plugin version (0.0.1) and two upper bounds (<1.0.0 and <2.0.0) that constrain cordova-ios. The two upper bounds do not override the constraint of 0.0.1, they are combined via AND at evaluation time. When we go to check the cordova-ios version of the project, the constraint we will evaluate for plugin version 0.0.1 will be the combination of these three:
+
+```
+ >1.0.0 AND <2.0.0 AND <5.0.0
+```
