rails_app_version 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4a38336feb27db4c69dc73aeb4358e7a5ca69e696bd197ba67bb152de74b1bb
-  data.tar.gz: 45083bf090ffe8e0797ac4af3ad18340a1f7c1b4f8a0932e282054a8e663d5d8
+  metadata.gz: 409c9f1cf9552f299f410f29c6c5aec32f4690a521e2ff99a1f441a7cbfafc2e
+  data.tar.gz: 2859e8073f038fcbdd924ad612a6db4193e7e7944c7fcc3b15be3fb104414284
 SHA512:
-  metadata.gz: 042bd639e93aa7f6d60cf1b8df524f66254eca8bc4b538e4877669beae575ef4fd3a3eb93d1d028f9078b35ba34bb44cf57a29245df4c4d957a7f6899e344161
-  data.tar.gz: '0378b7c1bd0683a5dbe0095584231bd0ff5a42672fefa4a373e994b389c6942499aeab5983b35c6efcbad2e8ba8eb1efc794d11ce28928d92cf1cac2bb221dd5'
+  metadata.gz: a04505806cbece569d2dc2b03e55cf724782b0075386d6360acd9dcdf0a94e8b96fe5bd81c78d848bad3462f04afb609623bbb0dc106f23bedbb7ce0f8519ef8
+  data.tar.gz: 533d508373e430b6934e86ebb476195b5c8f064c1337cfe5964c7762ed47fa11e89e6a61df9e87a5569a170d64293aae42caa99a91aa717207019cc63280fb51

data/README.md

@@ -4,6 +4,17 @@ Rails AppVersion provides an opinionated version and environment management for
 version and environment information throughout your application, it enables better error tracking, debugging, and
 deployment management.
 
+> [!NOTE]
+> **Part of this gem has been upstreamed into Rails.** Rails 8.2 ships `Rails.application.revision`, which resolves the
+> deploy revision from `ENV["REVISION"]`, the `REVISION` file, then `git rev-parse HEAD`. This gem defers to it rather
+> than reimplementing it. See [Revision resolution](#revision-resolution).
+>
+> The middleware has **not** been upstreamed, and is the main reason to still reach for this gem. It advertises the
+> running version and environment on every response (`X-App-Version`, `X-App-Environment`), which lets external
+> agents (uptime monitors, deploy verifiers, load balancers, LLM agents poking at an endpoint) tell *when a server was
+> deployed* without shell access to it. `Rails.application.revision` is only readable from inside the process; the
+> header is readable from anywhere.
+
 ## Why Use Rails AppVersion?
 
 Version and environment tracking are important for modern web applications, particularly when debugging issues in
@@ -17,8 +28,15 @@ production. Rails AppVersion helps you:
 
 ### Error Reporting Integration Example
 
+Using [Lapsoss](https://github.com/seuros/lapsoss) - a vendor-neutral error reporting gem:
+
 ```ruby
-Sentry.init do |config|
+# config/initializers/lapsoss.rb
+Lapsoss.configure do |config|
+  # Works with any service - switch vendors without code changes
+  config.use_telebugs(dsn: ENV['TELEBUGS_DSN'])
+
+  # Set release and environment from Rails AppVersion
   config.release = Rails.application.version.to_s
   config.environment = Rails.application.env
 end
@@ -88,12 +106,25 @@ The default configuration file is located at `config/app_version.yml`:
 shared:
   # Attempts to read from VERSION file, falls back to '0.0.0'
   version: <%= Rails.root.join('VERSION').read.strip rescue '0.0.0' %>
-  # Attempts to read from REVISION file, then tries git commit hash, finally falls back to '0'
-  revision: <%= Rails.root.join('REVISION').read.strip rescue (`git rev-parse HEAD`.strip rescue '0') %>
+  # Blank on purpose. See "Revision resolution" below
+  revision:
   show_revision: <%= Rails.env.local? %>
   environment: <%= ENV.fetch('RAILS_APP_ENV', Rails.env) %>
 ```
 
+#### Revision resolution
+
+Rails 8.2 resolves the deploy revision itself via `Rails.application.revision`, checking `ENV["REVISION"]`, then the
+`REVISION` file, then `git rev-parse HEAD`. This gem defers to it rather than reimplementing that lookup, so the
+resolution order is:
+
+1. An explicit `revision:` in `config/app_version.yml`, if set
+2. `Rails.application.revision` (Rails 8.2+)
+3. On Rails 8.0/8.1 only: `ENV["REVISION"]`, then the `REVISION` file
+
+On Rails 8.0 and 8.1 there is no `git rev-parse` fallback: deploy a `REVISION` file or set `ENV["REVISION"]` rather
+than shelling out on every boot. Step 3 goes away once Rails 8.2 is the minimum supported version.
+
 You can customize this configuration for different environments, though we recommend maintaining version information in
 the VERSION file:
 
@@ -195,22 +226,82 @@ The gem automatically displays version and environment information when you star
 
 ```
 Welcome to the Rails console!
-Ruby version: 3.2.0
+Ruby version: 3.4.0
 Application environment: staging
 Application version: 1.2.3
 To exit, press `Ctrl + D`.
 ```
 
+## Requirements
+
+- Ruby >= 3.4
+- Rails >= 8.0
+
+CI runs the suite against Ruby 3.4 and 4.0, on Rails 8.0, 8.1 and `rails/rails@main`.
+
 ## Version Format
 
 Rails AppVersion supports several version formats:
 
 - Standard versions: "1.2.3" (major.minor.patch)
 - Short versions: "1.2" (major.minor)
-- Pre-release versions: "2.0.0-alpha" (with pre-release identifier)
+- Pre-release versions: "2.0.0-alpha", "2.0.0.alpha" or "2.0.0.pre.alpha" (all expose `pre == "alpha"`)
+
+Parsing is delegated to `Gem::Version`, so comparison operators behave exactly as they do for gem versions.
+Malformed strings raise `ArgumentError` rather than silently parsing as `0`.
 
-Version strings are parsed according to Semantic Versioning principles and maintain compatibility with `Gem::Version`
-for comparison operations.
+## Using with release-please
+To have release-please automatically update a plain VERSION file in your repository:
+1. Add the inline marker to your VERSION file:
+```
+1.0.0
+```
+
+2. Configure release-please
+
+Add the following to .github/release-please-config.json:
+```json
+{
+  "packages": {
+    ".": {
+      "release-type": "simple",
+      "component": "App Name",
+      "version-file": "VERSION"
+    }
+  }
+}
+```
+
+3. Add the following to .github/release-please-manifest.json:
+```json
+{
+    ".": "1.0.0"
+}
+```
+
+4. Add the following to .github/workflows/release-please.yml:
+```yaml
+name: release-please
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release-please:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          token: ${{ secrets.RELEASE_PLEASE_TOKEN }}
+          config-file: .github/release-please-config.json
+          manifest-file: .github/.release-please-manifest.json
+```
 
 ## Contributing
 

data/config/app_version.yml

@@ -1,6 +1,9 @@
 shared:
   version: <%= Rails.root.join('VERSION').read.strip rescue '0.0.0' %>
-  revision: <%= Rails.root.join('REVISION').read.strip rescue (`git rev-parse HEAD`.strip rescue '0') %>
+  # Blank on purpose. Rails resolves the deploy revision itself from
+  # ENV["REVISION"], the REVISION file, then `git rev-parse HEAD`.
+  # Set a value here only to override that.
+  revision:
   show_revision: <%= Rails.env.local? %>
   environment: <%= ENV.fetch('RAILS_APP_ENV', Rails.env) %>
   middleware:

data/lib/rails_app_version/app_info.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RailsAppVersion
+  # Mixed into Rails::Application so `Rails.application.version`,
+  # `.env` and `.app_config` read straight off the railtie instance that
+  # parsed app_version.yml.
+  module AppInfo
+    def version = app_version_railtie.version
+    def env = app_version_railtie.env
+    def app_config = app_version_railtie.app_config
+
+    private
+
+    def app_version_railtie
+      @app_version_railtie ||= railties.find { |railtie| railtie.is_a?(RailsAppVersion::Railtie) }
+    end
+  end
+end

data/lib/rails_app_version/railtie.rb

@@ -1,21 +1,31 @@
 # frozen_string_literal: true
 
 module RailsAppVersion
-  Rails::Application.include AppEnvironment
-  Rails::Application.include AppVersion
+  Rails::Application.include AppInfo
+
   class Railtie < ::Rails::Railtie
-    CONFIG_FILE = "app_version.yml".freeze
+    CONFIG_FILE = "app_version.yml"
 
     class << self
       def root
-        @root ||= Pathname.new(File.expand_path(File.expand_path("../../", __dir__)))
+        @root ||= Pathname.new(File.expand_path("../..", __dir__))
+      end
+
+      def print_console_banner
+        # rubocop:disable Rails/Output
+        puts "Welcome to the Rails console!"
+        puts "Ruby version: #{RUBY_VERSION}"
+        puts "Application environment: #{Rails.application.env}"
+        puts "Application version: #{Rails.application.version.full}"
+        puts "To exit, press `Ctrl + D`."
+        # rubocop:enable Rails/Output
       end
     end
 
     attr_reader :app_config, :version, :env
 
     rake_tasks do
-      load File.expand_path("../../tasks/app_version_tasks.rake", __FILE__)
+      load File.expand_path("../tasks/app_version_tasks.rake", __dir__)
     end
 
     console do
@@ -24,48 +34,53 @@ module RailsAppVersion
 
     initializer "rails_app_version.fetch_config" do |app|
       @app_config = load_config(app)
-      @version = Version.create(@app_config[:version], @app_config[:revision])
+      @version = Version.create(@app_config[:version], revision_for(app, @app_config))
       @env = ActiveSupport::StringInquirer.new(@app_config.fetch(:environment, Rails.env))
     end
 
     initializer "rails_app_version.middleware" do |app|
-      # Add the middleware to the stack if enabled
-      if @app_config.dig(:middleware, :enabled)
-        options = @app_config.dig(:middleware, :options) || {}
-        app.middleware.insert_before Rails::Rack::Logger, AppInfoMiddleware, options
-      end
+      next unless @app_config.dig(:middleware, :enabled)
+
+      options = @app_config.dig(:middleware, :options) || {}
+      app.middleware.insert_before Rails::Rack::Logger, AppInfoMiddleware, options
     end
 
     private
 
+    # An explicit revision in app_version.yml always wins. Otherwise defer to
+    # Rails::Application#revision (8.2+), which already resolves
+    # ENV["REVISION"], the REVISION file, then `git rev-parse HEAD`. There is
+    # no reason for this gem to reimplement that.
+    def revision_for(app, config)
+      return config[:revision] if config[:revision].present?
+      return app.revision if app.respond_to?(:revision)
+
+      # Rails < 8.2 has no native lookup. Deliberately no `git rev-parse`
+      # fallback: ship a REVISION file or set ENV["REVISION"] instead of
+      # shelling out on every boot. Remove once 8.2 is the minimum.
+      ENV["REVISION"].presence || read_revision_file(app)
+    end
+
+    def read_revision_file(app)
+      app.root.join("REVISION").read.strip.presence
+    rescue SystemCallError
+      nil
+    end
+
+    # Falls back to the config shipped with the gem when the host app has no
+    # config/app_version.yml. `rake app:version:config` installs one.
     def load_config(app)
       app.config_for(:app_version, env: Rails.env)
     rescue StandardError => e
-      Rails.logger.warn("Could not load app_version.yml: #{e.message}. Using default configuration.")
-      load_default_config
+      Rails.logger&.warn("Could not load #{CONFIG_FILE}: #{e.message}. Using default configuration.")
+      default_config
     end
 
-    def load_default_config
-      yaml_path = Railtie.root.join("config", CONFIG_FILE)
-      all_configs = parse_yaml_config(yaml_path)
-      all_configs[:shared] || {}
-    end
-
-    def parse_yaml_config(path)
+    def default_config
+      path = Railtie.root.join("config", CONFIG_FILE)
       return {} unless File.exist?(path)
 
-      require "erb"
-      ActiveSupport::ConfigurationFile.parse(path).deep_symbolize_keys
-    end
-
-    def self.print_console_banner
-      # rubocop:disable Rails/Output
-      puts "Welcome to the Rails console!"
-      puts "Ruby version: #{RUBY_VERSION}"
-      puts "Application environment: #{Rails.application.env}"
-      puts "Application version: #{Rails.application.version&.full}"
-      puts "To exit, press `Ctrl + D`."
-      # rubocop:enable Rails/Output
+      ActiveSupport::ConfigurationFile.parse(path).deep_symbolize_keys[:shared] || {}
     end
   end
 end

data/lib/rails_app_version/version.rb

@@ -1,73 +1,61 @@
 # frozen_string_literal: true
 
 module RailsAppVersion
-  VERSION = "1.4.0"
-
+  VERSION = "1.5.0"
+
+  # A Gem::Version with named segments, an optional VCS revision and cache-key
+  # helpers.
+  #
+  # Segment parsing is delegated to Gem::Version, so "2.0.0-alpha",
+  # "2.0.0.alpha" and "2.0.0.pre.alpha" all describe the same prerelease, and
+  # malformed strings raise instead of silently parsing as 0.
   class Version < Gem::Version
-    attr_reader :major, :minor, :patch, :pre, :revision
+    # Deploy scripts write "0" to REVISION when no SHA is available.
+    BLANK_REVISION = "0"
+
+    attr_accessor :revision
 
     def self.create(version_string, revision = nil)
-      new(version_string).tap { |v| v.set_revision(revision) }
-    end
+      raise ArgumentError, "Version string cannot be nil or empty" if version_string.to_s.strip.empty?
 
-    def set_revision(revision)
-      @revision = revision
+      new(version_string).tap { |version| version.revision = revision }
     end
 
-    def full
-      return to_s unless revision
-      return to_s if revision.to_s == "0"
-      "#{self} (#{short_revision})"
-    end
+    def major = numeric_segments[0] || 0
+    def minor = numeric_segments[1] || 0
+    def patch = numeric_segments[2]
 
-    def to_cache_key
-      parts = [ major, minor ]
-      parts << patch if has_patch?
-      parts << pre if prerelease?
-      parts.join("-")
-    end
+    # The prerelease label, without the "pre" marker Gem::Version inserts:
+    # "2.0.0-alpha" => "alpha", "1.2.3" => nil.
+    def pre
+      return @pre if defined?(@pre)
 
-    def short_revision
-      revision.to_s.slice(0, 8).presence
+      @pre = segments.drop(numeric_segments.size).reject { |segment| segment == "pre" }.join(".").presence
     end
 
-    def prerelease?
-      !@pre.nil?
+    def full
+      short_revision ? "#{self} (#{short_revision})" : to_s
     end
 
-    def production_ready?
-      !prerelease? && major.positive?
-    end
+    def short_revision
+      return if revision.to_s == BLANK_REVISION
 
-    def has_patch?
-      !@patch.nil?
+      revision.to_s.slice(0, 8).presence
     end
 
-    protected
-
-    def initialize(version)
-      super
-      parse_version(version)
+    def to_cache_key
+      parts = [ major, minor ]
+      parts << patch if patch
+      parts << pre if prerelease?
+      parts.join("-")
     end
 
-    private
-
-    def parse_version(version_string)
-      if version_string.nil? || version_string.empty?
-        raise ArgumentError, "Version string cannot be nil or empty"
-      end
-
-      parts = version_string.split(".")
-      pre_parts = parts.last.split("-")
+    def production_ready? = !prerelease? && major.positive?
 
-      if pre_parts.length > 1
-        parts[-1] = pre_parts[0]
-        @pre = pre_parts[1]
-      end
+    private
 
-      @major = parts[0].to_i
-      @minor = parts[1]&.to_i || 0
-      @patch = parts[2]&.to_i
+    def numeric_segments
+      @numeric_segments ||= segments.take_while { |segment| segment.is_a?(Integer) }
     end
   end
 end

data/lib/rails_app_version.rb

@@ -2,10 +2,9 @@
 
 require "rails"
 require "rails/application"
-require "rails_app_version/version"
-require "rails_app_version/app_version"
-require "rails_app_version/app_environment"
 require "action_controller/railtie"
+require "rails_app_version/version"
+require "rails_app_version/app_info"
 require "rails_app_version/railtie"
 
 module RailsAppVersion

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_app_version
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -15,20 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '8.2'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '7.0'
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '8.2'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: dotenv-rails
   requirement: !ruby/object:Gem::Requirement
@@ -68,9 +62,8 @@ files:
 - Rakefile
 - config/app_version.yml
 - lib/rails_app_version.rb
-- lib/rails_app_version/app_environment.rb
+- lib/rails_app_version/app_info.rb
 - lib/rails_app_version/app_info_middleware.rb
-- lib/rails_app_version/app_version.rb
 - lib/rails_app_version/railtie.rb
 - lib/rails_app_version/version.rb
 - lib/tasks/app_version_tasks.rake
@@ -88,14 +81,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Get the version of your Rails app
 test_files: []

data/lib/rails_app_version/app_environment.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module RailsAppVersion
-  module AppEnvironment
-    extend ActiveSupport::Concern
-
-    included do
-      def env
-        @env ||= railties.find do |railtie|
-          railtie.is_a?(RailsAppVersion::Railtie)
-        end.env
-      end
-    end
-  end
-end

data/lib/rails_app_version/app_version.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module RailsAppVersion
-  module AppVersion
-    extend ActiveSupport::Concern
-
-    included do
-      def version
-        @version ||= railties.find do |railtie|
-          railtie.is_a?(RailsAppVersion::Railtie)
-        end.version
-      end
-    end
-  end
-end