rails_app_version 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de1ff73be83ef61042e2e2baddd1b94805f4f41a8ce2f1a021802ccad42c2323
-  data.tar.gz: a410eac1d9ac536a352f8d3158bf1e5bf6b872aa1fced4c2c152db4adc71d840
+  metadata.gz: 6ceff4b502902ed60d708fd295202078d48fc55a56abbd427b92daed2c5da7ad
+  data.tar.gz: f517710e94b7d97c4e90593f3ca6f9ab9b2351848d3fdb1e2ead54e91aee59a7
 SHA512:
-  metadata.gz: f1cfbe373f72deb414e9bbe6900e690552da4f8f5a68ca7d1df286bb553556a1e16c28f162b6098a7027cdcf7ac1a6d3126bfe986449834049d7a64716b29eb4
-  data.tar.gz: c09bae51fe6e6ee8e714cc04ef3b4f5558f2618ece745423bab6248372ab10de8e45d5d92b8aaac2dee94c75727b9b667e7bf0f13b7e00672a25655ecdfe73c8
+  metadata.gz: 656786a178a739b22a45d8e1ec71e013c4dfd121e979726dd9536ff6c90630cfb0152b6585f0b081acdd1eab584a760db21388ff278c490d4c86620ebecd1b95
+  data.tar.gz: e124ff8fb6fdc72478947a215e41865cb93bbb1c08607f74a5d7fffd9f4776964e9566433ac812eecb8a6a187f5288114ff67263dc4f144b5d1284a4c3db2e8a

data/README.md

@@ -1,45 +1,263 @@
 # Rails AppVersion
 
-Rails AppVersion is a Ruby on Rails engine designed to easily manage and access your application's version and environment information. 
+Rails AppVersion provides an opinionated version and environment management for your Rails applications. By exposing
+version and environment information throughout your application, it enables better error tracking, debugging, and
+deployment management.
 
-It allows for a seamless integration of versioning within your Rails application, providing a straightforward way to access the current application version and environment without hardcoding these values.
+## Why Use Rails AppVersion?
 
-This gem is exclusively build for Rails applications and is compatible with Rails 7.0 and above.
+Version and environment tracking are important for modern web applications, particularly when debugging issues in
+production. Rails AppVersion helps you:
 
-## Usage
-How to use my plugin.
+- Track errors with version context in error reporting services
+- Identify which version of your application is running in each environment
+- Cache bust assets between versions
+- Verify deployment success across environments
+- Avoid homegrown version management solutions
+
+### Error Reporting Integration Example
+
+```ruby
+Sentry.init do |config|
+  config.release = Rails.application.version.to_s
+  config.environment = Rails.application.env
+end
+```
+
+### Cache Management Example
+
+```ruby
+
+class AssetManifest
+  def asset_path(path)
+    "/assets/#{path}?v=#{Rails.application.version.to_cache_key}"
+  end
+end
+```
 
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
 gem "rails_app_version"
 ```
 
-And then execute:
+Then execute:
+
 ```bash
-$ bundle
+$ bundle install
+$ rails app:version:config  # Copies the default configuration file
+$ echo "1.0.0" > VERSION            # Create initial version file
+```
+
+## Version Management
+
+Rails AppVersion supports two methods for managing your application's version:
+
+### Recommended: Using a VERSION File
+
+The recommended approach is to maintain a `VERSION` file in your application's root directory. This file should contain
+only the version number:
+
+```plaintext
+# VERSION
+1.2.3
+```
+
+This approach offers several advantages:
+
+- Clear version history in source control
+- Easy automated updates during deployment
+- Separation of version from configuration
+- Compatibility with CI/CD pipelines
+
+### Alternative: Configuration in YAML
+
+While not recommended for production applications, you can also specify the version directly in the configuration file.
+The default configuration file is located at `config/app_version.yml`:
+
+```yaml
+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') %>
+  show_revision: <%= Rails.env.local? %>
+  environment: <%= ENV.fetch('RAILS_APP_ENV', Rails.env) %>
+```
+
+You can customize this configuration for different environments, though we recommend maintaining version information in
+the VERSION file:
+
+```yaml
+shared:
+  # Not recommended: hardcoding version in YAML
+  version: '1.2.3'
+  environment: production
+
+development:
+  environment: local
+  show_revision: true
+
+staging:
+  environment: staging
 ```
 
-## Usage:
-    After adding the gem, you can access the application version and environment information anywhere in your Rails application.
+## Usage
+
+### Accessing Version Information
+
 ```ruby
-Rails.application.version # => "1.0.0"
+# Get the current version
+Rails.application.version.to_s # => "1.2.3"
+
+# Check version components
+Rails.application.version.major # => 1
+Rails.application.version.minor # => 2
+Rails.application.version.patch # => 3
+
+# Check version status
+Rails.application.version.production_ready? # => true
+Rails.application.version.prerelease? # => false
+
+# Get a cache-friendly version string
+Rails.application.version.to_cache_key # => "1-2-3"
+```
+
+## Version Headers Middleware
+
+Rails AppVersion includes an optional middleware that adds version and environment information to HTTP response headers.
+This is particularly useful in staging and development environments to verify deployment success and track which version
+of the application is serving requests.
+
+### Configuring the Middleware
+
+Enable and configure the middleware in your `config/app_version.yml`:
+
+```yaml
+development:
+  middleware:
+    enabled: true
+    options:
+      include_revision: true  # Include git revision in headers
+      version_header: X-App-Version
+      environment_header: X-App-Environment
+      revision_header: X-App-Revision
+
+staging:
+  middleware:
+    enabled: true
+    options:
+      version_header: X-Staging-Version
+      environment_header: X-Staging-Environment
+```
+
+### Manual Middleware Configuration
+
+You can also add the middleware manually in your application configuration:
+
+```ruby
+# config/application.rb or config/environments/staging.rb
+config.middleware.use RailsAppVersion::AppInfoMiddleware, {
+  version_header: 'X-Custom-Version',
+  environment_header: 'X-Custom-Environment',
+  include_revision: true
+}
+```
+
+The middleware will add the following headers to each response:
+
+- X-App-Version: Current application version, optionally including revision (e.g., "1.2.3" or "1.2.3 (abc123de)")
+- X-App-Environment: Current environment (e.g., "staging")
+
+When `include_revision` is enabled, the version header will include the first 8 characters of the git revision in
+parentheses. This provides a quick way to verify both the version and the specific deployment in a single header.
+
+This makes it easy for developers to verify which version is deployed and running in each environment, particularly
+useful during deployments and debugging.
+
+### Environment Management
+
+```ruby
+# Get the current environment
 Rails.application.env # => "staging"
+
+# Environment checks
+Rails.application.env.production? # => false
+Rails.application.env.staging? # => true
 ```
 
-## Features
-- Easy Configuration: Set up your application version and environment in a simple YAML file.
-- Automatic Integration: The engine automatically integrates with your Rails application, making the version and environment information accessible.
-- Flexible Usage: Access the application version and environment information anywhere in your Rails application.
+### Console Integration
+
+The gem automatically displays version and environment information when you start a Rails console:
+
+```
+Welcome to the Rails console!
+Ruby version: 3.2.0
+Application environment: staging
+Application version: 1.2.3
+To exit, press `Ctrl + D`.
+```
+
+## 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)
+
+Version strings are parsed according to Semantic Versioning principles and maintain compatibility with `Gem::Version`
+for comparison operations.
+
+## Version Headers
+
+Enable version headers in HTTP responses to verify deployments and track running versions:
+
+```yaml
+# config/app_version.yml
+development:
+  middleware:
+    enabled: true
+    options:
+      include_revision: true
+
+staging:
+  middleware:
+    enabled: true
+```
+
+Or add the middleware manually:
+
+```ruby
+# config/application.rb
+config.middleware.use RailsAppVersion::AppInfoMiddleware, {
+  version_header: 'X-App-Version',
+  environment_header: 'X-App-Environment',
+  include_revision: true
+}
+```
+
+Headers added:
+
+- X-App-Version: "1.2.3" (or "1.2.3 (abc123de)" with revision)
+- X-App-Environment: "production"
 
 ## Contributing
-Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
-1. Fork the repo
-2. Create your feature branch (git checkout -b my-new-feature)
-3. Commit your changes (git commit -am 'Add some feature')
-4. Push to the branch (git push origin my-new-feature)
-5. Create a new Pull Request
+
+We welcome contributions! Here's how you can help:
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Add tests for your changes
+4. Make your changes and ensure tests pass
+5. Commit your changes (`git commit -am 'Add some feature'`)
+6. Push to the branch (`git push origin my-new-feature`)
+7. Create a new Pull Request
+
+Please ensure your changes include appropriate tests and documentation.
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/rails_app_version/app_environment.rb

@@ -0,0 +1,15 @@
+# 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_info_middleware.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RailsAppVersion
+  class AppInfoMiddleware
+    DEFAULT_OPTIONS = {
+      version_header: "X-App-Version",
+      environment_header: "X-App-Environment",
+      revision_header: "X-App-Revision",
+      include_revision: false
+    }.freeze
+
+    def initialize(app, options = {})
+      @app = app
+      @options = DEFAULT_OPTIONS.merge(options)
+    end
+
+    def call(env)
+      status, headers, response = @app.call(env)
+
+      headers[@options[:version_header]] = Rails.application.version.full
+      headers[@options[:environment_header]] = Rails.application.env
+
+      [ status, headers, response ]
+    end
+  end
+end

data/lib/rails_app_version/app_version.rb

@@ -0,0 +1,15 @@
+# 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

data/lib/rails_app_version/railtie.rb

@@ -0,0 +1,53 @@
+module RailsAppVersion
+  class Railtie < ::Rails::Railtie
+    class << self
+      def root
+        @root ||= Pathname.new(File.expand_path(File.expand_path("../../", __dir__)))
+      end
+    end
+
+    attr_reader :app_config, :version, :env
+
+    rake_tasks do
+      namespace :app do
+        namespace :version do
+          desc "Copy config/app_version.yml to the main app config directory"
+          task :config do
+            source = Railtie.root.join("config", "app_version.yml")
+            destination = Rails.root.join("config", "app_version.yml")
+
+            FileUtils.cp(source, destination)
+
+            puts "Installed app_version.yml to #{destination}"
+          end
+        end
+      end
+    end
+
+    # Console
+    console do
+      # 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}"
+      puts "To exit, press `Ctrl + D`."
+      # rubocop:enable Rails/Output
+    end
+
+    initializer "fetch_config" do |app|
+      @app_config = begin
+                      app.config_for(:app_version, env: Rails.env)
+                    rescue RuntimeError => e # file is not found
+                      # Load the default configuration from the gem
+                      require "erb"
+                      yaml = Railtie.root.join("config", "app_version.yml")
+                      all_configs = ActiveSupport::ConfigurationFile.parse(yaml).deep_symbolize_keys
+                      all_configs[:shared]
+                    end
+
+      @version = RailsAppVersion::Version.create(@app_config[:version], @app_config[:revision])
+      @env = ActiveSupport::StringInquirer.new(@app_config.fetch(:environment, Rails.env))
+    end
+  end
+end

data/lib/rails_app_version/version.rb

@@ -1,5 +1,72 @@
 # frozen_string_literal: true
 
 module RailsAppVersion
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
+
+  class Version < Gem::Version
+    attr_reader :major, :minor, :patch, :pre, :revision
+
+    def self.create(version_string, revision = nil)
+      new(version_string).tap { |v| v.set_revision(revision) }
+    end
+
+    def set_revision(revision)
+      @revision = revision
+    end
+
+    def full
+      return to_s unless revision
+      "#{self} (#{short_revision})"
+    end
+
+    def to_cache_key
+      parts = [ major, minor ]
+      parts << patch if has_patch?
+      parts << pre if prerelease?
+      parts.join("-")
+    end
+
+    def short_revision
+      revision&.slice(0, 8)
+    end
+
+    def prerelease?
+      !@pre.nil?
+    end
+
+    def production_ready?
+      !prerelease? && major.positive?
+    end
+
+    def has_patch?
+      !@patch.nil?
+    end
+
+    protected
+
+    def initialize(version)
+      super
+      parse_version(version)
+    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("-")
+
+      if pre_parts.length > 1
+        parts[-1] = pre_parts[0]
+        @pre = pre_parts[1]
+      end
+
+      @major = parts[0].to_i
+      @minor = parts[1]&.to_i || 0
+      @patch = parts[2]&.to_i
+    end
+  end
 end

data/lib/rails_app_version.rb

@@ -3,88 +3,16 @@
 require "rails"
 require "rails/application"
 require "rails_app_version/version"
+require "rails_app_version/railtie"
+require "rails_app_version/app_version"
+require "rails_app_version/app_environment"
+require "rails_app_version/version"
 require "action_controller/railtie"
 
 module RailsAppVersion
-  class Version < Gem::Version
-    # This method cache used by Rails.cache.fetch to generate a cache key
-    def to_cache_key
-      (to_s).parameterize
-    end
-  end
-  class Railtie < ::Rails::Railtie
-    attr_reader :app_config, :version, :env
-
-    def root
-      @root ||= Pathname.new(File.expand_path("..", __dir__))
-    end
-
-    rake_tasks do
-      namespace :app do
-        namespace :version do
-          desc "Copy config/app_version.yml to the main app config directory"
-          task :config do
-            source = RailsAppVersion::Railtie.root.join("config", "app_version.yml")
-            destination = Rails.root.join("config", "app_version.yml")
-
-            FileUtils.cp(source, destination)
-
-            puts "Installed app_version.yml to #{destination}"
-          end
-        end
-      end
-    end
-
-    # Console
-    console do
-      # 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}"
-      puts "To exit, press `Ctrl + D`."
-      # rubocop:enable Rails/Output
-    end
-
-    initializer "fetch_config" do |app|
-      @app_config = begin
-        app.config_for(:app_version, env: Rails.env)
-      rescue RuntimeError
-        # Load the default configuration from the gem, if the app does not have one
-        require "erb"
-        yaml = Railtie.root.join("config", "app_version.yml")
-        all_configs = ActiveSupport::ConfigurationFile.parse(yaml).deep_symbolize_keys
-        all_configs[:shared]
-                    end
-
-      @version = Version.new(@app_config[:version])
-      @env = ActiveSupport::StringInquirer.new(@app_config[:environment] || Rails.env)
-    end
-  end
-
-  module AppVersion
-    extend ActiveSupport::Concern
-
-    included do
-      def version
-        @version ||= railties.find do |railtie|
-          railtie.is_a?(RailsAppVersion::Railtie)
-        end.version
-      end
-    end
-  end
-
-  module AppEnvironment
-    extend ActiveSupport::Concern
+  extend ActiveSupport::Autoload
 
-    included do
-      def env
-        @env ||= railties.find do |railtie|
-          railtie.is_a?(RailsAppVersion::Railtie)
-        end.env
-      end
-    end
-  end
+  autoload :AppInfoMiddleware
 end
 
 Rails::Application.include RailsAppVersion::AppVersion

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_app_version
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Abdelkader Boudih
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-03 00:00:00.000000000 Z
+date: 2024-12-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -69,6 +69,10 @@ files:
 - Rakefile
 - config/app_version.yml
 - lib/rails_app_version.rb
+- lib/rails_app_version/app_environment.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
 homepage: https://github.com/seuros/rails_app_version
 licenses: []
@@ -85,14 +89,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Get the version of your Rails app