Github user geomacy commented on a diff in the pull request:
https://github.com/apache/brooklyn-docs/pull/198#discussion_r124210019
--- Diff: guide/blueprints/catalog/versioning.md ---
@@ -3,18 +3,130 @@ title: Versioning
layout: website-normal
---
-### Versioning
+Brooklyn supports multiple versions of a type to be installed and used at
the same time.
+Versions are a first-class concept and are often prominently displayed in
the UI.
-Version numbers follow the OSGi convention. This can have a major, minor,
micro and qualifier part.
-For example, `1.0`. `1.0.1` or `1.0.1-20150101`.
+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.
+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:
-The combination of `id:version` strings must be unique across the catalog.
-It is an error to deploy the same version of an existing item:
-to update a blueprint, it is recommended to increase its version number;
-alternatively in some cases it is permitted to delete an `id:version`
instance
-and then re-deploy.
-If no version is specified, re-deploying will automatically
-increment an internal version number for the catalog item.
+* Use a `-SNAPSHOT` qualifer suffix on your version when developing
+* Increase the version number when making a change to a non-SNAPSHOT type
+
+When adding to the catalog, if no version is supplied, Brooklyn may
automatically
--- End diff --
Not keen on the "may" here, it seems too woolly - will Brooklyn increment
the version or won't it, under what circumstances? Similarly below.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
