Skip to content

Commit 17c98f3

Browse files
pbolingpboling
authored
Merge pull request #7 from oauth-xx/qlty
📝 Improve documentation of Epoch SemVer
2 parents 95cb0d7 + 4b8b121 commit 17c98f3

File tree

6 files changed

+83
-80
lines changed

6 files changed

+83
-80
lines changed

‎.github/workflows/coverage.yml

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,7 @@ jobs:
9898
hide_complexity: true
9999
indicators: true
100100
output: both
101-
thresholds: '69 80'
101+
thresholds: '100 100'
102102
continue-on-error: ${{ matrix.experimental != 'false' }}
103103

104104
- name: Add Coverage PR Comment
@@ -109,13 +109,22 @@ jobs:
109109
path: code-coverage-results.md
110110
continue-on-error: ${{ matrix.experimental != 'false' }}
111111

112-
- name: Coveralls
112+
- name: Upload coverage to Coveralls
113113
uses: coverallsapp/github-action@master
114114
with:
115115
github-token: ${{ secrets.GITHUB_TOKEN }}
116116
continue-on-error: ${{ matrix.experimental != 'false' }}
117117

118-
- name: Upload results to Codecov
118+
- name: Upload coverage to QLTY
119+
uses: qltysh/qlty-action/coverage@main
120+
with:
121+
coverage-token: ${{secrets.QLTY_COVERAGE_TOKEN}}
122+
files: coverage/.resultset.json
123+
continue-on-error: ${{ matrix.experimental != 'false' }}
124+
125+
- name: Upload coverage to CodeCov
119126
uses: codecov/codecov-action@v5
120127
with:
128+
fail_ci_if_error: true # optional (default = false)
121129
token: ${{ secrets.CODECOV_TOKEN }}
130+
verbose: true # optional (default = false)

‎.github/workflows/current.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@ jobs:
5454
rubygems: default
5555
bundler: default
5656

57-
# jruby-9.4 (targets Ruby 3.1 compatibility)
57+
# jruby-10.0 (targets Ruby 3.4 compatibility)
5858
- ruby: "jruby"
5959
appraisal: "current"
6060
exec_cmd: "rake spec"

‎.github/workflows/hoary.yml

Lines changed: 0 additions & 62 deletions
This file was deleted.

‎Appraisals

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,12 @@ appraise "ruby-3-3" do
7272
remove_gem "appraisal" # only present because it must be in the gemfile because we target a git branch
7373
end
7474

75+
appraise "ruby-3-4" do
76+
gem "mutex_m", "~> 0.2"
77+
gem "stringio", "~> 3.0"
78+
remove_gem "appraisal" # only present because it must be in the gemfile because we target a git branch
79+
end
80+
7581
# Only run security audit on latest Ruby version
7682
appraise "audit" do
7783
gem "mutex_m", "~> 0.2"

‎README.md

Lines changed: 56 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ This gem has a very niche purpose, which is:
3939
3. allowing 100% test coverage of Ruby code, including the `Version` module.
4040

4141
As proof in the pudding, this gem achieves 100% test coverage for lines and branches,
42-
all 77 and 2 of them, respectively; coverage enabled in part by patterns from this library.
42+
all 117 and 4 of them, respectively; coverage enabled in part by patterns from this library.
4343
You can make it happen for your library too!
4444

4545
If this isn't **precisely** your use case you may be better off looking at
@@ -70,10 +70,10 @@ This gem has no runtime dependencies.
7070

7171
| Tokens to Remember | [![Gem name][⛳️name-img]][⛳️gem-name] [![Gem namespace][⛳️namespace-img]][⛳️gem-namespace] |
7272
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
73-
| Works with JRuby | [![JRuby 9.1 Compat][💎jruby-9.1i]][🚎10-j-wf] [![JRuby 9.2 Compat][💎jruby-9.2i]][🚎10-j-wf] [![JRuby 9.3 Compat][💎jruby-9.3i]][🚎10-j-wf] [![JRuby 9.4 Compat][💎jruby-c-i]][🚎11-c-wf] [![JRuby HEAD Compat][💎jruby-headi]][🚎3-hd-wf] |
73+
| Works with JRuby | [![JRuby 9.1 Compat][💎jruby-9.1i]][🚎10-j-wf] [![JRuby 9.2 Compat][💎jruby-9.2i]][🚎10-j-wf] [![JRuby 9.3 Compat][💎jruby-9.3i]][🚎10-j-wf] [![JRuby 9.4 Compat][💎jruby-9.4i]][🚎10-j-wf] [![JRuby 10.0 Compat][💎jruby-c-i]][🚎11-c-wf] [![JRuby HEAD Compat][💎jruby-headi]][🚎3-hd-wf] |
7474
| Works with Truffle Ruby | [![Truffle Ruby 22.3 Compat][💎truby-22.3i]][🚎9-t-wf] [![Truffle Ruby 23.0 Compat][💎truby-23.0i]][🚎9-t-wf] [![Truffle Ruby 23.1 Compat][💎truby-23.1i]][🚎9-t-wf] [![Truffle Ruby 24.1 Compat][💎truby-c-i]][🚎11-c-wf] [![Truffle Ruby HEAD Compat][💎truby-headi]][🚎3-hd-wf] |
7575
| Works with MRI Ruby 3 | [![Ruby 3.0 Compat][💎ruby-3.0i]][🚎4-lg-wf] [![Ruby 3.1 Compat][💎ruby-3.1i]][🚎6-s-wf] [![Ruby 3.2 Compat][💎ruby-3.2i]][🚎6-s-wf] [![Ruby 3.3 Compat][💎ruby-3.3i]][🚎6-s-wf] [![Ruby 3.4 Compat][💎ruby-c-i]][🚎11-c-wf] [![Ruby HEAD Compat][💎ruby-headi]][🚎3-hd-wf] |
76-
| Works with MRI Ruby 2 | [![Ruby 2.2 Compat][💎ruby-2.2i]][🚎8-ho-wf] [![Ruby 2.3 Compat][💎ruby-2.3i]][🚎1-an-wf] [![Ruby 2.4 Compat][💎ruby-2.4i]][🚎1-an-wf] [![Ruby 2.5 Compat][💎ruby-2.5i]][🚎1-an-wf] [![Ruby 2.6 Compat][💎ruby-2.6i]][🚎7-us-wf] [![Ruby 2.7 Compat][💎ruby-2.7i]][🚎7-us-wf] |
76+
| Works with MRI Ruby 2 | [![Ruby 2.3 Compat][💎ruby-2.3i]][🚎1-an-wf] [![Ruby 2.4 Compat][💎ruby-2.4i]][🚎1-an-wf] [![Ruby 2.5 Compat][💎ruby-2.5i]][🚎1-an-wf] [![Ruby 2.6 Compat][💎ruby-2.6i]][🚎7-us-wf] [![Ruby 2.7 Compat][💎ruby-2.7i]][🚎7-us-wf] |
7777
| Source | [![Source on GitLab.com][📜src-gl-img]][📜src-gl] [![Source on Github.com][📜src-gh-img]][📜src-gh] [![The best SHA: dQw4w9WgXcQ!][🧮kloc-img]][🧮kloc] |
7878
| Documentation | [![Current release on RubyDoc.info][📜docs-cr-rd-img]][🚎yard-current] [![HEAD on RubyDoc.info][📜docs-head-rd-img]][🚎yard-head] [![BDFL Blog][🚂bdfl-blog-img]][🚂bdfl-blog] [![Wiki][📜wiki-img]][📜wiki] |
7979
| Compliance | [![License: MIT][📄license-img]][📄license-ref] [![📄ilo-declaration-img]][📄ilo-declaration] [![Security Policy][🔐security-img]][🔐security] [![CodeQL][🖐codeQL-img]][🖐codeQL] [![Contributor Covenant 2.1][🪇conduct-img]][🪇conduct] [![SemVer 2.0.0][📌semver-img]][📌semver] [![Keep-A-Changelog 1.0.0][📗keep-changelog-img]][📗keep-changelog] |
@@ -162,7 +162,7 @@ end
162162

163163
Your `version.rb` file now abides the Ruby convention of directory / path matching the namespace / class!
164164

165-
## Epoch Usage (Epoch Semantic Versioning)
165+
## Epoch Usage (Epoch Semantic Versioning, as of version 1.1.7)
166166

167167
In the standard `bundle gem my_lib` code you get the following in `lib/my_lib/version.rb`:
168168

@@ -177,11 +177,52 @@ Change it to a nested `Version` namespace (the one implied by the path => namesp
177177
```ruby
178178
module MyLib
179179
module Version
180-
VERSION = "1024.3.8"
180+
VERSION = "0.1.0"
181181
end
182182
end
183183
```
184184

185+
The Epoch and Major versions are derived from the formula:
186+
187+
```
188+
{EPOCH * 1000 + MAJOR}.MINOR.PATCH
189+
```
190+
191+
This will start your library with the following version segments:
192+
193+
* `epoch = 0`
194+
* `major = 0`
195+
* `minor = 1`
196+
* `patch = 0`
197+
* `pre = nil`
198+
199+
And the segments are defined as:
200+
201+
```
202+
EPOCH: Increment when you make significant or groundbreaking changes.
203+
MAJOR: Increment when you make minor incompatible API changes.
204+
MINOR: Increment when you add functionality in a backwards-compatible manner.
205+
PATCH: Increment when you make backwards-compatible bug fixes.
206+
```
207+
208+
Therefore, if you set your version number to:
209+
210+
```ruby
211+
VERSION = "27016.42.86-pre.7"
212+
```
213+
214+
You will get the following version segments:
215+
216+
```
217+
{
218+
epoch: 27,
219+
major: 16,
220+
minor: 42,
221+
patch: 86,
222+
pre: "pre-7",
223+
}
224+
```
225+
185226
Now add the following near the top of the file the manages requiring external libraries.
186227
Using the same example of `bundle gem my_lib`, this would be `lib/my_lib.rb`.
187228

@@ -308,9 +349,11 @@ RSpec.describe(MyLib::Version) do
308349
expect(described_class).to(have_version_as_string)
309350
expect(described_class.to_s).to(be_a(String))
310351
expect(described_class).to(have_major_as_integer)
352+
expect(described_class).to(have_epoch_as_integer)
311353
expect(described_class).to(have_minor_as_integer)
312354
expect(described_class).to(have_patch_as_integer)
313355
expect(described_class).to(have_pre_as_nil_or_string)
356+
# This would be %i[epoch major minor patch pre] for epoch version schemes
314357
expect(described_class.to_h.keys).to(match_array(%i[major minor patch pre]))
315358
expect(described_class.to_a).to(be_a(Array))
316359
end
@@ -364,7 +407,8 @@ This Library adheres to [![Epoch Semantic Versioning][📌semver-img]][📌semve
364407
Violations of this scheme should be reported as bugs.
365408
Specifically, if a minor or patch version is released that breaks backward compatibility,
366409
a new version should be immediately released that restores compatibility.
367-
Breaking changes to the public API, including dropping a supported platform (i.e. minor version of Ruby), will only be introduced with new major versions.
410+
Breaking changes to the public API, including dropping a supported platform (i.e. minor version of Ruby),
411+
will only be introduced with new major versions.
368412
Epoch will only be bumped if there are dramatic changes, and that is not expected to happen ever.
369413

370414
### 📌 Is "Platform Support" part of the public API?
@@ -475,10 +519,10 @@ or one of the others at the head of this README.
475519
[👽oss-helpi]: https://www.codetriage.com/oauth-xx/version_gem/badges/users.svg
476520
[👽version]: https://rubygems.org/gems/version_gem
477521
[👽versioni]: https://img.shields.io/gem/v/version_gem.svg
478-
[🔑cc-mnt]: https://codeclimate.com/github/oauth-xx/version_gem/maintainability
479-
[🔑cc-mnti♻️]: https://api.codeclimate.com/v1/badges/e26c543320ca0d14e871/maintainability
480-
[🔑cc-cov]: https://codeclimate.com/github/oauth-xx/version_gem/test_coverage
481-
[🔑cc-covi♻️]: https://api.codeclimate.com/v1/badges/e26c543320ca0d14e871/test_coverage
522+
[🔑cc-mnt]: https://qlty.sh/gh/rubocop-lts/projects/standard-rubocop-lts
523+
[🔑cc-mnti♻️]: https://qlty.sh/badges/19404e90-9168-451a-8dac-882382cb768d/maintainability.svg
524+
[🔑cc-cov]: https://qlty.sh/gh/rubocop-lts/projects/standard-rubocop-lts
525+
[🔑cc-covi♻️]: https://qlty.sh/badges/19404e90-9168-451a-8dac-882382cb768d/test_coverage.svg
482526
[🔑codecov]: https://codecov.io/gh/oauth-xx/version_gem
483527
[🔑codecovi♻️]: https://codecov.io/gh/oauth-xx/version_gem/branch/main/graph/badge.svg?token=cc6UdZCpAL
484528
[🔑coveralls]: https://coveralls.io/github/oauth-xx/version_gem?branch=main
@@ -501,8 +545,6 @@ or one of the others at the head of this README.
501545
[🚎6-s-wfi]: https://github.com/oauth-xx/version_gem/actions/workflows/supported.yml/badge.svg
502546
[🚎7-us-wf]: https://github.com/oauth-xx/version_gem/actions/workflows/unsupported.yml
503547
[🚎7-us-wfi]: https://github.com/oauth-xx/version_gem/actions/workflows/unsupported.yml/badge.svg
504-
[🚎8-ho-wf]: https://github.com/oauth-xx/version_gem/actions/workflows/hoary.yml
505-
[🚎8-ho-wfi]: https://github.com/oauth-xx/version_gem/actions/workflows/hoary.yml/badge.svg
506548
[🚎9-t-wf]: https://github.com/oauth-xx/version_gem/actions/workflows/truffle.yml
507549
[🚎9-t-wfi]: https://github.com/oauth-xx/version_gem/actions/workflows/truffle.yml/badge.svg
508550
[🚎10-j-wf]: https://github.com/oauth-xx/version_gem/actions/workflows/jruby.yml
@@ -522,7 +564,6 @@ or one of the others at the head of this README.
522564
[🖇buyme-img]: https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20latte&emoji=&slug=pboling&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff
523565
[🖇buyme]: https://www.buymeacoffee.com/pboling
524566
[🖇buyme-small-img]: https://img.shields.io/badge/buy_me_a_coffee-✓-yellow.svg?style=flat
525-
[💎ruby-2.2i]: https://img.shields.io/badge/Ruby-2.2-DF00CA?style=for-the-badge&logo=ruby&logoColor=white
526567
[💎ruby-2.3i]: https://img.shields.io/badge/Ruby-2.3-DF00CA?style=for-the-badge&logo=ruby&logoColor=white
527568
[💎ruby-2.4i]: https://img.shields.io/badge/Ruby-2.4-DF00CA?style=for-the-badge&logo=ruby&logoColor=white
528569
[💎ruby-2.5i]: https://img.shields.io/badge/Ruby-2.5-DF00CA?style=for-the-badge&logo=ruby&logoColor=white
@@ -542,6 +583,7 @@ or one of the others at the head of this README.
542583
[💎jruby-9.1i]: https://img.shields.io/badge/JRuby-9.1-FBE742?style=for-the-badge&logo=ruby&logoColor=red
543584
[💎jruby-9.2i]: https://img.shields.io/badge/JRuby-9.2-FBE742?style=for-the-badge&logo=ruby&logoColor=red
544585
[💎jruby-9.3i]: https://img.shields.io/badge/JRuby-9.3-FBE742?style=for-the-badge&logo=ruby&logoColor=red
586+
[💎jruby-9.4i]: https://img.shields.io/badge/JRuby-9.4-FBE742?style=for-the-badge&logo=ruby&logoColor=red
545587
[💎jruby-c-i]: https://img.shields.io/badge/JRuby-current-FBE742?style=for-the-badge&logo=ruby&logoColor=green
546588
[💎jruby-headi]: https://img.shields.io/badge/JRuby-HEAD-FBE742?style=for-the-badge&logo=ruby&logoColor=blue
547589
[🤝issues]: https://github.com/oauth-xx/version_gem/issues
@@ -563,7 +605,7 @@ or one of the others at the head of this README.
563605
[📗keep-changelog]: https://keepachangelog.com/en/1.0.0/
564606
[📗keep-changelog-img]: https://img.shields.io/badge/keep--a--changelog-1.0.0-FFDD67.svg?style=flat
565607
[🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
566-
[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.077-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
608+
[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.117-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
567609
[🔐security]: SECURITY.md
568610
[🔐security-img]: https://img.shields.io/badge/security-policy-brightgreen.svg?style=flat
569611
[📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

‎gemfiles/ruby_3_4.gemfile

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# This file was generated by Appraisal
2+
3+
source "https://rubygems.org"
4+
5+
gem "mutex_m", "~> 0.2"
6+
gem "stringio", "~> 3.0"
7+
8+
gemspec path: "../"

0 commit comments

Comments
 (0)