[3/5] brooklyn-docs git commit: PR comments on versioning and note on `0` implicit minor/patch

[he...@apache.org]

PR comments on versioning and note on `0` implicit minor/patch


Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/0b106a34
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/0b106a34
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/0b106a34

Branch: refs/heads/master
Commit: 0b106a3425db529bc2f7c56788d838059aa598cc
Parents: 80debad
Author: Alex Heneveld <al...@cloudsoftcorp.com>
Authored: Fri Jun 23 12:44:05 2017 +0100
Committer: Alex Heneveld <al...@cloudsoftcorp.com>
Committed: Fri Jun 23 12:44:05 2017 +0100

----------------------------------------------------------------------
 guide/blueprints/catalog/bundle.md     | 12 ++++++++----
 guide/blueprints/catalog/versioning.md | 26 +++++++++++++++++++-------
 2 files changed, 27 insertions(+), 11 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/0b106a34/guide/blueprints/catalog/bundle.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/catalog/bundle.md b/guide/blueprints/catalog/bundle.md
index 78367cf..964dee0 100644
--- a/guide/blueprints/catalog/bundle.md
+++ b/guide/blueprints/catalog/bundle.md
@@ -6,7 +6,8 @@ layout: website-normal
 ### Bundling Catalog Resources
 
 It is possible to upload catalog items and associated resources as a single bundle to AMP.
-This is useful when you have a blueprint that needs to reference external scripts/resources or 
+This is useful when you have a blueprint that needs to reference external scripts, icons,
+config files or other resources, or 
 when you have multiple blueprints that you want to keep in sync. Brooklyn will persist any 
 uploaded bundles so that they are available after a restart or on HA failover.
 
@@ -14,9 +15,12 @@ The bundle must be a ZIP file including a `catalog.bom` in the root.
 (The `br` CLI will create a ZIP from a local folder, for convenience.)
 The `catalog.bom` must declare a `bundle` identifier and a `version`, 
 following Brooklyn's [versioning](versioning.html) rules.
-Brooklyn will keep track of that bundle, allow SNAPSHOT-version bundles to be replaced,
-and ensure dependent bundles (specified as `brooklyn.libraries` or, for people familiar
-with OSGi, the `Required-bundle` manifest header) are available for searching.
+Brooklyn will keep track of that bundle, allowing items to be added and removed as a group,
+and associated resources to be versioned and included alongside them. 
+With SNAPSHOT-version bundles, it allows replacement of multiple related items at the same time,
+and in advanced cases it allows setting up dependent bundles 
+(specified as `brooklyn.libraries` or, for people familiar with OSGi, the `Required-bundle` manifest header) 
+which will be searched if a blueprint in one bundle references resources from another bundle.
 
 Resources in the bundle can be referenced from the `catalog.bom` by using
 the `classpath:` URL protocol, as in `classpath://path/to/script.sh`.

http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/0b106a34/guide/blueprints/catalog/versioning.md
----------------------------------------------------------------------
diff --git a/guide/blueprints/catalog/versioning.md b/guide/blueprints/catalog/versioning.md
index 14bd2e4..5077b79 100644
--- a/guide/blueprints/catalog/versioning.md
+++ b/guide/blueprints/catalog/versioning.md
@@ -8,8 +8,8 @@ Versions are a first-class concept and are often prominently displayed in the UI
 
 In order to do this, Brooklyn requires that the `id:version` string be unique across the catalog:
 it is normally an error to add a type if a type with the same `id:version` is present.
-Exceptions are if the definition is identical, or if the `version` is noted as a `SNAPSHOT`.
-In extraordinary circumstances it is possible to delete a given `id:version` definition
+The exceptions to this are if the definition is identical, or if the `version` is noted as a `SNAPSHOT`.
+In extraordinary circumstances it may be appropriate to delete a given `id:version` definition
 and then add the new one, but this is discouraged and the usual practice is to:
 
 * Use a `-SNAPSHOT` qualifer suffix on your version when developing
@@ -73,6 +73,11 @@ Thus the _order_ of the list of examples above is:
 * `2.0.0`
 * `3`
 
+For practical purposes, `3`, `3.0`, and `3.0.0` are treated as equivalent,
+but if referencing a version you should use the exact version string defined.
+The version `3.0-0` is different, as the `-0` indicates a qualifier, and
+is ordered before a `3.0.0`.
+ 
 
 #### Advanced: Other Version Syntaxes
 
@@ -88,20 +93,27 @@ Other version syntaxes are supported with the following restrictions:
 This means in practice that almost any common version scheme can be used.
 However the recommended scheme will fit more neatly alongside types from other sources.
 
-Internally in some places, Brooklyn needs to produce OSGi-compliant versions.
+Internally when installing bundles, Brooklyn needs to produce OSGi-compliant versions.
 For the recommended syntax, this mapping consists of replacing the first
 occurrence of `"-"` with `"."` and setting `0` values for absent minor and patch versions.
 Thus when looking at the OSGi view, instead of version `1.10-rc3-20170619`
 you will see `1.10.0.rc3-20170619`.
-This mapping is guaranteed to be one-to-one so no conflicts will occur if the
+Apart from the omission of `0` as minor and patch versions,
+this mapping is guaranteed to be one-to-one so no conflicts will occur if the
 recommended syntax is used.
-(If not using the recommended syntax, the mapping proceeds by treating the first dot-separated fragment 
+Bundles `foo:3`, `foo:3.0`, and `foo:3.0.0` would all be installed using OSGi version `3.0.0`,
+and so would conflict and block installation if there is any change
+(and replace if they have a `-SNAPSHOT` qualifier);
+references to bundles can use `3` or `3.0` or `3.0.0`, though as noted above 
+types contained within would have to be referenced using the exact version string supplied. 
+
+If not using the recommended syntax, the mapping proceeds by treating the first dot-separated fragment 
 as the qualifer and converts unsupported characters in a qualifier to an underscore;
 thus `1.x` becomes `1.0.0.x`, `v1` becomes `0.0.0.v1`, and `"1.0.0-v1.1"` becomes `"1.0.0.v1_1"` 
-hence the bundle replacement noted above.)
+hence the bundle replacement noted above.
 
 If you are creating an OSGi `MANIFEST.MF` for a bundle that also contains a `catalog.bom`, 
-you will need to use the mapped rsult (OSGi version syntax) in the manifest,
+you will need to use the mapped result (OSGi version syntax) in the manifest,
 but should continue to use the Brooklyn-recommended syntax in the `catalog.bom`.
  
 For those who are curious, the reason for the Brooklyn version syntax is to reconcile