Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Equinox/p2/Omni Version"
(→Proposed Version Types) |
(→Proposed Version Types) |
||
| Line 44: | Line 44: | ||
|- valign="top" | |- valign="top" | ||
{{Command|alpha}} | {{Command|alpha}} | ||
| − | | A alhpa numeric sequence of arbitrary depth separated by '.' e.g. 'mango.banana.0003.smoothie'. This type primarily exists to enable encoding of complex types. Segments may not contain reserved ''version range | + | | A alhpa numeric sequence of arbitrary depth separated by '.' e.g. 'mango.banana.0003.smoothie'. This type primarily exists to enable encoding of complex types. Segments may not contain reserved ''version range delimiters''. A complex type is one that requires: |
| + | * more than one alhpa compared segment | ||
| + | * more than three numerical segments in combination with alpha segement(s) | ||
| + | * alpha segment(s) in combination with less than three numerical segments | ||
| + | * non '.' segment separators | ||
|- valign="top" | |- valign="top" | ||
{{Command|numeric}} | {{Command|numeric}} | ||
| Line 53: | Line 57: | ||
|- valign="top" | |- valign="top" | ||
{{Command|string}} | {{Command|string}} | ||
| − | | A free form string version that may contain any character except the version range delimiters | + | | A free form string version that may contain any character except the reserved ''version range delimiters'' |
|- valign="top" | |- valign="top" | ||
{{Command|timestamp}} | {{Command|timestamp}} | ||
| Line 59: | Line 63: | ||
|- valign="top" | |- valign="top" | ||
{{Command|triplet}} | {{Command|triplet}} | ||
| − | | A variation on OSGi, with the same syntax, but where the a lack of qualifier > any qualifier. | + | | A variation on OSGi, with the same syntax, but where the a lack of qualifier > any qualifier. |
|} | |} | ||
| − | + | The ''version range delimiters'' are: '(', ')', '[', ']' and , ',' (comma). | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
====Exploring a possible pattern based type==== | ====Exploring a possible pattern based type==== | ||
| Line 74: | Line 73: | ||
An alternative in these cases is to fix the reordering issue when publishing the artifacts as IUs. Previous example pattern could then be expressed as 'N.n.n-a-a' if it is known that the next to last segment will not have a '-' as a valid part of that segment. | An alternative in these cases is to fix the reordering issue when publishing the artifacts as IUs. Previous example pattern could then be expressed as 'N.n.n-a-a' if it is known that the next to last segment will not have a '-' as a valid part of that segment. | ||
| − | But, there are lots of ways to get into trouble here: can segments be empty | + | But, there are lots of ways to get into trouble here: can segments be empty? how should a trailing segment separator be handled (is it significant?), and much more. |
| − | + | ||
| − | + | ||
| − | + | Anything short of a full regular expression will simply not deal with the most complex (and perhaps also least well thought through) numbering schemes. Using a regular expression as a prefix is certainly powerful, but not recommended. Such a pattern would be better expressed in a a proper named type. | |
| − | + | ||
==Version Type is a property of version and version range== | ==Version Type is a property of version and version range== | ||
Revision as of 22:05, 1 December 2008
Contents
Introduction
This page describes a proposal for adding support for non OSGi version and version ranges in Equinox p2. This page was created as a result of the discussion on the p2 call on Dec 1, 2008.
Background
There are other versioning schemes in wide use that are not compatible with OSGi version and version ranges. The problem is both syntactic and semantic.
Example of semantic issue
Many open source projects do their versioning in a fashion similar to OSGi but with one very significant difference. For two versions that are otherwise equal, a lack of qualifier signifies a higher version then when a qualifier is present. I.e.
1.0.0.alpha 1.0.0.beta 1.0.0.rc1 1.0.0
The 1.0.0 is the final release. The qualifier happens to be in alphabetical order here but that's not always true.
Example of syntax issue
Here are some examples of versions used in Red Had Fedora distributions.
KDE Admin version 7:4.0.3-3.fc9 Compat libstdc version 33-3.2.3-63 Automake 1.4p6-15.fc7
These are not syntactically compatible with OSGi versions as they use colon, and dash as leading separators.
Current implementation in p2
The current implementation in p2 uses the classes Version and Version range to describe the two concepts and these are implementations handling only OSGi version type.
Proposed Solution
Equinox p2 should support a set of "built in" version types. After a lengthy discussion about various "chicken and egg" type of problems relating to dynamic version type specifications and when and how the need for a particular version type is detected, and when it needs to be installed the meeting came to the conclusion that support for a "handful of built in types" would be sufficient as a starting point.
- The interfaces IVersion and IVersionRange should be used throughout the code instead of directly using the corresponding Version and VersionRange classes.
- An IVersion is obtained by calling a factory method such as VersionFactory.create(String versionString)
- An IVersionRange is obtained by a similar factory method
- The version string and version range has a URI scheme like prefix to indicate the version type
- The factory API can naturally contain some options where scheme and version string are either separate or canonical
- When a version or version range is present without the version type prefix, the default is to use OSGi version type (this preserves backwards compatibility).
Proposed Version Types
| type name | description |
| alpha | A alhpa numeric sequence of arbitrary depth separated by '.' e.g. 'mango.banana.0003.smoothie'. This type primarily exists to enable encoding of complex types. Segments may not contain reserved version range delimiters. A complex type is one that requires:
|
| numeric | A numeric sequence of arbitrary depth separated by '.' e.g. 1.1.1.1.1.1 |
| osgi | The default OSGi version type. |
| string | A free form string version that may contain any character except the reserved version range delimiters |
| timestamp | Time stamps compared in ascending order. |
| triplet | A variation on OSGi, with the same syntax, but where the a lack of qualifier > any qualifier. |
The version range delimiters are: '(', ')', '[', ']' and , ',' (comma).
Exploring a possible pattern based type
A "pattern based" type would be of value where it is possible to specify number of segments, their significance, use of numeric or string comparison, and what delimiters to use. It is tempting to specify it as a prefix using a template where 'n' stands for 'numeric', and 'a' for 'alphanumeric, uppercase could mean required. OSGi version could then be expressed as 'N.n.n.a', but this quickly gets complex as there is the need to reorder the segments, specify delimiters, etc. Syntax like 1N.2n.3n.4a could be used to denote the ordering from major (1), to qualifier(4) - which would allow for something like 5a:1N.2n.3n-4a. If only one delimiter per segment is allowed it could easily added as in the 5a:1N.2n.3n-4a example. There are many issues with such an approach - it is probably not powerful enough to meet all requirements, and even if it is more user friendly and compact than having to specify a full regular expression, it is still looks quite horrible.
An alternative in these cases is to fix the reordering issue when publishing the artifacts as IUs. Previous example pattern could then be expressed as 'N.n.n-a-a' if it is known that the next to last segment will not have a '-' as a valid part of that segment.
But, there are lots of ways to get into trouble here: can segments be empty? how should a trailing segment separator be handled (is it significant?), and much more.
Anything short of a full regular expression will simply not deal with the most complex (and perhaps also least well thought through) numbering schemes. Using a regular expression as a prefix is certainly powerful, but not recommended. Such a pattern would be better expressed in a a proper named type.
Version Type is a property of version and version range
The introduction of version type can be made as either a separate property on IU, or as part of version.
If the type is a separate IU property, then the version and range properties would need to be syntactically very relaxed (e.g. be "just strings"), and the appropriate parser, comparator etc. would need to be picked by code based on the IU's version type property.
If the version type is instead part of the version