mixlib-versioning 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. data/.gitignore +18 -0
  2. data/.yardopts +7 -0
  3. data/CHANGELOG.md +3 -0
  4. data/CONTRIBUTING.md +188 -0
  5. data/Gemfile +9 -0
  6. data/LICENSE +201 -0
  7. data/README.md +364 -0
  8. data/Rakefile +6 -0
  9. data/lib/mixlib/versioning.rb +194 -0
  10. data/lib/mixlib/versioning/exceptions.rb +28 -0
  11. data/lib/mixlib/versioning/format.rb +351 -0
  12. data/lib/mixlib/versioning/format/git_describe.rb +71 -0
  13. data/lib/mixlib/versioning/format/opscode_semver.rb +91 -0
  14. data/lib/mixlib/versioning/format/rubygems.rb +66 -0
  15. data/lib/mixlib/versioning/format/semver.rb +66 -0
  16. data/lib/mixlib/versioning/version.rb +23 -0
  17. data/mixlib-versioning.gemspec +22 -0
  18. data/spec/mixlib/versioning/format/git_describe_spec.rb +178 -0
  19. data/spec/mixlib/versioning/format/opscode_semver_spec.rb +113 -0
  20. data/spec/mixlib/versioning/format/rubygems_spec.rb +142 -0
  21. data/spec/mixlib/versioning/format/semver_spec.rb +107 -0
  22. data/spec/mixlib/versioning/format_spec.rb +69 -0
  23. data/spec/mixlib/versioning/versioning_spec.rb +259 -0
  24. data/spec/spec_helper.rb +43 -0
  25. data/spec/support/shared_examples/basic_semver.rb +42 -0
  26. data/spec/support/shared_examples/behaviors/filterable.rb +66 -0
  27. data/spec/support/shared_examples/behaviors/parses_valid_version_strings.rb +32 -0
  28. data/spec/support/shared_examples/behaviors/rejects_invalid_version_strings.rb +32 -0
  29. data/spec/support/shared_examples/behaviors/serializable.rb +51 -0
  30. data/spec/support/shared_examples/behaviors/sortable.rb +45 -0
  31. data/spec/support/shared_examples/semver.rb +105 -0
  32. metadata +127 -0
@@ -0,0 +1,18 @@
1
+ *.gem
2
+ *.rbc
3
+ .bundle
4
+ .config
5
+ .yardoc
6
+ Gemfile.lock
7
+ InstalledFiles
8
+ _yardoc
9
+ coverage
10
+ doc/
11
+ lib/bundler/man
12
+ pkg
13
+ rdoc
14
+ spec/reports
15
+ test/tmp
16
+ test/version_tmp
17
+ tmp
18
+ bin/
@@ -0,0 +1,7 @@
1
+ --markup=markdown
2
+ --markup-provider=redcarpet
3
+ --readme=README.md
4
+ -
5
+ CHANGELOG.md
6
+ CONTRIBUTING.md
7
+ LICENSE
@@ -0,0 +1,3 @@
1
+ ## 1.0.0
2
+
3
+ * The initial release. Versioning parsing shouldn't suck.
@@ -0,0 +1,188 @@
1
+ [jira-project]: http://tickets.opscode.com/browse/MIXLIB
2
+ [github-project]: http://www.github.com/opscode/mixlib-versioning
3
+ [github-opscode]: http://www.github.com/opscode
4
+ [cla]: https://secure.echosign.com/public/hostedForm?formid=PJIF5694K6L
5
+ [cla-corp]: https://secure.echosign.com/public/hostedForm?formid=PIE6C7AX856
6
+ [wiki-contribute]: http://wiki.opscode.com/display/chef/How+to+Contribute
7
+ [wiki-git]: http://wiki.opscode.com/display/chef/Working+with+Git
8
+ [wiki-code-review]: http://wiki.opscode.com/display/chef/Code+Review
9
+ [list-chef-dev]: http://lists.opscode.com/sympa/info/chef-dev
10
+
11
+ # Contributing to Mixlib::Versioning
12
+
13
+ We are glad you want to contribute to `Mixlib::Versioning`! The first step is
14
+ the desire to improve the project.
15
+
16
+ You can find the answers to additional frequently asked questions
17
+ [on the wiki][wiki-contribute].
18
+
19
+ ## Quick-contribute
20
+
21
+ * Create an account on our [bug tracker][jira-project]
22
+ * Sign our contributor agreement (CLA) [online][cla] (keep reading if you're
23
+ contributing on behalf of your employer)
24
+ * Create a ticket for your change on the [bug tracker][jira-project]. Tickets
25
+ should be filed under the **MIXLIB** project with the component set to
26
+ **mixlib-versioning**.
27
+ * Link to your patch as a rebased git branch or pull request from the ticket
28
+ * Resolve the ticket as fixed
29
+
30
+ We regularly review contributions and will get back to you if we have any
31
+ suggestions or concerns.
32
+
33
+ ## The Apache License and the CLA/CCLA
34
+
35
+ Licensing is very important to open source projects, it helps ensure the
36
+ software continues to be available under the terms that the author desired.
37
+ This project uses the Apache 2.0 license to strike a balance between open
38
+ contribution and allowing you to use the software however you would like to.
39
+
40
+ The license tells you what rights you have that are provided by the copyright
41
+ holder. It is important that the contributor fully understands what rights they
42
+ are licensing and agrees to them. Sometimes the copyright holder isn't the
43
+ contributor, most often when the contributor is doing work for a company.
44
+
45
+ To make a good faith effort to ensure these criteria are met, Opscode requires
46
+ a Contributor License Agreement (CLA) or a Corporate Contributor License
47
+ Agreement (CCLA) for all contributions. This is without exception due to some
48
+ matters not being related to copyright and to avoid having to continually check
49
+ with our lawyers about small patches.
50
+
51
+ It only takes a few minutes to complete a CLA, and you retain the copyright to
52
+ your contribution.
53
+
54
+ You can complete our contributor agreement (CLA) [online][cla]. If you're
55
+ contributing on behalf of your employer, have your employer fill out our
56
+ [Corporate CLA][cla-corp] instead.
57
+
58
+ ## Ticket Tracker (JIRA)
59
+
60
+ The [ticket tracker][jira-project] is the most important documentation for the
61
+ code base. It provides significant historical information, such as:
62
+
63
+ * Which release a bug fix is included in
64
+ * Discussion regarding the design and merits of features
65
+ * Error output to aid in finding similar bugs
66
+
67
+ Each ticket should aim to fix one bug or add one feature.
68
+
69
+ ## Using git
70
+
71
+ You can get a quick copy of this project's repository by running:
72
+
73
+ ```shell
74
+ git clone git://github.com/opscode/mixlib-versioning.git
75
+ ```
76
+
77
+ For collaboration purposes, it is best if you create a Github account and fork
78
+ the repository to your own account. Once you do this you will be able to push
79
+ your changes to your Github repository for others to see and use.
80
+
81
+ ### Branches and Commits
82
+
83
+ You should submit your patch as a git branch named after the ticket, such as
84
+ MIXLIB-1337. This is called a _topic branch_ and allows users to associate a
85
+ branch of code with the ticket.
86
+
87
+ It is a best practice to have your commit message have a _summary line_ that
88
+ includes the ticket number, followed by an empty line and then a brief
89
+ description of the commit. This also helps other contributors understand the
90
+ purpose of changes to the code. Here is an example from the Chef project:
91
+
92
+ CHEF-3435: Create deploy dirs before calling scm_provider
93
+
94
+ The SCM providers have an assertation that requires the deploy directory to
95
+ exist. The deploy provider will create missing directories, we don't converge
96
+ the actions before we call run_action against the SCM provider, so it is not
97
+ yet created. This ensures we run any converge actions waiting before we call
98
+ the SCM provider.
99
+
100
+ Remember that not all users use this library in the same way or on the same
101
+ operating systems as you, so it is helpful to be clear about your use case and
102
+ change so they can understand it even when it doesn't apply to them.
103
+
104
+ ### Github and Pull Requests
105
+
106
+ All of Opscode's open source projects are available on [Github][github-opscode].
107
+
108
+ We don't require you to use Github, and we will even take patch diffs attached
109
+ to tickets on the tracker. However Github has a lot of convenient features,
110
+ such as being able to see a diff of changes between a pull request and the main
111
+ repository quickly without downloading the branch.
112
+
113
+ If you do choose to use a pull request, please provide a link to the pull
114
+ request from the ticket __and__ a link to the ticket from the pull request.
115
+ Because pull requests only have two states, open and closed, we can't easily
116
+ filter pull requests that are waiting for a reply from the author for various
117
+ reasons.
118
+
119
+ ### More information
120
+
121
+ Additional help with git is available on the [Working with Git][wiki-git] wiki
122
+ page.
123
+
124
+ ## Functional and Unit Tests
125
+
126
+ There are rspec unit tests in the 'spec' directory. If you don't have rspec
127
+ already installed, you can use the 'bundler' gem to help you get the necessary
128
+ prerequisites by running `sudo gem install bundler` and then `bundle install`
129
+ from the project root. You can run the project's spec tests by running
130
+ `rspec spec/*` or `rake spec` from the root directory of the this repository.
131
+
132
+ It is good to run the tests once on your system before you get started to
133
+ ensure they all pass so you have a valid baseline. After you write your patch,
134
+ run the tests again to see if they all pass.
135
+
136
+ If any don't pass, investigate them before submitting your patch.
137
+
138
+ These tests don't modify your system, and sometimes tests fail because a
139
+ command that would be run has changed because of your patch. This should be a
140
+ simple fix. Other times the failure can show you that an important feature no
141
+ longer works because of your change.
142
+
143
+ Any new feature should have unit tests included with the patch with good code
144
+ coverage to help protect it from future changes. Similarly, patches that fix a
145
+ bug or regression should have a _regression test_. Simply put, this is a test
146
+ that would fail without your patch but passes with it. The goal is to ensure
147
+ this bug doesn't regress in the future. Consider a regular expression that
148
+ doesn't match a certain pattern that it should, so you provide a patch and a
149
+ test to ensure that the part of the code that uses this regular expression
150
+ works as expected. Later another contributor may modify this regular expression
151
+ in a way that breaks your use cases. The test you wrote will fail, signalling
152
+ to them to research your ticket and use case and accounting for it.
153
+
154
+ ## Code Review
155
+
156
+ Opscode regularly reviews code contributions and provides suggestions for
157
+ improvement in the code itself or the implementation.
158
+
159
+ We find contributions by searching the ticket tracker for _resolved_ tickets
160
+ with a status of _fixed_. If we have feedback we will reopen the ticket and you
161
+ should resolve it again when you've made the changes or have a response to our
162
+ feedback. When we believe the patch is ready to be merged, we update the status
163
+ to _Fix Reviewed_.
164
+
165
+ Depending on the project, these tickets are then merged within a week or two,
166
+ depending on the current release cycle. At this point the ticket status will be
167
+ updated to _Fix Committed_ or _Closed_.
168
+
169
+ Please see the [Code Review][wiki-code-review] page on the wiki for additional
170
+ information.
171
+
172
+ ## Release Cycle
173
+
174
+ The versioning for the this project is X.Y.Z and follows
175
+ [SemVer 2.0.0-rc.1 conventions](http://semver.org/):
176
+
177
+ * X is a major release, which may not be fully compatible with prior major releases
178
+ * Y is a minor release, which adds both new features and bug fixes
179
+ * Z is a patch release, which adds just bug fixes
180
+
181
+ There are usually beta releases and release candidates (RC) of major and minor
182
+ releases announced on the [chef-dev mailing list][list-chef-dev]. Once an
183
+ RC is released, we wait at least three days to allow for testing for regressions
184
+ before the final release. If a blocking regression is found then another RC is
185
+ made containing the fix and the timer is reset.
186
+
187
+ Once the official release is made, the release notes are available on the
188
+ [Opscode blog](http://www.opscode.com/blog).
data/Gemfile ADDED
@@ -0,0 +1,9 @@
1
+ source 'https://rubygems.org'
2
+
3
+ gemspec
4
+
5
+ group :docs do
6
+ gem "yard", "~> 0.8.5"
7
+ gem "redcarpet", "~> 2.2.2"
8
+ gem "github-markup", "~> 0.7.5"
9
+ end
data/LICENSE ADDED
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
@@ -0,0 +1,364 @@
1
+ # Mixlib::Versioning
2
+
3
+ Versioning is hard! `mixlib-versioning` is a general Ruby library that allows
4
+ you to parse, compare and manipulate version numbers in multiple formats.
5
+ Currently the following version string formats are supported:
6
+
7
+ ### SemVer 2.0.0-rc.1
8
+
9
+ **Specification:**
10
+
11
+ http://semver.org/
12
+
13
+ **Supported Formats:**
14
+
15
+ ```text
16
+ MAJOR.MINOR.PATCH
17
+ MAJOR.MINOR.PATCH-PRERELEASE
18
+ MAJOR.MINOR.PATCH-PRERELEASE+BUILD
19
+ ```
20
+
21
+ Not much to say here except: *YUNO USE SEMVER!* The specification is focused and
22
+ brief, do yourself a favor and go read it.
23
+
24
+ ### Opscode SemVer
25
+
26
+ **Supported Formats:**
27
+
28
+ ```text
29
+ MAJOR.MINOR.PATCH
30
+ MAJOR.MINOR.PATCH-alpha.INDEX
31
+ MAJOR.MINOR.PATCH-beta.INDEX
32
+ MAJOR.MINOR.PATCH-rc.INDEX
33
+ MAJOR.MINOR.PATCH-alpha.INDEX+YYYYMMDDHHMMSS
34
+ MAJOR.MINOR.PATCH-beta.INDEX+YYYYMMDDHHMMSS
35
+ MAJOR.MINOR.PATCH-rc.INDEX+YYYYMMDDHHMMSS
36
+ MAJOR.MINOR.PATCH-alpha.INDEX+YYYYMMDDHHMMSS.git.COMMITS_SINCE.SHA1
37
+ MAJOR.MINOR.PATCH-beta.INDEX+YYYYMMDDHHMMSS.git.COMMITS_SINCE.SHA1
38
+ MAJOR.MINOR.PATCH-rc.INDEX+YYYYMMDDHHMMSS.git.COMMITS_SINCE.SHA1
39
+ ```
40
+
41
+ All the fun of regular SemVer with some extra limits around what constitutes a
42
+ valid pre-release or build version string.
43
+
44
+ Valid prerelease version strings use the format: `PRERELEASE_STAGE.INDEX`.
45
+ Valid prerelease stages include: `alpha`, `beta` and `rc`.
46
+
47
+ All of the following are acceptable Opscode SemVer pre-release versions:
48
+
49
+ ```text
50
+ 11.0.8-alpha.0
51
+ 11.0.8-alpha.1
52
+ 11.0.8-beta.7
53
+ 11.0.8-beta.8
54
+ 11.0.8-rc.1
55
+ 11.0.8-rc.2
56
+ ```
57
+
58
+ Build version strings are limited to timestamps (`YYYYMMDDHHMMSS`), git
59
+ describe strings (`git.COMMITS_SINCE.SHA1`) or a combination of the two
60
+ (`YYYYMMDDHHMMSS.git.COMMITS_SINCE.SHA1`).
61
+
62
+ All of the following are acceptable Opscode build versions:
63
+
64
+ ```text
65
+ 11.0.8+20130308110833
66
+ 11.0.8+git.2.g94a1dde
67
+ 11.0.8+20130308110833.git.2.94a1dde
68
+ ```
69
+
70
+ And as is true with regular SemVer you can mix pre-release and build versions:
71
+
72
+ ```text
73
+ 11.0.8-rc.1+20130308110833
74
+ 11.0.8-alpha.2+20130308110833.git.2.94a1dde
75
+ ```
76
+
77
+ ### Rubygems
78
+
79
+ **specification:**
80
+
81
+ http://docs.rubygems.org/read/chapter/7
82
+
83
+ http://guides.rubygems.org/patterns/
84
+
85
+ **Supported Formats:**
86
+
87
+ ```text
88
+ MAJOR.MINOR.PATCH
89
+ MAJOR.MINOR.PATCH.PRERELEASE
90
+ ```
91
+
92
+ Rubygems is *almost* SemVer compliant but it separates the main version from
93
+ the pre-release version using a "dot". It also does not have the notion of a
94
+ build version like SemVer.
95
+
96
+ Examples of valid Rubygems version strings:
97
+
98
+ ```text
99
+ 10.1.1
100
+ 10.1.1
101
+ 10.1.1.alpha.1
102
+ 10.1.1.beta.1
103
+ 10.1.1.rc.0
104
+ ```
105
+
106
+ ### Git Describe
107
+
108
+ **Specification:**
109
+
110
+ http://git-scm.com/docs/git-describe
111
+
112
+ **Supported Formats:**
113
+
114
+ ```text
115
+ MAJOR.MINOR.PATCH-COMMITS_SINCE-gGIT_SHA1
116
+ MAJOR.MINOR.PATCH-COMMITS_SINCE-gGIT_SHA1-ITERATION
117
+ MAJOR.MINOR.PATCH-PRERELEASE-COMMITS_SINCE-gGIT_SHA1
118
+ MAJOR.MINOR.PATCH-PRERELEASE-COMMITS_SINCE-gGIT_SHA1-ITERATION
119
+ ```
120
+
121
+ Examples of valid Git Describe version strings:
122
+
123
+ ```text
124
+ 10.16.2-49-g21353f0-1
125
+ 10.16.2.rc.1-49-g21353f0-1
126
+ 11.0.0-alpha-10-g642ffed
127
+ 11.0.0-alpha.1-1-gcea071e
128
+ ```
129
+
130
+ ## Installation
131
+
132
+ Add this line to your application's Gemfile:
133
+
134
+ gem 'mixlib-versioning'
135
+
136
+ And then execute:
137
+
138
+ $ bundle
139
+
140
+ Or install it yourself as:
141
+
142
+ $ gem install mixlib-semver
143
+
144
+ ## Usage
145
+
146
+ ### Basic Version String Parsing
147
+
148
+ ```irb
149
+ >> require 'mixlib/versioning'
150
+ true
151
+ >> v1 = Mixlib::Versioning.parse("11.0.3")
152
+ #<Mixlib::Versioning::Format::OpscodeSemVer:0x3fecddccff4c @major=11, @minor=0, @patch=3, @prerelease=nil, @build=nil, @input="11.0.3">
153
+ >> v1.release?
154
+ true
155
+ >> v1.prerelease?
156
+ false
157
+ >> v1.build?
158
+ false
159
+ >> v1.prerelease_build?
160
+ false
161
+ >> v2 = Mixlib::Versioning.parse("11.0.0-beta.1")
162
+ #<Mixlib::Versioning::Format::OpscodeSemVer:0x3fecde44f420 @major=11, @minor=0, @patch=0, @prerelease="beta.1", @build=nil, @input="11.0.0-beta.1">
163
+ >> v2.release?
164
+ false
165
+ >> v2.prerelease?
166
+ true
167
+ >> v2.build?
168
+ false
169
+ >> v2.prerelease_build?
170
+ false
171
+ >> v3 = Mixlib::Versioning.parse("11.0.6+20130216075209")
172
+ #<Mixlib::Versioning::Format::OpscodeSemVer:0x3fecde49568c @major=11, @minor=0, @patch=6, @prerelease=nil, @build="20130216075209", @input="11.0.6+20130216075209">
173
+ >> v3.release?
174
+ false
175
+ >> v3.prerelease?
176
+ false
177
+ >> v3.build?
178
+ true
179
+ >> v3.prerelease_build?
180
+ false
181
+ >> v4 = Mixlib::Versioning.parse("11.0.8-rc.1+20130302083119")
182
+ #<Mixlib::Versioning::Format::OpscodeSemVer:0x3fecde4dad7c @major=11, @minor=0, @patch=8, @prerelease="rc.1", @build="20130302083119", @input="11.0.8-rc.1+20130302083119">
183
+ >> v4.release?
184
+ false
185
+ >> v4.prerelease?
186
+ false
187
+ >> v4.build?
188
+ true
189
+ >> v4.prerelease_build?
190
+ true
191
+ >> v5 = Mixlib::Versioning.parse("10.16.8.alpha.0")
192
+ #<Mixlib::Versioning::Format::Rubygems:0x3fecde532bd0 @major=10, @minor=16, @patch=8, @prerelease="alpha.0", @iteration=0, @input="10.16.8.alpha.0">
193
+ >> v5.major
194
+ 10
195
+ >> v5.minor
196
+ 16
197
+ >> v5.patch
198
+ 8
199
+ >> v5.prerelease
200
+ "alpha.0"
201
+ >> v5.release?
202
+ false
203
+ >> v5.prerelease?
204
+ true
205
+ ```
206
+
207
+ ### Version Comparison and Sorting
208
+
209
+ ```irb
210
+ >> require 'mixlib/versioning'
211
+ true
212
+ >> v1 = Mixlib::Versioning.parse("11.0.0-beta.1")
213
+ #<Mixlib::Versioning::Format::OpscodeSemVer:0x3ff009cd54e0 @major=11, @minor=0, @patch=0, @prerelease="beta.1", @build=nil, @input="11.0.0-beta.1">
214
+ >> v2 = Mixlib::Versioning.parse("11.0.0-rc.1")
215
+ #<Mixlib::Versioning::Format::OpscodeSemVer:0x3ff009d07260 @major=11, @minor=0, @patch=0, @prerelease="rc.1", @build=nil, @input="11.0.0-rc.1">
216
+ >> v3 = Mixlib::Versioning.parse("11.0.0")
217
+ #<Mixlib::Versioning::Format::OpscodeSemVer:0x3ff009d0d3cc @major=11, @minor=0, @patch=0, @prerelease=nil, @build=nil, @input="11.0.0">
218
+ >> v1 < v2
219
+ true
220
+ >> v3 < v1
221
+ false
222
+ >> v1 == v2
223
+ false
224
+ >> [v3, v1, v2].sort
225
+ [
226
+ [0] #<Mixlib::Versioning::Format::OpscodeSemVer:0x3ff009cd54e0 @major=11, @minor=0, @patch=0, @prerelease="beta.1", @build=nil, @input="11.0.0-beta.1">,
227
+ [1] #<Mixlib::Versioning::Format::OpscodeSemVer:0x3ff009d07260 @major=11, @minor=0, @patch=0, @prerelease="rc.1", @build=nil, @input="11.0.0-rc.1">,
228
+ [2] #<Mixlib::Versioning::Format::OpscodeSemVer:0x3ff009d0d3cc @major=11, @minor=0, @patch=0, @prerelease=nil, @build=nil, @input="11.0.0">
229
+ ]
230
+ >> [v3, v1, v2].map{|v| v.to_s}.sort
231
+ [
232
+ [0] "11.0.0",
233
+ [1] "11.0.0-beta.1",
234
+ [2] "11.0.0-rc.1"
235
+ ]
236
+ ```
237
+
238
+ ### Target Version Selection
239
+
240
+ Basic usage:
241
+
242
+ ```ruby
243
+ >> require 'mixlib/versioning'
244
+ true
245
+ >> all_versions = %w{
246
+ 11.0.0-alpha.1
247
+ 11.0.0-alpha.1-1-gcea071e
248
+ 11.0.0-alpha.3+20130103213604.git.11.3fe70b5
249
+ 11.0.0-alpha.3+20130129075201.git.38.3332a80
250
+ 11.0.0-alpha.3+20130130075202.git.38.3332a80
251
+ 11.0.0-beta.0+20130131044557
252
+ 11.0.0-beta.1+20130201023059.git.5.c9d3320
253
+ 11.0.0-beta.2+20130201035911
254
+ 11.0.0-beta.2+20130201191308.git.4.9aa4cb2
255
+ 11.0.0-rc.1
256
+ 11.0.0+20130204053034.git.1.1802643
257
+ 11.0.4
258
+ 11.0.6-alpha.0+20130208045134.git.2.298c401
259
+ 11.0.6-alpha.0+20130214075209.git.11.5d72e1c
260
+ 11.0.6-alpha.0+20130215075208.git.11.5d72e1c
261
+ 11.0.6-rc.0
262
+ 11.0.6
263
+ 11.0.6+20130216075209
264
+ 11.0.6+20130221075213
265
+ 11.0.8-rc.1
266
+ 11.0.8-rc.1+20130302083119
267
+ 11.0.8-rc.1+20130304083118
268
+ 11.0.8-rc.1+20130305083118
269
+ 11.0.8-rc.1+20130305195925.git.2.94a1dde
270
+ 11.0.8-rc.1+20130306083036.git.2.94a1dde
271
+ 11.0.8-rc.1+20130319083111.git.6.dc8613e
272
+ };''
273
+ ""
274
+ >> Mixlib::Versioning.find_target_version(all_versions, "11.0.6", false, false)
275
+ #<Mixlib::Versioning::Format::OpscodeSemVer:0x3ffdc91364a4 @major=11, @minor=0, @patch=6, @prerelease=nil, @build=nil, @input="11.0.6">
276
+ >> target = Mixlib::Versioning.find_target_version(all_versions, "11.0.6", false, false)
277
+ #<Mixlib::Versioning::Format::OpscodeSemVer:0x3ffdc91364a4 @major=11, @minor=0, @patch=6, @prerelease=nil, @build=nil, @input="11.0.6">
278
+ >> target.to_s
279
+ "11.0.6"
280
+ ```
281
+
282
+ Select latest release version:
283
+
284
+ ```irb
285
+ >> target = Mixlib::Versioning.find_target_version(all_versions, nil, false, false)
286
+ #<Mixlib::Versioning::Format::OpscodeSemVer:0x3ffdc91364a4 @major=11, @minor=0, @patch=6, @prerelease=nil, @build=nil, @input="11.0.6">
287
+ >> target.to_s
288
+ "11.0.6"
289
+ ```
290
+
291
+ Select latest pre-release version:
292
+
293
+ ```irb
294
+ >> target = Mixlib::Versioning.find_target_version(all_versions, nil, true, false)
295
+ #<Mixlib::Versioning::Format::OpscodeSemVer:0x3ffdc9139078 @major=11, @minor=0, @patch=8, @prerelease="rc.1", @build=nil, @input="11.0.8-rc.1">
296
+ >> target.to_s
297
+ "11.0.8-rc.1"
298
+ ```
299
+
300
+ Select the latest release build version:
301
+
302
+ ```irb
303
+ >> target = Mixlib::Versioning.find_target_version(all_versions, nil, false, true)
304
+ #<Mixlib::Versioning::Format::OpscodeSemVer:0x3ffdc91f0bb0 @major=11, @minor=0, @patch=6, @prerelease=nil, @build="20130221075213", @input="11.0.6+20130221075213">
305
+ >> target.to_s
306
+ "11.0.6+20130221075213"
307
+ ```
308
+
309
+ Select the latest pre-release build version:
310
+
311
+ ```irb
312
+ >> target = Mixlib::Versioning.find_target_version(all_versions, nil, true, true)
313
+ #<Mixlib::Versioning::Format::OpscodeSemVer:0x3ffdc91f154c @major=11, @minor=0, @patch=8, @prerelease="rc.1", @build="20130319083111.git.6.dc8613e", @input="11.0.8-rc.1+20130319083111.git.6.dc8613e">
314
+ >> target.to_s
315
+ "11.0.8-rc.1+20130319083111.git.6.dc8613e"
316
+ ```
317
+
318
+ ## How to Run the Tests
319
+
320
+ To run the unit tests, run
321
+
322
+ ```
323
+ rake spec
324
+ ```
325
+
326
+ ## Documentation
327
+
328
+ All documentation is written using YARD. You can generate a by running:
329
+
330
+ ```
331
+ rake yard
332
+ ```
333
+
334
+ ## Contributing
335
+
336
+ See the [CONTRIBUTING](CONTRIBUTING.md) document.
337
+
338
+ ## Reporting Bugs
339
+
340
+ You can search for known issues in [Opscode's bug tracker][jira]. Tickets
341
+ should be filed under the **MIXLIB** project with the component set to
342
+ **"mixlib-versioning"**.
343
+
344
+ ## License
345
+
346
+ | | |
347
+ |:---------------------|:-----------------------------------------|
348
+ | **Author:** | Seth Chisamore (schisamo@opscode.com)
349
+ | **Copyright:** | Copyright (c) 2013 Opscode, Inc.
350
+ | **License:** | Apache License, Version 2.0
351
+
352
+ Licensed under the Apache License, Version 2.0 (the "License");
353
+ you may not use this file except in compliance with the License.
354
+ You may obtain a copy of the License at
355
+
356
+ http://www.apache.org/licenses/LICENSE-2.0
357
+
358
+ Unless required by applicable law or agreed to in writing, software
359
+ distributed under the License is distributed on an "AS IS" BASIS,
360
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
361
+ See the License for the specific language governing permissions and
362
+ limitations under the License.
363
+
364
+ [jira]: http://tickets.opscode.com/browse/MIXLIB