brooklyn-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From geomacy <...@git.apache.org>
Subject [GitHub] brooklyn-docs pull request #198: [WIP] Versioning
Date Tue, 27 Jun 2017 10:59:53 GMT
Github user geomacy commented on a diff in the pull request:

    https://github.com/apache/brooklyn-docs/pull/198#discussion_r124223906
  
    --- 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 
    +increment the version number for the catalog item.
    +
    +When deploying a blueprint, if a version number is not specified Brooklyn will typically
use
    +the highest ordered version (see "Ordering" below) in the catalog for the referenced
type,
    +and will thereafter lock the use of that version in that blueprint.
    +(An exception is where types are co-bundled or an explicit search path is defined;
    +in the context of evaluating one type, Brooklyn may prefer versions in the same bundle
or on the search path.) 
    +
    +
    +#### Versioning Syntax
    +
    +Version numbers in Brooklyn are recommended to follow the following syntax:
    +
    +```
    +<major> ( "." <minor> ( "." <patch> )? )? ( "-" <qualifier> )?
    +```
    +
    +where the `<major>`, `<minor>`, and `<patch>` parts are numbers
    +in accordance with [semver](http://semver.org) semantic versioning,
    +assumed to be `0` if omitted,
    +and an `<qualifier>` is made up of letters, numbers, `"-"` and `"_"`
    +in accordance with [OSGi](https://www.osgi.org/release-4-version-4-3-download/)
    +(see sections 1.3.2 and 3.2.5).
    +
    +Examples:
    +
    +* `1.2`
    +* `2.0.0`
    +* `3`
    +* `2.0.0-SNAPSHOT`
    +* `1.10-rc3-20170619`
    +
    +
    +#### Snapshots and Ordering
    +
    +The string `SNAPSHOT` appearing anywhere in the version indicates a pre-release version;
    +if this string is not present the version is treated as a release version.
    +
    +When taking an ordering, for instance to find the highest version, 
    +snapshot versions are always considered lower than release versions.
    +Next, the natural order is taken on the major, minor, and patch fields.
    +Next, a version with no qualifier is considered higher than one with a qualifier.
    +Finally, the qualifier is taken in natural order.
    +
    +The natural order here is defined as ASCII-lexicographic comparison
    +for any non-numeric segments (`"a" < "b"`) but numeric order for digit sequences 
    +(`"9" < "10"`), so it does what is usually expected for versions (`1.9` < `1.10`
    +and `"1.1-rc9-b" < "1.1-rc10-a"`).
    --- End diff --
    
    This actually puts us at odds with OSGI - they define _qualifier_ comparison to be simply
lexicographic. For OSGI, `1.1.0.rc9-b  > 1.1.0.rc10-a`.  If we are converting versions
to bundle versions internally we need to match the OSGI version  comparison rules.  E.g. when
brooklyn is working out what the latest version of a bundle is, we don't want Brooklyn choosing
a different version than OSGI thinks is the latest. 


---
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 infrastructure@apache.org or file a JIRA ticket
with INFRA.
---

Mime
View raw message