[Cordova Wiki] Update of "StoringRepoVersionsDesign" by AndrewGrieve

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Cordova Wiki" for change notification.

The "StoringRepoVersionsDesign" page has been changed by AndrewGrieve:
https://wiki.apache.org/cordova/StoringRepoVersionsDesign?action=diff&rev1=2&rev2=3

- ## page was renamed from PlatformVersionScripts
- Cordova platforms should have a simple, reliable method to report their version number, for use by automated tools such as CLI and plugman.
+ = Storing Versions =
+ This section describes how we '''''store''''' version numbers on our various repositories.
  
- The current method for doing this (supported by Android; support coming for other platforms) is to have a script in the platform package, under `bin/templates/cordova/version`, which can be called to report the version number.
+ == Cordova Platform Repositories ==
+ There are two aspects of this:
+  1. Storing the version for the repository
+  2. Storing the version of the platform of a created project (as created by the `bin/create` script)
  
- Previously, this file would, on some platforms, go through some rather complicated process to infer the correct version number (such as checking the git hash of the included cordova.js file). It will be simpler and easier to maintain to have this file simply echo a string constant.
+ For #1:
+  * We will continue to use a VERSION file at the root of the repository.
  
+ For #2:
+  * There is already a way to report the version - through the `cordova/version` script of a created project.
+  * The logic of this script used to be different across platforms
+  * The new logic here is to have it echo a hard-coded string, which is the contents of the VERSION file at the time of creation.
+ 
+ == Cordova JS ==
+ There are two aspects of this:
+  1. Storing the version for the repository
+  2. Storing the version for within generated cordova.js files.
+ 
+ For #1:
+  * We will continue to use a VERSION file at the root of the repository.
+ 
+ For #2:
+  1. Use build-time logic to stamp cordova.js files with a version through a variable at the top of the file.
+  1. When built in the context of a git repo, and not at a tagged commit, append the git hash.
+  1. When not in a git repo or at a tagged commit, don't try and append a hash.
+ 
+ == Cordova Plugins ==
+ Plugins store their version within their plugin.xml file. No VERSION files exist.
+ 
+ == Plugman & CLI ==
+ These tools are built as npm modules, and so use package.json. No VERSION files exist.
+ 
+ 
+ = Choosing Version Numbers Based on Dev vs Release =
+ This section describes how we '''''choose''''' version numbers for each branch within our various repositories.
+ 
+ == Cordova Platform Repositories ==
  The version number should correspond closely to the git branch. When a release branch is made, both the branch and the master branch should be updated. The master branch should *always* have a version number ending in "-dev", which indicates the version currently being developed. A fresh release branch should change the version to an "-rc1" version, and then change to the unqualified version number when it is released.
  
  (This constant version number can be updated manually, but *should* eventually be updated via coho as release branches are made.)
@@ -47, +80 @@

  ||WP8           || {o}         ||
  ||www           || {o}         ||
  
+ == Cordova JS ==
+ cordova-js follows the same scheme as platforms.
+ 
+ 
+ == Cordova Plugins ==
+ Current state is that we have master & dev branches. This is because plugman pulls from master by default, so it must remain stable.
+ 
+  1. Versions should stay be suffixed with "-dev" on the dev branch.
+  1. This means a releases involves:
+     a. Update plugin.xml's version to "3.1.0" on dev branch
+     a. Merge dev -> master
+     a. Update plugin.xml's version to "3.2.0-dev" on dev branch
+ 
+ == Plugman & CLI ==
+ cordova-plugman and cordova-cli follow the same scheme as platforms.
+