git commit: CB-7774 Have a separate section on upgrades

[ma...@apache.org]

Repository: cordova-coho
Updated Branches:
  refs/heads/master f1ce1133d -> 8a5fd63c9


CB-7774 Have a separate section on upgrades


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

Branch: refs/heads/master
Commit: 8a5fd63c987995434c4b9e854ee784cd10386237
Parents: f1ce113
Author: Marcel Kinard <cm...@gmail.com>
Authored: Tue Oct 14 12:22:43 2014 -0400
Committer: Marcel Kinard <cm...@gmail.com>
Committed: Tue Oct 14 12:22:43 2014 -0400

----------------------------------------------------------------------
 docs/versioning-and-release-strategy.md | 34 ++++++++++++++++++----------
 1 file changed, 22 insertions(+), 12 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-coho/blob/8a5fd63c/docs/versioning-and-release-strategy.md
----------------------------------------------------------------------
diff --git a/docs/versioning-and-release-strategy.md b/docs/versioning-and-release-strategy.md
index ab227fe..c0d8147 100644
--- a/docs/versioning-and-release-strategy.md
+++ b/docs/versioning-and-release-strategy.md
@@ -84,24 +84,16 @@ content being added to that individual component. The exception to this
 is that when a new platform is released, and the platform pin in the CLI
 is correspondingly updated, the CLI receives a bump to its third digit, no
 matter the size of the version bump to those platform(s). If the CLI requires
-a change (beyond updating the pin) to handle the new platform, then the second
-digit of the CLI version may get bumped. Tools docs should be stored in each
+a change (beyond updating the pin) to handle the new platform, or if the CLI
+has other changes, then the second or even first
+digit of the CLI version may get bumped - the `SemVer` semantics still
+apply for the CLI. Tools docs should be stored in each
 tool repo, so that the docs are versioned with their source code.
 
-When a user updates the version of the CLI they have installed, this CLI
-update has no effect on the platform and plugin versions that are already
-installed in their project, but they may receive a warning or notice if
-the installed platform versions are older than the versions pinned by
-the CLI. However, if they subsequently do a `cordova platform update`
-they will get the pinned version specified in their newer CLI.
-
 The CLI version number will be the "name" of the Cordova version. Thus
 tools and platform updates will cause a bump of the "Cordova version",
 but plugins will not.
 
-Release notes should be easy for users to find and understand. This is important
-because of the non-trivial number of components.
-
 Where Cordova components have dependencies upon other Cordova components
 (i.e., CLI depends on `cordova-lib`) or upon third-party components (i.e.,
 CLI depends on `nopt`), the `package.json` should fully pin the version of
@@ -128,6 +120,24 @@ even though they consistently executed `npm install cordova@3.8.0`. As
 npm-shrinkwrap matures, we hope that it will take care of dependency pinning
 across the whole tree. Until then, only part of the tree is properly pinned.
 
+## Upgrade Behavior
+
+When a user updates the version of the CLI they have installed, this CLI
+update has no effect on the platform and plugin versions that are already
+installed in their project, but they may receive a warning or notice if
+the installed platform versions are older than the versions pinned by
+the CLI. However, if they subsequently do a `cordova platform update`
+they will get the pinned version specified in their newer CLI.
+
+Release notes should be easy for users to find and understand. This is important
+because of the non-trivial number of components.
+
+At some future time, there may be added a `cordova upgrade` command,
+which would install the new pinned versions of all platforms (possibly
+replacing, or possibly alongside existing platforms), and not attempt to update
+a specific platform in-place. There are cases where users have modified platform
+native code.
+
 # Release Strategies
  1. __On-Demand Releases__
    * Any repository can do an on-demand release at any time.


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