From 1ee76ffedac88fb4594b3fa0e859761a4755eea6 Mon Sep 17 00:00:00 2001 From: Andrew Janke Date: Wed, 3 Jan 2024 23:47:31 -0500 Subject: [PATCH] doc: add Distros & Packaging notes --- CHANGELOG.md | 8 +-- doc-project/Developer-Guide.md | 5 +- doc-project/Distros and Packaging.md | 93 ++++++++++++++++++++++++++++ 3 files changed, 99 insertions(+), 7 deletions(-) create mode 100644 doc-project/Distros and Packaging.md diff --git a/CHANGELOG.md b/CHANGELOG.md index f47756d..d41f39b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,8 @@ Note: 0.10.1 is the first 0.10.x release, because Ronn-NG 0.10.0 does not exist. * Switch to GitHub Flavored Markdown ([#53](https://github.com/apjanke/ronn-ng/pull/53)) * Fixes code block rendering +* doc: Reformat Changelog to match common gem and keep-a-changelog conventions + * NOTE: Renamed `CHANGES` to `CHANGELOG.md`. Packagers will need to update specs. * Bump Ruby to 2.7, gem deps to latest minor versions ### Bug Fixes @@ -19,14 +21,10 @@ Note: 0.10.1 is the first 0.10.x release, because Ronn-NG 0.10.0 does not exist. * Elide HTML comments when producing roff output ([#65](https://github.com/apjanke/ronn-ng/issues/65)) * Remove non-portable `more -i` option ([#71](https://github.com/apjanke/ronn-ng/issues/71)) * Fix charset (utf-8) in HTML output's Content-Type ([#83](https://github.com/apjanke/ronn-ng/pull/83)) -* Psych 4.0 test workaround, Ruby 3.x support (from n-ronn) ([#87](https://github.com/apjanke/ronn-ng/issues/87)) +* Psych 4.0 test fix, Ruby 3.x support (from n-ronn) ([#87](https://github.com/apjanke/ronn-ng/issues/87)) * Fix test failure for angle-bracket items with namespace-like "foo:" prefixes ([#102](https://github.com/apjanke/ronn-ng/issues/102)) * Inclusion of the "foo:" is now considered correct, matching current code behavior -### Internal - -* doc: Reformat Changelog to match common gem and keep-a-changelog conventions - ## 0.10.0 (never released) Doesn't exist due to a RubyGems publishing mistake. diff --git a/doc-project/Developer-Guide.md b/doc-project/Developer-Guide.md index 5c5f45a..d2a7a92 100644 --- a/doc-project/Developer-Guide.md +++ b/doc-project/Developer-Guide.md @@ -15,10 +15,9 @@ * Build and publish the gem to RubyGems * `gem build ronn-ng.gemspec` * `gem push ronn-ng-.gem` +* Update the ronn-ng formula in our [ronn-ng/homebrew-ronn-ng Homebrew tap repo](https://github.com/apjanke/homebrew-ronn-ng) and push it * TBD: Announce the release somewhere -TODO: Add instructions for prerelease/beta releases. - After the release, start development on the next release: * Update the version in files @@ -30,6 +29,8 @@ After the release, start development on the next release: * Commit and push * Use commit message like "open development for next release" +TODO: Add instructions for prerelease/beta releases. Include a process for making a prerelease ronn-ng formula in our Homebrew tap. + ## Setting up your dev environment You need to have all of the gem dependencies installed, either in your system gem installation location, or user gems, or locally in this directory. `bundle install` will do something like that, but I haven't been able to figure out how to get that to work with `bundle exec rake test` without requiring you to install the gems and stuff in to the system location instead of a user or dir-local location. diff --git a/doc-project/Distros and Packaging.md b/doc-project/Distros and Packaging.md new file mode 100644 index 0000000..6a7115c --- /dev/null +++ b/doc-project/Distros and Packaging.md @@ -0,0 +1,93 @@ +# Distros and Packaging + +This doc has notes about packaging Ronn-NG with various package managers, and about the distros (like Linux distros or Homebrew) which have picked up Ronn-NG for inclusion. + +The distro packagers have picked up Ronn-NG on their own and created the packages for them, including the package definitions and patches for them. The Ronn-NG project doesn't maintain (or necessarily understand) these packaging mechanisms. This list is a reference, useful for finding the actual maintainers of the packaging stuff if you need to discuss that level of things, or to explore and learn about how they work. + +We'd generally like to upstream any patches applied by package managers, unless they're very platform-specific. And if you're a distro packager who'd like us to do something to make packaging Ronn-NG easier for you, please let us know – email or open an issue on [our GitHub repo issues page](https://github.com/apjanke/ronn-ng/issues). + +## Distros + +### Debian + +* Package: [ronn](https://packages.debian.org/bookworm/ronn) +* Package: [ruby-ronn](https://packages.debian.org/bookworm/ruby-ronn) +* Source package: [ruby-ronn](https://packages.debian.org/source/bookworm/ruby-ronn) (produces both ruby-ronn and ronn packages?) +* Source repo: [ruby-ronn](https://salsa.debian.org/ruby-team/ruby-ronn) + +| Distro Release | Ronn-NG Ver | Ruby Ver | +| -------------- | ----------- | -------- | +| 10 buster | 0.8.0 | 2.5 | +| 11 bullseye | 0.9.1 | 2.7 | +| 12 bookworm | 0.9.1 | 3.1 ??? | +| 13 trixie | 0.9.1 | 3.1 ??? | +| 14 sid | TBD? / 0.9.1 | 3.1 | + +Debian splits Ronn-NG into separate ronn ("tool") and ruby-ronn ("library") packages. Not sure why, or how that is done. It's not something I intended for Ronn-NG, and AFAICT, the original author Tomayko didn't either; Ronn doesn't seemed designed or documented for use as a Ruby library as opposed to a command. + +Package definitions and patches are in the `debian` subdirectory in the repo. + +Their package definition has a "watch" for new tags in my ronn-ng repo, so they'll notice when a new release comes out. + +The Debian package for 0.9.1 had some patches. As of 2023's work on 0.10, the non-Debian-specific ones have all been upstreamed, so they can probably remove most patches for an 0.10.1 package. (In [#80](https://github.com/apjanke/ronn-ng/issues/80), [#87](https://github.com/apjanke/ronn-ng/issues/87) (Psych 4.0 compat), [#76](https://github.com/apjanke/ronn-ng/pull/76) (reproducible man pages with fixed datestamp).) + +### Ubuntu + +* Package: [ronn](https://packages.ubuntu.com/jammy/ronn) +* Package: [ruby-ronn](https://packages.ubuntu.com/jammy/ruby-ronn) +* Source package: [ruby-ronn](https://packages.ubuntu.com/source/jammy/ruby-ronn) +* Uses the Debian source repo: [Debian ruby-ronn](https://salsa.debian.org/ruby-team/ruby-ronn) + +| Distro Release | Ronn-NG Ver | Ruby Ver | +| ---------------- | ----------- | -------- | +| 20.04 LTS focal | 0.8.0 | 2.7 | +| 22.04 LTS jammy | 0.9.1 | 3.0 | +| 23.04 lunar | 0.9.1 | 3.1 | +| 23.10 mantic | 0.9.1 | 3.1 | +| noble | TBD | | + +Ubuntu is a derivative of Debian, so I think their packaging choices and actual package defnitions are just inherited from Debian. + +### Fedora + +* Package: [rubygem-ronn-ng](https://packages.fedoraproject.org/pkgs/rubygem-ronn-ng/rubygem-ronn-ng/) +* Package (classic Ronn): [rubygem-ronn](https://packages.fedoraproject.org/pkgs/rubygem-ronn/rubygem-ronn/) + +| Distro Release | Ronn-NG Ver | Ruby Ver | +| ---------------- | ----------- | -------- | +| Fedora 38 | 0.9.1 | | +| Fedora 39 | 0.9.1 | | + +Fedora has both Ronn and Ronn-NG as distinct packages. The original rubygem-ronn only seems present in the EPEL 8 release; rubygem-ronn is in EPEL 8, Fedora 38, 39, and Rawhide. And the [spec for rubygem-ronn-ng](https://src.fedoraproject.org/rpms/rubygem-ronn-ng/blob/main/f/rubygem-ronn-ng.spec) says it obsoletes rubygem-ronn: + +```text +Provides: rubygem-ronn = %{version}-%{release} +Obsoletes: rubygem-ronn < 0.7.3-20 +``` + +### Arch Linux + +* Package: [ruby-ronn-ng](https://archlinux.org/packages/extra/any/ruby-ronn-ng/) + +### MacPorts + +* Port: [rb-ronn-ng](https://ports.macports.org/port/rb-ronn-ng/details/) + +MacPorts provides subports for different Ruby versions. Our tight dependency versioning probably makes that harder. That may be a reason to relax the ruby and gem version dependencies in the gemspec, allowing much oler versions even if I'm not testing against them. + +### Homebrew + +* Our Tap Formula: [ronn-ng/ronn-ng](https://github.com/apjanke/homebrew-ronn-ng) +* Core Formula (clasic Ronn, not Ronn-NG): [ronn.rb](https://github.com/Homebrew/homebrew-core/blob/master/Formula/r/ronn.rb) + +Homebrew still uses the original Ronn, not Ronn-NG. As of 2024-01, they're on Ronn 0.7.3. + +We provide a [custom ronn-ng Tap](https://github.com/apjanke/homebrew-ronn-ng) with formulae for installing Ronn-NG with brew. Users need to "tap" it first, and can then do `brew install ronn-ng`. + +We do not actively test our custom Homebrew formula as part of our development and release process. We should probably start doing so. + +## Packaging Considerations + +As of 0.9.1 and especially 0.10.1, Ronn-NG's gem dependency versions are defined rather tightly, to versions that I have actually tested on and know work. That seems good for when you're shipping Ronn-NG as an "application" that expects dedicated bundled/vendored dependencies. But not all targets may be able to supply those, especially in combination with dependencies from other Ruby-based programs that define their own gem version range dependencies, in distro environments that supply the dependency gems like nokogiri or mustache as their own distro packages, so they may have a fixed single "current" version. + +May want to relax those dependencies: set the minimum version for ruby and gem deps as low as I think I can go and have it still work (even with a couple issues), and don't cap the maximum versions or put exclusions unless I have actually seen issues with a that version.