redis-objects-periodical 0.7.0 → 0.8.0

data/README.md

@@ -1,263 +1,100 @@
-[![CircleCI](https://circleci.com/gh/ryz310/redis-objects-periodical.svg?style=svg)](https://circleci.com/gh/ryz310/redis-objects-periodical) [![Gem Version](https://badge.fury.io/rb/redis-objects-periodical.svg)](https://badge.fury.io/rb/redis-objects-periodical) [![Maintainability](https://api.codeclimate.com/v1/badges/deebb6c406c306a6f337/maintainability)](https://codeclimate.com/github/ryz310/redis-objects-periodical/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/deebb6c406c306a6f337/test_coverage)](https://codeclimate.com/github/ryz310/redis-objects-periodical/test_coverage)
+[![CI](https://github.com/ryz310/redis-objects-periodical/actions/workflows/ci.yml/badge.svg)](https://github.com/ryz310/redis-objects-periodical/actions/workflows/ci.yml) [![Gem Version](https://badge.fury.io/rb/redis-objects-periodical.svg)](https://badge.fury.io/rb/redis-objects-periodical)
+[![Maintainability](https://qlty.sh/gh/ryz310/projects/redis-objects-periodical/maintainability.svg)](https://qlty.sh/gh/ryz310/projects/redis-objects-periodical)
+[![Code Coverage](https://qlty.sh/gh/ryz310/projects/redis-objects-periodical/coverage.svg)](https://qlty.sh/gh/ryz310/projects/redis-objects-periodical)
 
 # Redis::Objects::Periodical
 
-This is a gem which extends [Redis::Objects](https://github.com/nateware/redis-objects) gem. Once install this gem, you can use the periodical counter, the periodical set, etc. in addition to the standard features of Redis::Objects. These counters and sets are useful for measuring conversions, implementing API rate limiting, MAU, DAU, and more.
+Extend [Redis::Objects](https://github.com/nateware/redis-objects) with counters,
+values, sets, and hashes whose Redis keys are partitioned by period. Use them for
+page views, active-user counts, rate-limiting data, and other periodical values.
 
 ## Installation
 
+Ruby 3.3 or newer is required. Ruby 3.3, 3.4, and 4.0 are tested in CI.
+The support policy follows stable Ruby branches receiving official normal or
+security maintenance; preview releases are not supported. CI uses the latest
+patch releases available in each supported series' CircleCI Ruby image.
+See [Ruby's maintenance status](https://www.ruby-lang.org/en/downloads/branches/).
+
+Ruby 2.7, 3.0, 3.1, and 3.2 are no longer supported. Applications using those
+versions must upgrade Ruby before upgrading this gem, or remain on the last gem
+release whose `required_ruby_version` permits their Ruby version.
+
 Add this line to your application's Gemfile:
 
 ```ruby
 gem 'redis-objects-periodical'
 ```
 
-If you want to know about installation and standard usage, please see Redis::Objects' GitHub page.
+## Quick start
 
-## Usage
+Configure the Redis connection as described in
+[Redis::Objects](https://github.com/nateware/redis-objects), then declare a field:
 
-`daily_counter` and `daily_set` automatically creates keys that are unique to each object, in the format:
-
-```
-model_name:id:field_name:yyyy-mm-dd
-```
-
-I recommend using with `expireat` option.
-For illustration purposes, consider this stub class:
+```ruby
+require 'redis-objects-periodical'
 
-```rb
 class Homepage
   include Redis::Objects
 
   daily_counter :pv, expireat: -> { Time.now + 2_678_400 } # about a month
-  daily_hash_key :browsing_history, expireat: -> { Time.now + 2_678_400 } # about a month
-  daily_set :dau, expireat: -> { Time.now + 2_678_400 } # about a month
-  daily_value :cache, expireat: -> { Time.now + 2_678_400 } # about a month
 
   def id
     1
   end
 end
 
-# 2021-04-01
 homepage = Homepage.new
-homepage.id # 1
-
-homepage.pv.increment
-homepage.pv.increment
-homepage.pv.increment
-puts homepage.pv.value # 3
-
-# 2021-04-02 (next day)
-puts homepage.pv.value # 0
-homepage.pv.increment
-homepage.pv.increment
-puts homepage.pv.value # 2
-
-start_date = Date.new(2021, 4, 1)
-end_date = Date.new(2021, 4, 2)
-homepage.pv.range(start_date, end_date) # [3, 2]
-```
-
-### Periodical Counters
-
-The periodical counters automatically switches the save destination when the date changes.
-You can access past dates counted values like Ruby arrays:
-
-```rb
-# 2021-04-01
+# On 2021-04-01:
 homepage.pv.increment(3)
+homepage.pv.value # => 3
 
-# 2021-04-02 (next day)
+# On 2021-04-02, calling the field accessor selects the new day's key:
+homepage.pv.value # => 0
 homepage.pv.increment(2)
-
-# 2021-04-03 (next day)
-homepage.pv.increment(5)
-
-homepage.pv[Date.new(2021, 4, 1)] # => 3
-homepage.pv[Date.new(2021, 4, 1), 3] # => [3, 2, 5]
-homepage.pv[Date.new(2021, 4, 1)..Date.new(2021, 4, 2)] # => [3, 2]
-
-homepage.pv.delete_at(Date.new(2021, 4, 1))
-homepage.pv.range(Date.new(2021, 4, 1), Date.new(2021, 4, 3)) # => [0, 2, 5]
-homepage.pv.at(Date.new(2021, 4, 2)) # => #<Redis::Counter key="homepage:1:pv:2021-04-02">
-homepage.pv.at(Date.new(2021, 4, 2)).value # 2
+homepage.pv.range(Date.new(2021, 4, 1), Date.new(2021, 4, 2)) # => [3, 2]
 ```
 
-#### Periodical Counters Family
-
-- `annual_counter`
-  - Key format: `model_name:id:field_name:yyyy`
-  - Redis is a highly volatile key-value store, so I don't recommend using it.
-- `monthly_counter`
-  - Key format: `model_name:id:field_name:yyyy-mm`
-- `weekly_counter`
-  - Key format: `model_name:id:field_name:yyyyWw`
-- `daily_counter`
-  - Key format: `model_name:id:field_name:yyyy-mm-dd`
-- `hourly_counter`
-  - Key format: `model_name:id:field_name:yyyy-mm-ddThh`
-- `minutely_counter`
-  - Key format: `model_name:id:field_name:yyyy-mm-ddThh:mi`
-
-### Periodical Values
-
-The periodical values automatically switches the save destination when the date changes.
-
-```rb
-# 2021-04-01
-homepage.cache.value = 'a'
-
-# 2021-04-02 (next day)
-homepage.cache.value = 'b'
-
-# 2021-04-03 (next day)
-homepage.cache.value = 'c'
-
-homepage.cache[Date.new(2021, 4, 1)] # => 'a'
-homepage.cache[Date.new(2021, 4, 1), 3] # => ['a', 'b', 'c']
-homepage.cache[Date.new(2021, 4, 1)..Date.new(2021, 4, 2)] # => ['a', 'b']
-
-homepage.cache.delete_at(Date.new(2021, 4, 1))
-homepage.cache.range(Date.new(2021, 4, 1), Date.new(2021, 4, 3)) # => [nil, 'b', 'c']
-homepage.cache.at(Date.new(2021, 4, 2)) # => #<Redis::Value key="homepage:1:cache:2021-04-02">
-homepage.cache.at(Date.new(2021, 4, 2)).value # 'b'
-```
+Keys are unique to the model, its ID, field, and period. This daily counter uses
+`homepage:1:pv:2021-04-01`. Each field accessor creates a new periodical object;
+an object retained in a variable keeps its original key across period boundaries.
+Use an appropriate expiration option to limit retained period keys.
 
-#### Periodical Values Family
+## Available periods and types
 
-- `annual_value`
-  - Key format: `model_name:id:field_name:yyyy`
-  - Redis is a highly volatile key-value store, so I don't recommend using it.
-- `monthly_value`
-  - Key format: `model_name:id:field_name:yyyy-mm`
-- `weekly_value`
-  - Key format: `model_name:id:field_name:yyyyWw`
-- `daily_value`
-  - Key format: `model_name:id:field_name:yyyy-mm-dd`
-- `hourly_value`
-  - Key format: `model_name:id:field_name:yyyy-mm-ddThh`
-- `minutely_value`
-  - Key format: `model_name:id:field_name:yyyy-mm-ddThh:mi`
+Combine one of `annual`, `monthly`, `weekly`, `daily`, `hourly`, or `minutely`
+with one of these field types:
 
-### Periodical Hashes
+| Type | Daily declaration | Single-period result | Multi-period result |
+| --- | --- | --- | --- |
+| Counter | `daily_counter` | Integer, missing as `0` | Array of integers |
+| Value | `daily_value` | Stored value, missing as `nil` | Array of values |
+| Set | `daily_set` | Members, missing as `[]` | Union of members |
+| Hash | `daily_hash_key` | Hash, missing as `{}` | Hash with combined field values |
 
-The periodical hashes also automatically switches the save destination when the date changes.
+See the [usage guide](docs/usage.md) for declarations, key suffixes, weekly
+year-boundary behavior, date/time arguments, aggregation, expiration, and timezone
+selection. Rails/ActiveSupport is optional.
 
-```rb
-# 2021-04-01
-homepage.browsing_history.incr('item1')
-homepage.browsing_history.incr('item2')
-homepage.browsing_history.incr('item2')
-puts homepage.browsing_history.all # { 'item1' => '1', 'item2' => '2' }
+## Development and maintenance
 
-# 2021-04-02 (next day)
-puts homepage.browsing_history.all # {}
-
-homepage.browsing_history.bulk_set('item1' => 3, 'item3' => 5)
-puts homepage.browsing_history.all # { 'item1' => '3', 'item3' => '5' }
-
-# 2021-04-03 (next day)
-homepage.browsing_history.incr('item2')
-homepage.browsing_history.incr('item4')
-puts homepage.browsing_history.all # { 'item2' => '1', 'item4' => '1' }
-
-homepage.browsing_history[Date.new(2021, 4, 1)] # => { 'item1' => '1', 'item2' => '2' }
-homepage.browsing_history[Date.new(2021, 4, 1), 3] # => { 'item1' => '4', 'item2' => '3', 'item3' => '5', 'item4' => '1' }
-homepage.browsing_history[Date.new(2021, 4, 1)..Date.new(2021, 4, 2)] # => { 'item1' => '4', 'item2' => '2', 'item3' => '5' }
-
-homepage.browsing_history.delete_at(Date.new(2021, 4, 1))
-homepage.browsing_history.range(Date.new(2021, 4, 1), Date.new(2021, 4, 3)) # => { 'item1' => '3', 'item2' => '1', 'item3' => '5', 'item4' => '1' }
-homepage.browsing_history.at(Date.new(2021, 4, 2)) # => #<Redis::HashKey key="homepage:1:browsing_history:2021-04-02">
-homepage.browsing_history.at(Date.new(2021, 4, 2)).all # { 'item1' => '3', 'item3' => '5' }
-```
-
-#### Periodical Hashes Family
-
-- `annual_hash_key`
-  - Key format: `model_name:id:field_name:yyyy`
-  - Redis is a highly volatile key-value store, so I don't recommend using it.
-- `monthly_hash_key`
-  - Key format: `model_name:id:field_name:yyyy-mm`
-- `weekly_hash_key`
-  - Key format: `model_name:id:field_name:yyyyWw`
-- `daily_hash_key`
-  - Key format: `model_name:id:field_name:yyyy-mm-dd`
-- `hourly_hash_key`
-  - Key format: `model_name:id:field_name:yyyy-mm-ddThh`
-- `minutely_hash_key`
-  - Key format: `model_name:id:field_name:yyyy-mm-ddThh:mi`
-
-### Periodical Sets
-
-The periodical sets also automatically switches the save destination when the date changes.
-
-```rb
-# 2021-04-01
-homepage.dau << 'user1'
-homepage.dau << 'user2'
-homepage.dau << 'user1' # dup ignored
-puts homepage.dau.members # ['user1', 'user2']
-puts homepage.dau.length # 2
-puts homepage.dau.count # alias of #length
-
-# 2021-04-02 (next day)
-puts homepage.dau.members # []
-
-homepage.dau.merge('user2', 'user3')
-puts homepage.dau.members # ['user2', 'user3']
-
-# 2021-04-03 (next day)
-homepage.dau.merge('user4')
-
-homepage.dau[Date.new(2021, 4, 1)] # => ['user1', 'user2']
-homepage.dau[Date.new(2021, 4, 1), 3] # => ['user1', 'user2', 'user3', 'user4']
-homepage.dau[Date.new(2021, 4, 1)..Date.new(2021, 4, 2)] # => ['user1', 'user2', 'user3']
-
-homepage.dau.delete_at(Date.new(2021, 4, 1))
-homepage.dau.range(Date.new(2021, 4, 1), Date.new(2021, 4, 3)) # => ['user2', 'user3', 'user4']
-homepage.dau.at(Date.new(2021, 4, 2)) # => #<Redis::Set key="homepage:1:dau:2021-04-02">
-homepage.dau.at(Date.new(2021, 4, 2)).members # ['user2', 'user3']
-```
-
-#### Periodical Sets Family
-
-- `annual_set`
-  - Key format: `model_name:id:field_name:yyyy`
-  - Redis is a highly volatile key-value store, so I don't recommend using it.
-- `monthly_set`
-  - Key format: `model_name:id:field_name:yyyy-mm`
-- `weekly_set`
-  - Key format: `model_name:id:field_name:yyyyWw`
-- `daily_set`
-  - Key format: `model_name:id:field_name:yyyy-mm-dd`
-- `hourly_set`
-  - Key format: `model_name:id:field_name:yyyy-mm-ddThh`
-- `minutely_set`
-  - Key format: `model_name:id:field_name:yyyy-mm-ddThh:mi`
-
-### Timezone
-
-This gem follows Ruby process' time zone, but if you extends Time class by ActiveSupport (e.g. `Time.current`), follows Rails process' timezone.
-
-## Development
-
-The development environment for this gem is configured with docker-compose.
-Please use the following command:
-
-    $ docker-compose up -d
-    $ docker-compose run --rm ruby bundle
-    $ docker-compose run --rm ruby rspec .
-    $ docker-compose run --rm ruby rubocop -a
+- [Contributing](CONTRIBUTING.md): Docker setup, isolated Compose projects,
+  specs, lint, builds, CI, and optional ActiveSupport verification.
+- [Maintaining](docs/maintaining.md): dependency updates, auto-merge, coverage
+  configuration, releases, scheduled maintenance, and CircleCI cutover/rollback.
+- [Agent guidance](AGENTS.md): repository workflow and compatibility constraints.
+- [Changelog](CHANGELOG.md): released changes.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/redis-objects-periodical. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/redis-objects-periodical/blob/master/CODE_OF_CONDUCT.md).
-
-## License
-
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/ryz310/redis-objects-periodical).
+Track unresolved bugs, improvements, and decisions in
+[GitHub Issues](https://github.com/ryz310/redis-objects-periodical/issues).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow.
 
-## Code of Conduct
+## License and code of conduct
 
-Everyone interacting in the Redis::Objects::Daily::Counter project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/redis-objects-periodical/blob/master/CODE_OF_CONDUCT.md).
+The gem is available under the [MIT License](LICENSE.txt).
+Everyone interacting with the Redis::Objects::Periodical project is expected to
+follow the [code of conduct](CODE_OF_CONDUCT.md).

data/docker-compose.yml

@@ -9,9 +9,7 @@ services:
       - .:/my_app
       - bundle:/usr/local/bundle
   redis:
-    image: redis:latest
-    ports:
-      - 6379:6379
+    image: redis:latest@sha256:97ec88159e6d7cfb5ddef9015386087d58a912de80112f06ebdfa78fa5989901
 
 volumes:
   bundle:

data/docs/maintaining.md

@@ -0,0 +1,237 @@
+# Maintaining
+
+See [Contributing](../CONTRIBUTING.md) for development and test commands.
+Keep unresolved work in [GitHub Issues](https://github.com/ryz310/redis-objects-periodical/issues).
+This guide describes procedures; it does not certify that external settings or
+CircleCI cutover have been completed.
+
+## Coverage reporting
+
+To enable coverage reporting to Qlty, enable this repository in Qlty Cloud and
+register a dedicated project coverage token as the GitHub Actions repository
+secret `QLTY_COVERAGE_TOKEN`. Keep secret variables unavailable to fork and
+Dependabot pull requests. When the token is absent, CI still merges and stores
+coverage but explicitly skips the upload. When present, the SHA-pinned Qlty
+Action publishes the merged report with `skip-errors: false`; upload errors fail
+that job. Never commit the token or print its value in logs.
+
+Qlty maintainability analysis and quality gates are configured separately in
+Qlty Cloud. Review their results before making new checks required. Coverage
+upload alone does not enable or verify those checks.
+
+## Dependency updates and auto-merge
+
+Dependabot checks Bundler and GitHub Actions weekly on Monday at 08:00 JST.
+Bundler version updates wait 3 days for patches, 7 for minor updates, and 14 for
+major updates (7 days by default). Actions updates use a 7-day default cooldown;
+SemVer-specific cooldown settings are not applied to that ecosystem. These
+cooldowns apply to version updates, not security updates.
+
+Bundler updates cover both `/` and `/gemfiles/active_support`. The optional
+integration uses a standard `Gemfile`/`Gemfile.lock` pair so Dependabot can discover
+it. Its Gemfile evaluates the root Gemfile; review shared dependency updates in
+both lockfiles. The `shared-dependencies` rule uses `group-by: dependency-name` to
+combine each dependency's version update across the two directories into one PR,
+while keeping different dependencies in separate PRs. See the
+[Dependabot grouping reference](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#group-by-groups).
+Cross-directory grouping applies to version updates; review security updates for
+the same lockfile consistency separately. Keep frozen installs enabled in CI.
+
+Updates that touch the optional lockfile require manual review under the existing
+auto-merge policy, including shared development dependency updates. ActiveSupport
+remains optional, and changes to its selected series follow the
+[version selection policy](../CONTRIBUTING.md#activesupport-version-selection).
+For a manual shared dependency update, update the root constraint/lockfile and
+resolve the optional lockfile with that dependency as the target, for example:
+
+```sh
+docker compose run --rm -e BUNDLE_GEMFILE=gemfiles/active_support/Gemfile ruby bundle lock --update simplecov --conservative
+```
+
+When changing the monitored Bundler directories, let the configuration land on
+`master` before using `@dependabot recreate` on PRs generated under the old
+configuration. Verify that each shared dependency update includes both lockfiles
+and passes the Ruby matrix, timezone inventory, and coverage collation. Recreation
+overwrites manual changes; if Dependabot replaces the old PR with a grouped PR,
+review the replacement. A successful configuration PR alone does not establish
+that the hosted Dependabot update has synchronized both lockfiles.
+
+`dependabot-auto-merge.yml` can reserve auto-merge for a narrow set of updates:
+
+- Bundler patch/minor updates of `pry-byebug`, `rake`, `rspec`,
+  `rspec_junit_formatter`, `rubocop`, `rubocop-performance`, `rubocop-rspec`,
+  `simplecov`, `timecop`, and `yard`, changing only `Gemfile.lock`. The locked
+  runtime dependency entries (`redis-objects-periodical`, `redis-objects`,
+  `redis`, `redis-client`, and `connection_pool`) must stay identical. Only gem
+  spec/version and transitive dependency requirement lines may change.
+- SHA-pinned patch/minor replacements for `actions/checkout`,
+  `actions/upload-artifact`, `actions/download-artifact`, and
+  `actions/github-script`, changing only `uses:` lines and their version comments
+  in existing workflow files.
+
+Every named dependency in a grouped update must be permitted. Major updates,
+Bundler itself, runtime dependencies, optional integration lockfiles, manifest
+constraints, source/platform changes, third-party Actions, and workflow
+permission/trigger/step changes require manual review. Unknown metadata, missing
+or incomplete patches, a changed PR head, forks, and API errors do not enable
+merging. The enable mutation also requires the exact inspected head commit.
+If GitHub rejects enabling auto-merge specifically because the PR is already in
+clean status, the workflow repeats policy and protection verification and checks
+the current head, base, open/clean state, and absence of a reservation before
+merging with an exact-head guard. Other enable errors fail the workflow.
+
+The privileged workflow uses `pull_request_target` only to obtain the write
+permissions unavailable on normal Dependabot PR events. It checks out only the
+trusted base commit's `.github/scripts` policy with credentials disabled, never
+executes PR code, and inspects changes through the GitHub API. Its trigger has a
+scoped zizmor exception for this metadata-only design. Policy regressions run in
+ordinary read-only CI:
+
+```sh
+node --test .github/scripts/*.test.cjs
+```
+
+Repository administrators must finish these settings after the new checks have
+appeared on a PR:
+
+1. Enable repository auto-merge with merge commits and preserve existing required
+   reviews, security checks, and other protections.
+2. On `master`, require status checks and require the branch to be up to date.
+   Keep all three `checks / build_on_ruby_*` checks, `checks / rubocop`, `yardoc`,
+   and `upload-coverage`; add `active-support-timezone` and `dependabot-policy`.
+3. Verify on an eligible Dependabot PR that a failing required check prevents
+   merging and that an excluded update stays manual. For existing PRs, let their
+   next update trigger the workflow.
+
+Matching Dependabot PR events run the workflow without a separate enable
+variable. The policy below verifies the repository settings before allowing a
+merge.
+
+The policy verifies the repository's auto-merge setting and the effective
+rulesets plus any classic branch protection, including all eight named checks and
+strict up-to-date checks, before reserving a merge. Preserve GitGuardian and all
+other existing required checks. If protection cannot be read or is missing, it
+rejects the update. On a current-head rejection or verification error (including
+metadata-fetch failure), the workflow revokes an earlier reservation only when
+its ownership can be verified. The reservation's merge commit body contains a
+small policy marker identifying the repository, PR, inspected head, and workflow
+run. Ownership requires both the GitHub Actions bot and a matching originating
+workflow run; this marker remains in the eventual merge commit body. Human,
+unrelated automation, and legacy unmarked reservations are preserved with a
+manual-inspection notice. Failure to read ownership or confirm cancellation
+fails the workflow and requires manual inspection of the PR's auto-merge state.
+
+Runs for one PR are serialized, stale events do not change the current head's
+reservation, and cancellation rechecks the head and reservation immediately
+before writing and verifies the result afterward. GitHub's disable mutation has
+no conditional head/reservation argument, so administrators and other automation
+must avoid changing reservations concurrently with this workflow. A concurrent
+external write between the final read and cancellation cannot be guarded
+atomically by this API.
+
+Merge queues are not supported. No branch-protection, repository-variable, or
+publication setting is changed by the workflow. When rolling back,
+[disable the Dependabot Auto Merge workflow](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/disable-and-enable-workflows)
+to prevent new runs, cancel any active runs, and disable auto-merge on
+already-reserved PRs separately. Disabling the workflow does not cancel active
+runs or revoke existing reservations. Also inspect reservations manually if the
+job is skipped (for example after retargeting away from `master`), checkout fails,
+a run is cancelled or times out, or an
+ownership marker's originating run is no longer available. Only the configured
+PR events trigger re-evaluation; settings changes do not trigger it.
+
+## Release and scheduled maintenance
+
+`release.yml` uses RubyGems Trusted Publishing. Only pushes or manual dispatches
+on `release` can publish; no repository enable variable is required. The workflow
+reruns all three Ruby checks and RuboCop against the triggering commit, then
+publishes that same commit using Ruby 3.3 and Bundler 4.0.23. YARD and Qlty do not
+gate publishing. The publishing job uses fresh dependencies without caches,
+checks for an existing version tag or published version, and is not cancelled by
+a newer run. Do not run a real release as a migration test.
+
+Before the first publish, register this gem's Trusted Publisher on RubyGems.org
+with owner `ryz310`, repository `redis-objects-periodical`, workflow filename
+`release.yml`, and environment `release`. Create the matching GitHub environment,
+restrict it to the `release` branch, and configure its protection rules. The
+publishing job alone receives `contents: write` and `id-token: write`; it does not
+use `RUBYGEMS_API_KEY`. See the [RubyGems Trusted Publishing guide](https://guides.rubygems.org/trusted-publishing/).
+
+`rubocop_challenge.yml` runs daily at 08:30 JST on `master` without a repository
+enable variable. Manual dispatch on `master` defaults to a read-only dry run using
+`--no-create-pr`. The CLI requires a token even for a dry run, so that job uses
+the automatic read-only `GITHUB_TOKEN`.
+Actual PR creation uses `GITHUB_TOKEN` with job-scoped `contents: write` and
+`pull-requests: write`. Enable **Allow GitHub Actions to create and approve pull
+requests** in the repository's Actions settings before PR creation. Check the
+created PR's CI and approve pending workflow runs if required; PR creation alone
+does not prove CI ran. Scheduled workflows run on the default branch, may be
+delayed, and can be disabled after 60 days without public repository activity.
+
+### Resume a release after removing the enable variables
+
+1. Stop and drain the old CircleCI publisher, and confirm the Trusted Publisher
+   and GitHub `release` environment described above are configured. Inspect the
+   intended version's Git tag and RubyGems version before continuing. If either
+   already exists, investigate the partial release instead of retrying blindly.
+2. Merge the workflow fix into `master` after its PR checks pass. This restores
+   the Challenge schedule on `master`; it does not update the release workflow
+   on the `release` branch.
+3. Open and review a PR from `master` to `release`. Confirm its complete diff
+   contains only the changes intended for this release. Merging this PR pushes
+   to `release` and starts publication automatically, so merge only when ready
+   to publish. No enable variable or additional manual dispatch is needed.
+4. Follow the new Release run. It must pass the three Ruby builds and RuboCop
+   before `publish` starts. Approve the `release` environment deployment if its
+   configured protection rules require approval. Confirm the version tag and
+   published RubyGems version after the job succeeds.
+
+If the fixed workflow is already on `release` and no publish is in progress,
+manual dispatch of **Release** with branch **release** starts a new release run.
+Do not re-run the old skipped run: [a re-run uses its original commit](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs)
+and still contains the removed conditions. Dispatching on `master` cannot publish.
+
+## CircleCI migration checklist
+
+The CircleCI configuration and badge have been removed. Repository administrators
+must complete the external settings below; removing a file does not update branch
+protection, stop already queued jobs, or disable workflows still present on the
+old `release` branch. Stop each CircleCI writer before activating the matching
+Actions workflow. The Challenge schedule becomes active when its workflow is on
+`master`; publication starts on a push or manual dispatch on `release`.
+
+1. Verify Actions on a normal PR, a fork PR, and a Dependabot PR. Check all three
+   Ruby builds, RuboCop, YARD, JUnit artifacts, and the three-input coverage merge.
+   Confirm missing-token skipping and authenticated Qlty reporting separately.
+2. Once the Actions checks are available, use their exact reported
+   names when updating required checks. Replace only the `ci/circleci:` entries;
+   preserve `GitGuardian Security Checks`, strict up-to-date checks, and any
+   unrelated protections. Include all three Ruby builds, RuboCop, YARD, and
+   `upload-coverage`. Verify a failing test or missing coverage input blocks
+   merging before retiring CircleCI checks.
+
+   For the Ruby support update, also replace required checks for Ruby 2.7, 3.0,
+   3.1, and 3.2 with the reported checks for Ruby 3.3, 3.4, and 4.0. Keep RuboCop,
+   YARD, coverage, and unrelated protections required. Update protection only
+   after the new checks have run successfully.
+3. Prepare the Trusted Publisher and protected `release` environment. Stop and
+   drain CircleCI publishing before pushing the release workflow to `release`.
+   Run the first real publish only as an explicitly requested release task;
+   first inspect existing tags and RubyGems versions, including any partial release.
+4. Stop and drain the CircleCI Challenge schedule before merging the Actions
+   Challenge workflow into `master`. Run the Challenge dry run, then check an
+   actual generated PR and its CI before considering this step complete.
+5. Stop the CircleCI project and confirm no queued or running jobs remain. Remove
+   obsolete CircleCI credentials and integration only after confirming they are
+   not shared with other projects. Keep the migration commit available for
+   restoring the previous configuration if needed.
+
+For rollback, [disable the corresponding Actions workflow](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/disable-and-enable-workflows)
+in the repository's Actions UI (or use `gh workflow disable release.yml` or
+`gh workflow disable rubocop_challenge.yml`) and wait for any running writes to
+finish before restoring the corresponding CircleCI writer. Inspect any partial
+publication before proceeding. Restore previously recorded
+required checks together with the previous CircleCI configuration and keep at
+least one complete CI path active. Never enable both
+publishers or both Challenge writers at once. Do not delete existing release tags
+or retry publishing blindly after a partial failure.