|
1 | 1 | %a{annotate:rdoc:skip} |
2 | 2 | module Gem |
3 | | - # <!-- rdoc-file=lib/rubygems/version.rb --> |
4 | | - # The Version class processes string versions into comparable values. A version |
5 | | - # string should normally be a series of numbers separated by periods. Each part |
6 | | - # (digits separated by periods) is considered its own number, and these are used |
7 | | - # for sorting. So for instance, 3.10 sorts higher than 3.2 because ten is |
8 | | - # greater than two. |
9 | | - # |
10 | | - # If any part contains letters (currently only a-z are supported) then that |
11 | | - # version is considered prerelease. Versions with a prerelease part in the Nth |
12 | | - # part sort less than versions with N-1 parts. Prerelease parts are sorted |
13 | | - # alphabetically using the normal Ruby string sorting rules. If a prerelease |
14 | | - # part contains both letters and numbers, it will be broken into multiple parts |
15 | | - # to provide expected sort behavior (1.0.a10 becomes 1.0.a.10, and is greater |
16 | | - # than 1.0.a9). |
17 | | - # |
18 | | - # Prereleases sort between real releases (newest to oldest): |
19 | | - # |
20 | | - # 1. 1.0 |
21 | | - # 2. 1.0.b1 |
22 | | - # 3. 1.0.a.2 |
23 | | - # 4. 0.9 |
24 | | - # |
25 | | - # If you want to specify a version restriction that includes both prereleases |
26 | | - # and regular releases of the 1.x series this is the best way: |
27 | | - # |
28 | | - # s.add_dependency 'example', '>= 1.0.0.a', '< 2.0.0' |
29 | | - # |
30 | | - # ## How Software Changes |
31 | | - # |
32 | | - # Users expect to be able to specify a version constraint that gives them some |
33 | | - # reasonable expectation that new versions of a library will work with their |
34 | | - # software if the version constraint is true, and not work with their software |
35 | | - # if the version constraint is false. In other words, the perfect system will |
36 | | - # accept all compatible versions of the library and reject all incompatible |
37 | | - # versions. |
38 | | - # |
39 | | - # Libraries change in 3 ways (well, more than 3, but stay focused here!). |
40 | | - # |
41 | | - # 1. The change may be an implementation detail only and have no effect on the |
42 | | - # client software. |
43 | | - # 2. The change may add new features, but do so in a way that client software |
44 | | - # written to an earlier version is still compatible. |
45 | | - # 3. The change may change the public interface of the library in such a way |
46 | | - # that old software is no longer compatible. |
47 | | - # |
48 | | - # Some examples are appropriate at this point. Suppose I have a Stack class |
49 | | - # that supports a `push` and a `pop` method. |
50 | | - # |
51 | | - # ### Examples of Category 1 changes: |
52 | | - # |
53 | | - # * Switch from an array based implementation to a linked-list based |
54 | | - # implementation. |
55 | | - # * Provide an automatic (and transparent) backing store for large stacks. |
56 | | - # |
57 | | - # ### Examples of Category 2 changes might be: |
58 | | - # |
59 | | - # * Add a `depth` method to return the current depth of the stack. |
60 | | - # * Add a `top` method that returns the current top of stack (without changing |
61 | | - # the stack). |
62 | | - # * Change `push` so that it returns the item pushed (previously it had no |
63 | | - # usable return value). |
64 | | - # |
65 | | - # ### Examples of Category 3 changes might be: |
66 | | - # |
67 | | - # * Changes `pop` so that it no longer returns a value (you must use `top` to |
68 | | - # get the top of the stack). |
69 | | - # * Rename the methods to `push_item` and `pop_item`. |
70 | | - # |
71 | | - # ## RubyGems Rational Versioning |
72 | | - # |
73 | | - # * Versions shall be represented by three non-negative integers, separated by |
74 | | - # periods (e.g. 3.1.4). The first integers is the "major" version number, |
75 | | - # the second integer is the "minor" version number, and the third integer is |
76 | | - # the "build" number. |
77 | | - # |
78 | | - # * A category 1 change (implementation detail) will increment the build |
79 | | - # number. |
80 | | - # |
81 | | - # * A category 2 change (backwards compatible) will increment the minor |
82 | | - # version number and reset the build number. |
83 | | - # |
84 | | - # * A category 3 change (incompatible) will increment the major build number |
85 | | - # and reset the minor and build numbers. |
86 | | - # |
87 | | - # * Any "public" release of a gem should have a different version. Normally |
88 | | - # that means incrementing the build number. This means a developer can |
89 | | - # generate builds all day long, but as soon as they make a public release, |
90 | | - # the version must be updated. |
91 | | - # |
92 | | - # ### Examples |
93 | | - # |
94 | | - # Let's work through a project lifecycle using our Stack example from above. |
95 | | - # |
96 | | - # Version 0.0.1 |
97 | | - # : The initial Stack class is release. |
98 | | - # |
99 | | - # Version 0.0.2 |
100 | | - # : Switched to a linked=list implementation because it is cooler. |
101 | | - # |
102 | | - # Version 0.1.0 |
103 | | - # : Added a `depth` method. |
104 | | - # |
105 | | - # Version 1.0.0 |
106 | | - # : Added `top` and made `pop` return nil (`pop` used to return the old top |
107 | | - # item). |
108 | | - # |
109 | | - # Version 1.1.0 |
110 | | - # : `push` now returns the value pushed (it used it return nil). |
111 | | - # |
112 | | - # Version 1.1.1 |
113 | | - # : Fixed a bug in the linked list implementation. |
114 | | - # |
115 | | - # Version 1.1.2 |
116 | | - # : Fixed a bug introduced in the last fix. |
117 | | - # |
118 | | - # |
119 | | - # Client A needs a stack with basic push/pop capability. They write to the |
120 | | - # original interface (no `top`), so their version constraint looks like: |
121 | | - # |
122 | | - # gem 'stack', '>= 0.0' |
123 | | - # |
124 | | - # Essentially, any version is OK with Client A. An incompatible change to the |
125 | | - # library will cause them grief, but they are willing to take the chance (we |
126 | | - # call Client A optimistic). |
127 | | - # |
128 | | - # Client B is just like Client A except for two things: (1) They use the `depth` |
129 | | - # method and (2) they are worried about future incompatibilities, so they write |
130 | | - # their version constraint like this: |
131 | | - # |
132 | | - # gem 'stack', '~> 0.1' |
133 | | - # |
134 | | - # The `depth` method was introduced in version 0.1.0, so that version or |
135 | | - # anything later is fine, as long as the version stays below version 1.0 where |
136 | | - # incompatibilities are introduced. We call Client B pessimistic because they |
137 | | - # are worried about incompatible future changes (it is OK to be pessimistic!). |
138 | | - # |
139 | | - # ## Preventing Version Catastrophe: |
140 | | - # |
141 | | - # From: |
142 | | - # https://www.zenspider.com/ruby/2008/10/rubygems-how-to-preventing-catastrophe. |
143 | | - # html |
144 | | - # |
145 | | - # Let's say you're depending on the fnord gem version 2.y.z. If you specify your |
146 | | - # dependency as ">= 2.0.0" then, you're good, right? What happens if fnord 3.0 |
147 | | - # comes out and it isn't backwards compatible with 2.y.z? Your stuff will break |
148 | | - # as a result of using ">=". The better route is to specify your dependency with |
149 | | - # an "approximate" version specifier ("~>"). They're a tad confusing, so here is |
150 | | - # how the dependency specifiers work: |
151 | | - # |
152 | | - # Specification From ... To (exclusive) |
153 | | - # ">= 3.0" 3.0 ... ∞ |
154 | | - # "~> 3.0" 3.0 ... 4.0 |
155 | | - # "~> 3.0.0" 3.0.0 ... 3.1 |
156 | | - # "~> 3.5" 3.5 ... 4.0 |
157 | | - # "~> 3.5.0" 3.5.0 ... 3.6 |
158 | | - # "~> 3" 3.0 ... 4.0 |
159 | | - # |
160 | | - # For the last example, single-digit versions are automatically extended with a |
161 | | - # zero to give a sensible result. |
162 | | - # |
163 | 3 | class Version |
164 | 4 | include Comparable |
165 | 5 |
|
|
0 commit comments