rollout 3.2.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cadea20a7d731c5538e5d6b6b19b34075843230fd5c6d75ffc4c269ce667a63f
-  data.tar.gz: '06483d373ff87c4e0537ab73d57be5bba089d43a4abacd87168bdf338cb4ca5e'
+  metadata.gz: ecf20a456dab296cc321049b845972bff0c72075e4bb7e30e2e5314e33cff1b2
+  data.tar.gz: d66bce69c2ec03dc790f922635501b970b790886281651708b98fd133d6c3c3e
 SHA512:
-  metadata.gz: 515d4d646e3c4c2c2fee20d77088a9dd22fe5730dd605764abfbc0e189591f7eaaf076830940358500e05eed30f456b9389f8843bad1df283d01b795eae6e935
-  data.tar.gz: c41503b0e1acff3c3c99de9b08d7c06167f2d4a2f7c7fc493230c11c70f633dcae0bc4c5a7028d04e11b01dfd7edfb6eaaf6d33255c559cd4b93fda206e10427
+  metadata.gz: dddafc84d403c006b8aafe0ef961b9a883b192a7ba1e4d7816a28bf72c38b60c86b7c86e5e6d10a9a8fa5921b5d8493361023553aecb455f6e2c954eed4bacdd
+  data.tar.gz: 1b2de6537a44270239c74d403051eac56cad4580fb995beaaedef5597e354cb7f839cca9b581f814d25451454f0ebfeaa16e0f2ca1e21469106c3413fa4cdee8

data/.github/workflows/release.yml

@@ -10,14 +10,16 @@ on:
 permissions:
   contents: write
   id-token: write
+  pull-requests: read
 
 jobs:
   publish:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     outputs:
       name: ${{ steps.package.outputs.name }}
       version: ${{ steps.package.outputs.version }}
       previous_tag: ${{ steps.package.outputs.previous_tag }}
+      paths: ${{ steps.package.outputs.paths }}
     steps:
       - name: Checkout code
         uses: actions/checkout@v5
@@ -31,9 +33,9 @@ jobs:
         id: package
         run: |
           case "$GITHUB_REF_NAME" in
-            rollout/v*) name=rollout; directory=. ;;
-            rollout-redis-adapter/v*) name=rollout-redis-adapter; directory=rollout-redis-adapter ;;
-            rollout-active_record-adapter/v*) name=rollout-active_record-adapter; directory=rollout-active_record-adapter ;;
+            rollout/v*) name=rollout; directory=.; paths="lib rollout.gemspec" ;;
+            rollout-redis-adapter/v*) name=rollout-redis-adapter; directory=rollout-redis-adapter; paths=rollout-redis-adapter ;;
+            rollout-active_record-adapter/v*) name=rollout-active_record-adapter; directory=rollout-active_record-adapter; paths=rollout-active_record-adapter ;;
             *) echo "Unexpected tag $GITHUB_REF_NAME" >&2; exit 1 ;;
           esac
           version="${GITHUB_REF_NAME##*/v}"
@@ -48,6 +50,7 @@ jobs:
           echo "version=$version" >> "$GITHUB_OUTPUT"
           echo "directory=$directory" >> "$GITHUB_OUTPUT"
           echo "previous_tag=$previous_tag" >> "$GITHUB_OUTPUT"
+          echo "paths=$paths" >> "$GITHUB_OUTPUT"
       - name: Build selected gem
         working-directory: ${{ steps.package.outputs.directory }}
         run: gem build "${{ steps.package.outputs.name }}.gemspec"
@@ -59,14 +62,37 @@ jobs:
 
   github-release:
     needs: publish
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      # GitHub's generated notes list every PR in the repo between tags; keep
+      # only PRs that touched the released gem's files.
+      - name: Build release notes
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PREVIOUS_TAG: ${{ needs.publish.outputs.previous_tag }}
+          PATHS: ${{ needs.publish.outputs.paths }}
+        run: |
+          {
+            echo "## What's Changed"
+            git log --reverse --format=%H "$PREVIOUS_TAG..$GITHUB_REF_NAME" -- $PATHS |
+              while read -r sha; do
+                gh api "repos/$GITHUB_REPOSITORY/commits/$sha/pulls" \
+                  --jq '.[] | "* \(.title) by @\(.user.login) in \(.html_url)"'
+              done |
+              awk '!seen[$0]++'
+            echo
+            echo "**Full Changelog**: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/compare/$PREVIOUS_TAG...$GITHUB_REF_NAME"
+          } > release-notes.md
+          cat release-notes.md
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v3
         with:
           tag_name: ${{ github.ref }}
           name: ${{ needs.publish.outputs.name }} ${{ needs.publish.outputs.version }}
-          generate_release_notes: true
-          previous_tag: ${{ needs.publish.outputs.previous_tag }}
+          body_path: release-notes.md
           draft: false
           prerelease: false

data/.github/workflows/test.yml

@@ -10,18 +10,24 @@ on:
 
 jobs:
   core:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
+    # setup-ruby has no Ruby 3.1 or older builds for ubuntu-26.04, so use the official Ruby images.
+    container: ruby:${{ matrix.ruby-version }}
     strategy:
       matrix:
         ruby-version: ['3.3', '3.2', '3.1', '3.0', '2.7', '2.6', '2.5', '2.4']
     steps:
       - name: Checkout code
         uses: actions/checkout@v5
-      - name: Setup Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: ${{ matrix.ruby-version }}
-          bundler-cache: true
+      - name: Install Bundler
+        # The Ruby 2.7 and older images ship Bundler 1.17 or 2.1; install the versions setup-ruby used.
+        run: |
+          case "$RUBY_VERSION" in
+            2.4.*|2.5.*) gem install bundler -v '~> 2.3.0' ;;
+            2.6.*|2.7.*) gem install bundler -v '~> 2.4.0' ;;
+          esac
+      - name: Install gems
+        run: bundle install --jobs 4
       - name: Run core tests
         run: |
           mkdir -p test_results
@@ -35,15 +41,17 @@ jobs:
           retention-days: 30
 
   redis:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
+    # setup-ruby has no Ruby 3.1 or older builds for ubuntu-26.04, so use the official Ruby images.
+    container: ruby:${{ matrix.ruby-version }}
     strategy:
       matrix:
         ruby-version: ['3.3', '3.2', '3.1', '3.0', '2.7', '2.6', '2.5', '2.4']
+    env:
+      REDIS_HOST: redis
     services:
       redis:
         image: redis:7-alpine
-        ports:
-          - 6379:6379
         options: >-
           --health-cmd "redis-cli ping"
           --health-interval 10s
@@ -52,12 +60,16 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v5
-      - name: Setup Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: ${{ matrix.ruby-version }}
-          working-directory: rollout-redis-adapter
-          bundler-cache: true
+      - name: Install Bundler
+        # The Ruby 2.7 and older images ship Bundler 1.17 or 2.1; install the versions setup-ruby used.
+        run: |
+          case "$RUBY_VERSION" in
+            2.4.*|2.5.*) gem install bundler -v '~> 2.3.0' ;;
+            2.6.*|2.7.*) gem install bundler -v '~> 2.4.0' ;;
+          esac
+      - name: Install gems
+        working-directory: rollout-redis-adapter
+        run: bundle install --jobs 4
       - name: Run Redis adapter tests
         working-directory: rollout-redis-adapter
         run: |
@@ -72,7 +84,9 @@ jobs:
           retention-days: 30
 
   active_record:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
+    # setup-ruby has no Ruby 3.1 or older builds for ubuntu-26.04, so use the official Ruby images.
+    container: ruby:${{ matrix.ruby-version }}
     strategy:
       fail-fast: false
       matrix:
@@ -104,20 +118,18 @@ jobs:
     env:
       ACTIVERECORD_VERSION: ${{ matrix.activerecord }}
       ROLLOUT_AR_ADAPTER: ${{ matrix.db }}
-      POSTGRES_HOST: localhost
+      POSTGRES_HOST: postgres
       POSTGRES_USER: postgres
       POSTGRES_PASSWORD: postgres
       POSTGRES_DB: rollout_test
-      MYSQL_HOST: 127.0.0.1
+      MYSQL_HOST: mysql
       MYSQL_USER: root
       MYSQL_PASSWORD: root
       MYSQL_DATABASE: rollout_test
-      REDIS_HOST: 127.0.0.1
+      REDIS_HOST: redis
     services:
       redis:
         image: redis:7-alpine
-        ports:
-          - 6379:6379
         options: >-
           --health-cmd "redis-cli ping"
           --health-interval 10s
@@ -129,8 +141,6 @@ jobs:
           POSTGRES_USER: postgres
           POSTGRES_PASSWORD: postgres
           POSTGRES_DB: rollout_test
-        ports:
-          - 5432:5432
         options: >-
           --health-cmd "pg_isready -U postgres"
           --health-interval 10s
@@ -141,8 +151,6 @@ jobs:
         env:
           MYSQL_ROOT_PASSWORD: root
           MYSQL_DATABASE: rollout_test
-        ports:
-          - 3306:3306
         options: >-
           --health-cmd "mysqladmin ping -h 127.0.0.1 -uroot -proot"
           --health-interval 10s
@@ -151,15 +159,16 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v5
-      - name: Install database client libraries
-        run: sudo apt-get update && sudo apt-get install -y libpq-dev default-libmysqlclient-dev
-      - name: Setup Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: ${{ matrix.ruby-version }}
-          working-directory: rollout-active_record-adapter
-          bundler-cache: true
-          cache-version: ar-${{ matrix.ruby-version }}-${{ matrix.activerecord }}-${{ matrix.db }}
+      - name: Install Bundler
+        # The Ruby 2.7 and older images ship Bundler 1.17 or 2.1; install the versions setup-ruby used.
+        run: |
+          case "$RUBY_VERSION" in
+            2.4.*|2.5.*) gem install bundler -v '~> 2.3.0' ;;
+            2.6.*|2.7.*) gem install bundler -v '~> 2.4.0' ;;
+          esac
+      - name: Install gems
+        working-directory: rollout-active_record-adapter
+        run: bundle install --jobs 4
       - name: Run Active Record adapter tests
         working-directory: rollout-active_record-adapter
         run: |

data/README.md

@@ -184,6 +184,63 @@ feature.to_hash
 # => { percentage: 5.0, groups: [:caretakers], users: ["1"], data: {} }
 ```
 
+## Defining features
+
+Describe each feature in its own YAML file, named after the feature. Rollout
+looks in `config/rollouts` under the current directory, which is your app's
+root when you start it from there.
+
+```text
+config/rollouts/
+├── chat.yml
+└── new_inbox.yml
+```
+
+Only `.yml` files directly in that folder are read. Subfolders, `.yaml` files
+and files starting with a dot are ignored. The file name without `.yml` is the
+feature name, the same one you pass to `$rollout.active?`.
+
+```yaml
+# config/rollouts/chat.yml
+description: Let members chat in groups.
+```
+
+```yaml
+# config/rollouts/new_inbox.yml
+description: Show conversations as threads.
+owner: messaging
+release_date: "2026-11-15"
+```
+
+```ruby
+Rollout.definitions.keys                      # => [:chat, :new_inbox]
+Rollout.definitions[:new_inbox].description   # => "Show conversations as threads."
+Rollout.definitions[:new_inbox].path          # => "/app/config/rollouts/new_inbox.yml"
+Rollout.definitions[:new_inbox].attributes
+# => { "description" => "Show conversations as threads.", "owner" => "messaging", "release_date" => "2026-11-15" }
+```
+
+Definitions only describe features: they don't create or change stored
+features, and features without a file work as before. Rollout reads
+`description`. Every key, including your own like `owner`, is kept in
+`attributes` with string keys for your application.
+
+`Rollout.definitions` reads the folder on every call. A missing folder means no
+definitions. `description` is optional.
+
+Files are read with `YAML.safe_load`, so values can be strings, numbers,
+booleans, `null`, lists and mappings. Quote dates and times
+(`release_date: "2026-10-28"`). A file raises `Rollout::InvalidDefinition` if
+it isn't valid YAML, isn't a mapping, uses anything else (an unquoted date, an
+alias, a `:symbol`), or sets `description` to something other than a string.
+
+Use another folder, or turn definitions off:
+
+```ruby
+Rollout.definitions_path = Rails.root.join("config", "features")
+Rollout.definitions_path = nil
+```
+
 ## Namespacing
 
 Rollout separates its keys from other keys in the data store using the

data/lib/rollout/definition.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+class Rollout
+  class InvalidDefinition < ArgumentError
+  end
+
+  class Definition
+    attr_reader :name, :path, :description, :attributes
+
+    def self.load(path)
+      attributes = YAML.safe_load(File.read(path))
+      raise InvalidDefinition, "#{path}: definition must be a mapping" unless attributes.is_a?(Hash)
+
+      new(name: File.basename(path, '.yml'), attributes: attributes, path: path)
+    rescue Psych::Exception => e
+      raise InvalidDefinition, "#{path}: #{e.message}"
+    end
+
+    def initialize(name:, attributes: {}, path: nil)
+      @name = name.to_sym
+      @path = path
+      @attributes = attributes.freeze
+      @description = attributes['description']
+      return if @description.nil? || @description.is_a?(String)
+
+      raise InvalidDefinition, "#{path || name}: description must be a string"
+    end
+  end
+end

data/lib/rollout/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Rollout
-  VERSION = '3.2.0'
+  VERSION = '3.3.0'
 end

data/lib/rollout.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'rollout/definition'
 require 'rollout/feature'
 require 'rollout/logging'
 require 'rollout/version'
@@ -13,6 +14,28 @@ class Rollout
 
   RAND_BASE = (2**32 - 1) / 100.0
 
+  class << self
+    attr_writer :definitions_path
+
+    def definitions_path
+      return @definitions_path if defined?(@definitions_path)
+
+      File.expand_path(File.join('config', 'rollouts'))
+    end
+
+    # Reads the folder on every call, so new files show up without a restart.
+    def definitions
+      folder = definitions_path&.to_s
+      return {} unless folder && File.directory?(folder)
+
+      # Dir.entries rather than a glob, so brackets or asterisks in the folder's path are taken literally.
+      Dir.entries(folder).grep(/\A[^.].*\.yml\z/).sort.each_with_object({}) do |file, definitions|
+        definition = Definition.load(File.join(folder, file))
+        definitions[definition.name] = definition
+      end
+    end
+  end
+
   attr_reader :options, :adapter
 
   def initialize(adapter:, **options)

data/spec/rollout/definition_spec.rb

@@ -0,0 +1,83 @@
+require "spec_helper"
+require "tmpdir"
+
+RSpec.describe "Rollout.definitions" do
+  around do |example|
+    Dir.mktmpdir do |dir|
+      @dir = dir
+      example.run
+    end
+  end
+
+  after do
+    Rollout.send(:remove_instance_variable, :@definitions_path) if Rollout.instance_variable_defined?(:@definitions_path)
+  end
+
+  def write(name, content)
+    File.write(File.join(@dir, name), content)
+  end
+
+  it "loads each .yml file directly in the folder, named after the file" do
+    write("chat.yml", "description: Group chat.\ncache: user\n")
+    write("notes.yaml", "description: Not loaded.\n")
+    FileUtils.mkdir_p(File.join(@dir, "drafts"))
+    write("drafts/inbox.yml", "description: Not loaded.\n")
+    Rollout.definitions_path = @dir
+
+    chat = Rollout.definitions.fetch(:chat)
+
+    expect(Rollout.definitions.keys).to eq [:chat]
+    expect(chat.description).to eq "Group chat."
+    expect(chat.attributes).to eq("description" => "Group chat.", "cache" => "user")
+    expect(chat.path).to eq File.join(@dir, "chat.yml")
+  end
+
+  it "defaults to config/rollouts under the current directory" do
+    folder = File.join(@dir, "config", "rollouts")
+    FileUtils.mkdir_p(folder)
+    File.write(File.join(folder, "chat.yml"), "description: Group chat.\n")
+
+    Dir.chdir(@dir) do
+      expect(Rollout.definitions.keys).to eq [:chat]
+    end
+  end
+
+  it "picks up a file added after an earlier call" do
+    Rollout.definitions_path = @dir
+    expect(Rollout.definitions).to eq({})
+
+    write("chat.yml", "description: Group chat.\n")
+    expect(Rollout.definitions.keys).to eq [:chat]
+  end
+
+  it "takes brackets in the folder's path literally" do
+    folder = File.join(@dir, "rollouts[1]")
+    FileUtils.mkdir_p(folder)
+    File.write(File.join(folder, "chat.yml"), "description: Group chat.\n")
+    Rollout.definitions_path = folder
+
+    expect(Rollout.definitions.keys).to eq [:chat]
+  end
+
+  it "has no definitions when the folder is missing or the path is nil" do
+    Rollout.definitions_path = File.join(@dir, "missing")
+    expect(Rollout.definitions).to eq({})
+
+    Rollout.definitions_path = nil
+    expect(Rollout.definitions).to eq({})
+  end
+
+  it "names the file that is not valid YAML" do
+    write("chat.yml", "description: [unclosed\n")
+    Rollout.definitions_path = @dir
+
+    expect { Rollout.definitions }.to raise_error(Rollout::InvalidDefinition, /chat\.yml/)
+  end
+
+  it "rejects a description that is not a string" do
+    write("chat.yml", "description: 42\n")
+    Rollout.definitions_path = @dir
+
+    expect { Rollout.definitions }.to raise_error(Rollout::InvalidDefinition, /description must be a string/)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rollout
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.3.0
 platform: ruby
 authors:
 - James Golick
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-01 00:00:00.000000000 Z
+date: 2026-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: observer
@@ -142,11 +142,13 @@ files:
 - Rakefile
 - docs/upgrading-to-v3.md
 - lib/rollout.rb
+- lib/rollout/definition.rb
 - lib/rollout/feature.rb
 - lib/rollout/feature_state.rb
 - lib/rollout/logging.rb
 - lib/rollout/version.rb
 - rollout.gemspec
+- spec/rollout/definition_spec.rb
 - spec/rollout/feature_spec.rb
 - spec/rollout/feature_state_spec.rb
 - spec/rollout/logging_spec.rb