From b4deb42be66013201fe297e56cd923b796a50b4a Mon Sep 17 00:00:00 2001 From: Andrew Janke Date: Thu, 4 Jan 2024 00:49:40 -0500 Subject: [PATCH] deps: relaxed and more precise dependency versions, to support more target environments Allowing a broader range of versions for dependency gems will let a given ronn-ng version work in more environments, particularly distros that have fixed versions of the dependency gems in their packages, and systems running older Ruby versions. Added comments to the gemspec to explain why the version restrictions are there. I left them all open-ended on the upper bound because I'm not aware of any dep versions that break things, and I'll just assume back-compatibility until I know otherwise for specific gems. The nokogiri minimum version is 1.14.3, because that's required for the behavior we want for HTML tag names with ":" in them. See #102. I updated Gemfile.lock instead of removing it, but I no longer know if that's significant or good in deployment. Right now I'm mostly considering it an indication of the exact versions I tested it most heavily with. I don't expect downstream packagers to use or respect Gemfile.lock. --- .ruby-version | 1 - Gemfile.lock | 34 +++++++++++++++++---------------- doc-project/Dependency Notes.md | 21 ++++++++++++++++++++ ronn-ng.gemspec | 30 ++++++++++++++++------------- 4 files changed, 56 insertions(+), 30 deletions(-) delete mode 100644 .ruby-version create mode 100644 doc-project/Dependency Notes.md diff --git a/.ruby-version b/.ruby-version deleted file mode 100644 index 6a81b4c..0000000 --- a/.ruby-version +++ /dev/null @@ -1 +0,0 @@ -2.7.8 diff --git a/Gemfile.lock b/Gemfile.lock index fb45cee..85aa9b1 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -2,15 +2,16 @@ PATH remote: . specs: ronn-ng (0.10.1.pre4) - kramdown (~> 2.4) - kramdown-parser-gfm (~> 1.1) - mustache (~> 1.1) - nokogiri (~> 1.15) + kramdown (>= 2.1) + kramdown-parser-gfm (>= 1.0.1) + mustache (>= 0.7.0) + nokogiri (>= 1.14.3) GEM remote: https://rubygems.org/ specs: ast (2.4.2) + base64 (0.2.0) json (2.7.1) kramdown (2.4.0) rexml @@ -19,7 +20,7 @@ GEM language_server-protocol (3.17.0.3) mini_portile2 (2.8.5) mustache (1.1.1) - mustermann (2.0.2) + mustermann (3.0.0) ruby2_keywords (~> 0.0.1) nokogiri (1.15.5) mini_portile2 (~> 2.8.2) @@ -31,8 +32,9 @@ GEM power_assert (2.0.3) racc (1.7.3) rack (2.2.8) - rack-protection (2.2.4) - rack + rack-protection (3.2.0) + base64 (>= 0.1.0) + rack (~> 2.2, >= 2.2.4) rainbow (3.1.1) rake (13.1.0) regexp_parser (2.8.3) @@ -52,10 +54,10 @@ GEM parser (>= 3.2.1.0) ruby-progressbar (1.13.0) ruby2_keywords (0.0.5) - sinatra (2.2.4) - mustermann (~> 2.0) - rack (~> 2.2) - rack-protection (= 2.2.4) + sinatra (3.2.0) + mustermann (~> 3.0) + rack (~> 2.2, >= 2.2.4) + rack-protection (= 3.2.0) tilt (~> 2.0) test-unit (3.6.1) power_assert @@ -66,12 +68,12 @@ PLATFORMS ruby DEPENDENCIES - rack (~> 2.2, >= 2.2.3) - rake (~> 13.0, >= 13.0.3) + rack (>= 2.2.3) + rake (>= 13.0.3) ronn-ng! - rubocop (~> 1.57) - sinatra (~> 2.2) - test-unit (~> 3.6) + rubocop (>= 1.25.1) + sinatra (>= 2.2.3) + test-unit (>= 3.2.7) BUNDLED WITH 2.1.4 diff --git a/doc-project/Dependency Notes.md b/doc-project/Dependency Notes.md new file mode 100644 index 0000000..59998c4 --- /dev/null +++ b/doc-project/Dependency Notes.md @@ -0,0 +1,21 @@ +# Ronn-NG Dependency Notes + +Ronn-NG tries to allow a wide range of dependency versions in its gemspec, and be strict and even specific about its gem dependencies in deployment and testing scenarios. This will hopefully let users install it as a gem in a wide variety of environments, and let distro packagers fit it in with different fixed versions of packaged dependencies, but be correct-er in testing and deployment in app or package form. + +## Ruby version + +I only develop and test on Ruby 2.6 and newer, and those are the only versions supported. Will probably be requiring >= 2.7 soon as of 2023. + +Chose Ruby 2.6 as the minimum because those are the ones that come with bundler included, and I don't want to bother installing it there. (The default `gem install bundler` doesn't work; a version-specific `gem install bundler -v 2.3.26` might, but use of it tends to break due to bugs in early gem and bundler versions, and I don't want to deal with that.) + +I mostly test on Ruby 2.7 or 3.x, because that's waht to seems to be in common use and distro shipping in 2023. + +## Gem versions + +I'm currently keeping the gem dependency versions in the gemspec as loose as I can, while everything still works (tests pass and I don't notice anything breaking), and keeping the min version high enough to pick up security fixes that I know about (mostly through Dependabot on GitHub). Specific reasons for those versions are noted in comments in the gemspec. + +If you need to install it in an environment that only supplies older gems, edit the gemspec to relax the minimum version, and maybe it'll work? But it will be unsupported. + +### nokogiri + +We require nokogiri >= [1.14.3](https://github.com/sparklemotion/nokogiri/releases/tag/v1.14.3) because earlier versions have undesirable handling of tag names with ":" characters in them (which look like namespaces). I don't know if that's a bug or not; I assume so because it's a material behavior change in a patch version increment. That nokogiri version bumped its vendored libxml2 from 2.10.3 to 2.10.4. See [issue #102 "libxml 2.10+ compatibility for dot. and foo:colon angle-bracket syntax"](https://github.com/apjanke/ronn-ng/issues/102). Earlier libxml2 versions also have security vulnerabilities; that's why the [nokogiri 1.14.3 release notes](https://github.com/sparklemotion/nokogiri/releases/tag/v1.14.3) say they upgraded. diff --git a/ronn-ng.gemspec b/ronn-ng.gemspec index 41965da..a369675 100644 --- a/ronn-ng.gemspec +++ b/ronn-ng.gemspec @@ -1,10 +1,10 @@ Gem::Specification.new do |s| s.name = 'ronn-ng' s.version = '0.10.1.pre4' - # As of 2023-09, ronn-ng targets and is tested on Ruby 2.7 for deployment. May well - # be compatible with earlier versions, but that's not really supported, and users can - # modify this locally if they want to try under older Rubies. - s.required_ruby_version = '>= 2.7' + # As of 2023-09, ronn-ng targets and is tested on Ruby 2.7 for deployment. It'll mostly + # work on lower versions, but in effect requires >= 2.7 because it needs nokogiri + # >= 1.14.3 for correct tag name handling, and that nokogiri requires Ruby 2.7. + s.required_ruby_version = '>= 2.4' s.summary = 'Builds man pages from Markdown' s.description = 'Ronn-NG builds manuals in Unix man page and HTML format from Markdown. Ronn-NG is a modern, maintained fork of the original Ronn.' @@ -61,15 +61,19 @@ Gem::Specification.new do |s| s.test_files = s.files.select { |path| path =~ /^test\/.*_test.rb/ } s.extra_rdoc_files = %w[LICENSE.txt AUTHORS] - s.add_dependency 'kramdown', '~> 2.4' - s.add_dependency 'kramdown-parser-gfm', '~> 1.1' - s.add_dependency 'mustache', '~> 1.1' - s.add_dependency 'nokogiri', '~> 1.15' - s.add_development_dependency 'rack', '~> 2.2', '>= 2.2.3' - s.add_development_dependency 'rake', '~> 13.0', '>= 13.0.3' - s.add_development_dependency 'rubocop', '~> 1.57' - s.add_development_dependency 'sinatra', '~> 2.2' - s.add_development_dependency 'test-unit', '~> 3.6' + s.add_dependency 'kramdown', '>= 2.1' + s.add_dependency 'kramdown-parser-gfm', '>= 1.0.1' + s.add_dependency 'mustache', '>= 0.7.0' + # nokogiri <= 1.14.2 mishandle tag names with ":" in them (see #102) + s.add_dependency 'nokogiri', '>= 1.14.3' + # rack < 2.2.3.0 have security vulns + s.add_development_dependency 'rack', '>= 2.2.3' + s.add_development_dependency 'rake', '>= 13.0.3' + # just a guess based on what I used to use + s.add_development_dependency 'rubocop', '>= 1.25.1' + # sinatra < 2.2.3 have security vulns + s.add_development_dependency 'sinatra', '>= 2.2.3' + s.add_development_dependency 'test-unit', '>= 3.2.7' s.rdoc_options = ['--line-numbers', '--inline-source', '--title', 'Ronn'] s.require_paths = %w[lib]