chore: improve repository quality, metadata, and contributor experience (#242)

josecolella · claude · web-flow · commit 8f16c1ad4780 · 2026-03-08T11:23:49.000-07:00
Signed-off-by: Jose Colella &lt;jose.colella@gusto.com&gt;
Co-authored-by: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -19,6 +19,8 @@ jobs:
         ruby:
           - "4.0"
           - "3.4"
+          - "head"
+    continue-on-error: ${{ matrix.ruby == 'head' }}
     env:
       BUNDLE_GEMFILE: Gemfile
 
@@ -45,16 +47,39 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: "3.4.8"
+          ruby-version: "3.4"
       - run: bundle install
       - name: Standard
         run: bundle exec rake standard
+  cucumber:
+    runs-on: ubuntu-latest
+    name: Gherkin Conformance
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          submodules: true
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+      - run: bundle install
+      - name: Cucumber
+        run: bundle exec cucumber
+  security:
+    runs-on: ubuntu-latest
+    name: Security Audit
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+      - name: Bundle Audit
+        run: bundle lock && gem install bundler-audit && bundle-audit check --update
   # check the status of other jobs, so we can have a single job dependency for branch protection
   # https://github.com/community/community/discussions/4324#discussioncomment-3477871
   status:
     name: CI Status
     runs-on: ubuntu-latest
-    needs: [rspec, standard]
+    needs: [rspec, standard, cucumber, security]
     if: always()
     steps:
       - name: Successful CI
diff --git a/.gitignore b/.gitignore
@@ -10,5 +10,7 @@
 # rspec failure tracking
 .rspec_status
 
+Gemfile.lock
+
 # IDEs
 .cursor/
diff --git a/.simplecov b/.simplecov
@@ -4,6 +4,7 @@ require "simplecov-cobertura"
 
 SimpleCov.start do
   add_filter "/spec/"
+  minimum_coverage 90
   if ENV["CI"] == "true"
     formatter SimpleCov::Formatter::CoberturaFormatter
   else
diff --git a/.yardopts b/.yardopts
@@ -0,0 +1,5 @@
+--markup markdown
+--output-dir doc
+lib/**/*.rb
+- README.md
+- CHANGELOG.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -7,7 +7,7 @@ You can contribute to this project from a Windows, macOS or Linux machine.
 On all platforms, the minimum requirements are:
 
 * Git client and command line tools.
-* Ruby 3.0 or higher
+* Ruby 3.4 or higher
 
 ## Pull Request
 
@@ -50,6 +50,20 @@ To run unit tests and other checks:
 bundle exec rake
 ```
 
+#### Spec conformance tests (Gherkin)
+
+The project includes Gherkin-based conformance tests that verify compliance with the OpenFeature specification:
+
+```bash
+bundle exec cucumber
+```
+
+#### Linting
+
+This project uses [Standard Ruby](https://github.com/standardrb/standard) for code style enforcement.
+Run `bundle exec standardrb` to check, or `bundle exec standardrb --fix` to auto-fix.
+Do not run `bundle exec rubocop` directly, as a stale RuboCop server may apply different rules.
+
 ### How to Receive Comments
 
 * If the PR is not ready for review, please mark it as
diff --git a/Gemfile b/Gemfile
@@ -5,5 +5,19 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in openfeature-sdk.gemspec
 gemspec
 
-gem "cucumber", "~> 10.0", group: :test
-gem "logger", group: :test
+group :development, :test do
+  gem "debug"
+  gem "markly"
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.12.0"
+  gem "standard"
+  gem "standard-performance"
+  gem "simplecov", "~> 0.22.0"
+  gem "simplecov-cobertura", "~> 3.0"
+  gem "timecop", "~> 0.9.10"
+end
+
+group :test do
+  gem "cucumber", "~> 10.0"
+  gem "logger"
+end
diff --git a/README.md b/README.md
@@ -22,6 +22,15 @@
   </a>
 
   <!-- x-release-please-end -->
+  <a href="https://github.com/open-feature/ruby-sdk/actions/workflows/main.yml">
+    <img alt="Build" src="https://img.shields.io/github/actions/workflow/status/open-feature/ruby-sdk/main.yml?style=for-the-badge" />
+  </a>
+  <a href="https://rubygems.org/gems/openfeature-sdk">
+    <img alt="Gem Version" src="https://img.shields.io/gem/v/openfeature-sdk?style=for-the-badge&color=red" />
+  </a>
+  <a href="https://codecov.io/gh/open-feature/ruby-sdk">
+    <img alt="Code Coverage" src="https://img.shields.io/codecov/c/github/open-feature/ruby-sdk?style=for-the-badge" />
+  </a>
   <br/>
   <a href="https://bestpractices.coreinfrastructure.org/projects/9337">
     <img alt="CII Best Practices" src="https://bestpractices.coreinfrastructure.org/projects/9337/badge" />
@@ -41,6 +50,8 @@
 | Ruby 3.4.x   | Windows, MacOS, Linux |
 | Ruby 4.0.x   | Windows, MacOS, Linux |
 
+This project supports all Ruby versions in active maintenance per the [Ruby maintenance schedule](https://www.ruby-lang.org/en/downloads/branches/).
+
 ### Install
 
 Install the gem and add to the application's Gemfile by executing:
@@ -115,6 +126,16 @@ object = client.fetch_object_value(flag_key: 'object_value', default_value: { na
 
 [Providers](https://openfeature.dev/docs/reference/concepts/provider) are an abstraction between a flag management system and the OpenFeature SDK.
 Look [here](https://openfeature.dev/ecosystem?instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Provider&instant_search%5BrefinementList%5D%5Btechnology%5D%5B0%5D=Ruby) for a complete list of available providers.
+
+#### Known Providers
+
+| Provider | Package |
+|----------|---------|
+| flagd | [openfeature-flagd-provider](https://rubygems.org/gems/openfeature-flagd-provider) |
+| Flipt | [openfeature-flipt-provider](https://rubygems.org/gems/openfeature-flipt-provider) |
+| Flagsmith | [openfeature-flagsmith-provider](https://rubygems.org/gems/openfeature-flagsmith-provider) |
+| GO Feature Flag | [openfeature-go-feature-flag-provider](https://rubygems.org/gems/openfeature-go-feature-flag-provider) |
+
 If the provider you're looking for hasn't been created yet, see the [develop a provider](#develop-a-provider) section to learn how to build it yourself.
 
 Once you've added a provider as a dependency, it can be registered with OpenFeature like this:
diff --git a/Rakefile b/Rakefile
@@ -7,6 +7,13 @@ RSpec::Core::RakeTask.new(:spec)
 
 require "standard/rake"
 
+begin
+  require "yard"
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  # YARD not available
+end
+
 desc "Run Cucumber Gherkin feature tests"
 task :cucumber do
   sh "bundle exec cucumber"
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,10 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it responsibly.
+Do NOT open a public GitHub issue.
+
+Please email security concerns to: cncf-openfeature-contributors@lists.cncf.io
+
+We will acknowledge receipt within 48 hours and provide a timeline for a fix.
diff --git a/examples/basic_usage.rb b/examples/basic_usage.rb
@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "open_feature/sdk"
+
+# Configure OpenFeature with the in-memory provider for demonstration
+OpenFeature::SDK.configure do |config|
+  config.set_provider(OpenFeature::SDK::Provider::InMemoryProvider.new(
+    "v2_enabled" => true,
+    "welcome_message" => "Hello, OpenFeature!",
+    "item_limit" => 42,
+    "theme" => {"color" => "blue", "mode" => "dark"}
+  ))
+end
+
+# Create a client
+client = OpenFeature::SDK.build_client
+
+# Evaluate different flag types
+puts client.fetch_boolean_value(flag_key: "v2_enabled", default_value: false)
+puts client.fetch_string_value(flag_key: "welcome_message", default_value: "default")
+puts client.fetch_number_value(flag_key: "item_limit", default_value: 10)
+puts client.fetch_object_value(flag_key: "theme", default_value: {})
diff --git a/examples/custom_provider.rb b/examples/custom_provider.rb
@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "open_feature/sdk"
+
+# A minimal custom provider demonstrating the duck type interface.
+# Any object implementing the fetch_*_value methods works as a provider.
+class MyProvider
+  def metadata
+    OpenFeature::SDK::Provider::ProviderMetadata.new(name: "my-provider")
+  end
+
+  def init(evaluation_context = nil)
+    # Perform setup (connect to flag service, load config, etc.)
+  end
+
+  def shutdown
+    # Clean up resources
+  end
+
+  def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
+    OpenFeature::SDK::Provider::ResolutionDetails.new(
+      value: true,
+      reason: "STATIC",
+      variant: "on"
+    )
+  end
+
+  # The remaining methods return the default value for brevity.
+  # A real provider would look up each flag_key in its flag management system.
+  def fetch_string_value(flag_key:, default_value:, evaluation_context: nil)
+    OpenFeature::SDK::Provider::ResolutionDetails.new(value: default_value)
+  end
+
+  def fetch_number_value(flag_key:, default_value:, evaluation_context: nil)
+    OpenFeature::SDK::Provider::ResolutionDetails.new(value: default_value)
+  end
+
+  def fetch_integer_value(flag_key:, default_value:, evaluation_context: nil)
+    OpenFeature::SDK::Provider::ResolutionDetails.new(value: default_value)
+  end
+
+  def fetch_float_value(flag_key:, default_value:, evaluation_context: nil)
+    OpenFeature::SDK::Provider::ResolutionDetails.new(value: default_value)
+  end
+
+  def fetch_object_value(flag_key:, default_value:, evaluation_context: nil)
+    OpenFeature::SDK::Provider::ResolutionDetails.new(value: default_value)
+  end
+end
+
+OpenFeature::SDK.configure do |config|
+  config.set_provider(MyProvider.new)
+end
+
+client = OpenFeature::SDK.build_client
+puts client.fetch_boolean_value(flag_key: "any_flag", default_value: false)
diff --git a/examples/rails_integration.rb b/examples/rails_integration.rb
@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Example: OpenFeature integration with Ruby on Rails
+#
+# This file demonstrates how you might integrate OpenFeature into a Rails app.
+# It is not runnable standalone — it shows patterns for use in a Rails context.
+
+# config/initializers/openfeature.rb
+#
+# OpenFeature::SDK.configure do |config|
+#   config.set_provider(YourProvider.new)
+#
+#   # Set global context with server-level info
+#   config.evaluation_context = OpenFeature::SDK::EvaluationContext.new(
+#     "environment" => Rails.env,
+#     "service" => "my-rails-app"
+#   )
+#
+#   # Use thread-local transaction context for per-request data
+#   config.set_transaction_context_propagator(
+#     OpenFeature::SDK::ThreadLocalTransactionContextPropagator.new
+#   )
+# end
+
+# app/middleware/openfeature_context_middleware.rb
+#
+# class OpenFeatureContextMiddleware
+#   def initialize(app)
+#     @app = app
+#   end
+#
+#   def call(env)
+#     request = ActionDispatch::Request.new(env)
+#     OpenFeature::SDK.set_transaction_context(
+#       OpenFeature::SDK::EvaluationContext.new(
+#         targeting_key: request.session[:user_id]&.to_s,
+#         "ip" => request.remote_ip,
+#         "user_agent" => request.user_agent
+#       )
+#     )
+#     @app.call(env)
+#   ensure
+#     # Clear context to prevent leakage in threaded servers (e.g. Puma)
+#     OpenFeature::SDK.set_transaction_context(nil)
+#   end
+# end
+
+# app/controllers/application_controller.rb
+#
+# class ApplicationController < ActionController::Base
+#   private
+#
+#   def feature_client
+#     @feature_client ||= OpenFeature::SDK.build_client(domain: "web")
+#   end
+#
+#   def feature_enabled?(flag_key)
+#     feature_client.fetch_boolean_value(flag_key: flag_key, default_value: false)
+#   end
+# end
diff --git a/openfeature-sdk.gemspec b/openfeature-sdk.gemspec
@@ -9,16 +9,17 @@ Gem::Specification.new do |spec|
   spec.email = ["cncf-openfeature-contributors@lists.cncf.io"]
 
   spec.summary = "OpenFeature SDK for Ruby"
-  spec.description = "Ruby SDK for an the specifications for the open standard of feature flag management"
-  spec.homepage = "https://github.com/open-feature/openfeature-ruby"
+  spec.description = "Ruby SDK for the OpenFeature specification, an open standard for feature flag management"
+  spec.homepage = "https://github.com/open-feature/ruby-sdk"
   spec.license = "Apache-2.0"
   spec.required_ruby_version = ">= 3.4"
 
   spec.metadata["homepage_uri"] = spec.homepage
-  spec.metadata["source_code_uri"] = "https://github.com/open-feature/openfeature-ruby"
-  spec.metadata["changelog_uri"] = "https://github.com/open-feature/openfeature-ruby/blob/main/CHANGELOG.md"
-  spec.metadata["bug_tracker_uri"] = "https://github.com/open-feature/openfeature-ruby/issues"
-  spec.metadata["documentation_uri"] = "https://github.com/open-feature/openfeature-ruby/README.md"
+  spec.metadata["source_code_uri"] = "https://github.com/open-feature/ruby-sdk"
+  spec.metadata["changelog_uri"] = "https://github.com/open-feature/ruby-sdk/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/open-feature/ruby-sdk/issues"
+  spec.metadata["documentation_uri"] = "https://github.com/open-feature/ruby-sdk#readme"
+  spec.metadata["rubygems_mfa_required"] = "true"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
@@ -30,14 +31,4 @@ Gem::Specification.new do |spec|
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
-
-  spec.add_development_dependency "debug"
-  spec.add_development_dependency "markly"
-  spec.add_development_dependency "rake", "~> 13.0"
-  spec.add_development_dependency "rspec", "~> 3.12.0"
-  spec.add_development_dependency "standard"
-  spec.add_development_dependency "standard-performance"
-  spec.add_development_dependency "simplecov", "~> 0.22.0"
-  spec.add_development_dependency "simplecov-cobertura", "~> 3.0"
-  spec.add_development_dependency "timecop", "~> 0.9.10"
 end
