resizing 1.2.1 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c35a202fce460c80d3b476d4d9307f6345d9d13ed95c385a0e41108f35e46e61
-  data.tar.gz: 14f7f3a20d83859f121b9138931164d5eb27a5a9764cd6ff2dee2dfc71aa72cd
+  metadata.gz: 0ff23b326ca457e2ba530fa2b299b7cb88c814fe08dc6469c3355506cdbb8f65
+  data.tar.gz: d0425ae8a78d155163a813a164b6f7b1e98f2a9b10032832d50c917878fcfbce
 SHA512:
-  metadata.gz: 25a5f49e162e691ed72d147132d4a7aea069a6d148af8a1d22b0b3b3cedecc0b8bd46b674c177fdbef88179684342a230ffc23edb56340db42540beadc5f6947
-  data.tar.gz: 03b8a3544e711973f79ef66dec2400ad09fba7d571a4518f0424ede8eb3da8420fb0c8fd299bc1a7c0ad734894bcbb59fa566857790277c0c8d4f0aa67537700
+  metadata.gz: 3e8a8b33fda6f8b6209c7b85fb7b2e89346b5059443b5de19f2334fb70019b1df4b92b0bf815e7f091e930a3e726e30f601d344e1330e2bb2ce83d6adbad3c9a
+  data.tar.gz: ab6ea786bce933942de4e10b8826beb243a2285789ec48c9a33644aae954bfc7fa26817ab73c95516844661d60d5e6f2b5d36da2c6b0509eb6b4126602ca6874

data/.devcontainer/Dockerfile

@@ -0,0 +1,73 @@
+# Debian variant of the base image (bookworm / bullseye)
+ARG VARIANT=bookworm
+FROM mcr.microsoft.com/devcontainers/base:${VARIANT}
+
+# Ruby installed and set as the rbenv global version. Matches .ruby-version.
+# Other versions can be installed from inside the container with `rbenv install`.
+ARG RUBY_VERSION=3.1.7
+
+# Build dependencies for ruby-build, plus what the mysql2 gem needs.
+# The MySQL packages match .github/workflows/test.yml.
+RUN apt-get update \
+    && export DEBIAN_FRONTEND=noninteractive \
+    && apt-get install -y --no-install-recommends \
+        autoconf \
+        bison \
+        build-essential \
+        libffi-dev \
+        libgdbm-dev \
+        libncurses-dev \
+        libreadline-dev \
+        libssl-dev \
+        libyaml-dev \
+        uuid-dev \
+        zlib1g-dev \
+        default-libmysqlclient-dev \
+        default-mysql-client \
+        pkg-config \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV RBENV_ROOT=/usr/local/rbenv
+ENV PATH=${RBENV_ROOT}/shims:${RBENV_ROOT}/bin:${PATH}
+
+# rbenv and ruby-build. RBENV_ROOT is owned by vscode so that `rbenv install`
+# works from inside the container without sudo.
+RUN git clone --depth 1 https://github.com/rbenv/rbenv.git "${RBENV_ROOT}" \
+    && git clone --depth 1 https://github.com/rbenv/ruby-build.git "${RBENV_ROOT}/plugins/ruby-build" \
+    && printf '%s\n' \
+        'export RBENV_ROOT=/usr/local/rbenv' \
+        'export PATH="$RBENV_ROOT/shims:$RBENV_ROOT/bin:$PATH"' \
+        'eval "$(rbenv init -)"' \
+        > /etc/profile.d/rbenv.sh
+
+RUN rbenv install "${RUBY_VERSION}" \
+    && rbenv global "${RUBY_VERSION}" \
+    && gem install bundler \
+    && rbenv rehash \
+    && chown -R vscode:vscode "${RBENV_ROOT}"
+
+# Install gems into a named volume, so nothing is written to the bind-mounted
+# workspace and a rebuild does not have to fetch them again.
+ENV BUNDLE_PATH=/usr/local/bundle
+
+RUN mkdir -p "${BUNDLE_PATH}" && chown -R vscode:vscode "${BUNDLE_PATH}"
+
+# Ruby artifacts generated on the host must not leak in through the bind mount:
+# vendor/ holds gems with native extensions built against the host's glibc,
+# .bundle/config points BUNDLE_PATH at it, and .ruby-lsp/ records which gems the
+# Ruby LSP extension has installed. compose.yaml keeps all three on their own
+# volumes; creating the directories here gives those volumes the right owner.
+RUN mkdir -p /workspaces/resizing-gem/vendor \
+             /workspaces/resizing-gem/.bundle \
+             /workspaces/resizing-gem/.ruby-lsp \
+    && chown -R vscode:vscode /workspaces
+
+# Bundler's global config, so that BUNDLE_PATH also applies to tools that
+# compose their own bundle with a clean environment. The Ruby LSP extension
+# builds one under .ruby-lsp/, which makes that directory bundler's app root,
+# so a config in the workspace root would not be read for it.
+RUN mkdir -p /home/vscode/.bundle \
+    && printf '%s\n' '---' 'BUNDLE_PATH: "/usr/local/bundle"' \
+        > /home/vscode/.bundle/config \
+    && chown -R vscode:vscode /home/vscode/.bundle

data/.devcontainer/compose.yaml

@@ -0,0 +1,58 @@
+# A distinct project name and service name so this does not collide with the
+# docker-compose.yml in the repository root (project resizing-gem, service mysql)
+name: resizing-gem-devcontainer
+
+services:
+  app:
+    build:
+      context: ..
+      dockerfile: .devcontainer/Dockerfile
+      args:
+        # Default Ruby version. Other versions can be installed from inside the
+        # container with `rbenv install`, so this rarely needs changing.
+        RUBY_VERSION: 3.1.7
+    command: sleep infinity
+    environment:
+      # test/test_helper.rb reads these to build the ActiveRecord connection.
+      # MYSQL_DATABASE is left unset on purpose: the tests then create a database
+      # per process and drop it afterwards, which keeps concurrent runs isolated.
+      MYSQL_HOST: db
+      MYSQL_PORT: '3306'
+      MYSQL_USER: root
+      MYSQL_PASSWORD: secret
+      # RAILS_VERSION is left unset on purpose: the Gemfile then picks the newest
+      # Rails that runs on the container's Ruby. Set it here to pin another version.
+    volumes:
+      - ..:/workspaces/resizing-gem:cached
+      - bundle:/usr/local/bundle
+      # Not shared with the host: see the Dockerfile
+      - vendor:/workspaces/resizing-gem/vendor
+      - bundle-config:/workspaces/resizing-gem/.bundle
+      - ruby-lsp:/workspaces/resizing-gem/.ruby-lsp
+    depends_on:
+      db:
+        condition: service_healthy
+
+  db:
+    image: mysql:5.7.29
+    # mysql:5.7 is published for amd64 only, so run it emulated on Apple Silicon
+    platform: linux/amd64
+    command: mysqld --character-set-server=utf8mb4 --collation-server=utf8mb4_bin
+    environment:
+      MYSQL_ROOT_PASSWORD: secret
+      MYSQL_DATABASE: resizing_gem_test
+    volumes:
+      - db-data:/var/lib/mysql
+    healthcheck:
+      test: ['CMD', 'mysqladmin', 'ping', '-h', '127.0.0.1', '-uroot', '-psecret']
+      interval: 5s
+      timeout: 5s
+      retries: 30
+      start_period: 30s
+
+volumes:
+  bundle:
+  vendor:
+  bundle-config:
+  ruby-lsp:
+  db-data:

data/.devcontainer/devcontainer-lock.json

@@ -0,0 +1,9 @@
+{
+  "features": {
+    "ghcr.io/devcontainers/features/github-cli:1": {
+      "version": "1.1.2",
+      "resolved": "ghcr.io/devcontainers/features/github-cli@sha256:7c409bf6316ffd85f04fd92fba85a744282639e603417dd4796409866bdb6805",
+      "integrity": "sha256:7c409bf6316ffd85f04fd92fba85a744282639e603417dd4796409866bdb6805"
+    }
+  }
+}

data/.devcontainer/devcontainer.json

@@ -0,0 +1,32 @@
+{
+  "name": "resizing-gem",
+  "dockerComposeFile": "compose.yaml",
+  "service": "app",
+  "workspaceFolder": "/workspaces/resizing-gem",
+  "remoteUser": "vscode",
+  "features": {
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+  "postCreateCommand": ".devcontainer/post-create.sh",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "Shopify.ruby-lsp",
+        "eamodio.gitlens"
+      ],
+      "settings": {
+        "[ruby]": {
+          "editor.defaultFormatter": "Shopify.ruby-lsp",
+          "editor.tabSize": 2,
+          "editor.insertSpaces": true
+        },
+        "rubyLsp.formatter": "rubocop",
+        "rubyLsp.rubyVersionManager": {
+          "identifier": "rbenv"
+        },
+        "files.trimTrailingWhitespace": true,
+        "files.insertFinalNewline": true
+      }
+    }
+  }
+}

data/.devcontainer/post-create.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Runs once after the dev container is created.
+set -euo pipefail
+
+# Honour a .ruby-version that asks for a Ruby the image does not carry.
+# (.ruby-version is gitignored, so it differs from machine to machine.)
+if [ -f .ruby-version ]; then
+  required="$(cat .ruby-version)"
+  if ! rbenv versions --bare | grep -qx "${required}"; then
+    echo "==> installing Ruby ${required} (from .ruby-version)"
+    rbenv install "${required}"
+    rbenv rehash
+  fi
+fi
+
+echo "==> ruby $(ruby -e 'print RUBY_VERSION')"
+
+echo "==> bundle install"
+bundle install
+
+echo "==> waiting for MySQL (${MYSQL_HOST}:${MYSQL_PORT})"
+for _ in $(seq 1 60); do
+  if mysqladmin ping \
+      -h "${MYSQL_HOST}" -P "${MYSQL_PORT}" \
+      -u "${MYSQL_USER}" -p"${MYSQL_PASSWORD}" \
+      --silent > /dev/null 2>&1; then
+    echo "MySQL is ready"
+    break
+  fi
+  sleep 1
+done
+
+cat <<'MSG'
+
+setup done.
+
+  bundle exec rake test      # run the tests
+  bundle exec rubocop        # run the linter
+  bin/console                # interactive prompt
+
+MSG

data/.github/copilot-instructions.md

@@ -0,0 +1 @@
+../CLAUDE.md

data/.github/labeler.yml

@@ -0,0 +1,28 @@
+ruby:
+  - changed-files:
+    - any-glob-to-any-file:
+      - 'lib/**/*.rb'
+      - 'Rakefile'
+      - 'resizing.gemspec'
+      - '.rubocop.yml'
+
+tests:
+  - changed-files:
+    - any-glob-to-any-file:
+      - 'test/**'
+
+github_actions:
+  - changed-files:
+    - any-glob-to-any-file:
+      - '.github/**'
+
+documentation:
+  - changed-files:
+    - any-glob-to-any-file:
+      - '**/*.md'
+
+dependencies:
+  - changed-files:
+    - any-glob-to-any-file:
+      - 'Gemfile'
+      - 'Gemfile.lock'

data/.github/release.yml

@@ -0,0 +1,35 @@
+changelog:
+  exclude:
+    labels:
+      - release
+  categories:
+    - title: Breaking Changes
+      labels:
+        - breaking change
+    - title: New Features
+      labels:
+        - enhancement
+    - title: Improvements
+      labels:
+        - improvement
+    - title: Bug Fixes
+      labels:
+        - bug
+    - title: Security
+      labels:
+        - security
+    - title: Dependencies
+      labels:
+        - dependencies
+    - title: CI
+      labels:
+        - github_actions
+    - title: Housekeeping
+      labels:
+        - housekeeping
+    - title: Documentation
+      labels:
+        - documentation
+    - title: Other Changes
+      labels:
+        - "*"

data/.github/workflows/labeler.yml

@@ -0,0 +1,20 @@
+name: labeler
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - synchronize
+      - reopened
+
+jobs:
+  labeler:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/labeler@b8dd2d9be0f68b860e7dae5dae7d772984eacd6d # v6
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          sync-labels: false

data/.github/workflows/lint.yml

@@ -0,0 +1,37 @@
+name: lint
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+permissions:
+  contents: read
+
+jobs:
+  rubocop:
+    name: RuboCop
+    runs-on: ubuntu-22.04
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: "Install ruby dependencies"
+        run: |
+          sudo apt update
+          sudo apt install -y libyaml-dev curl libmysqlclient-dev
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          # Matches the devcontainer, so local and CI report the same offenses
+          ruby-version: '3.1'
+          bundler-cache: false
+
+      - name: bundle install
+        run: |
+          bundle install
+
+      - name: Run RuboCop
+        run: |
+          bundle exec rubocop

data/.github/workflows/test.yml

@@ -12,27 +12,30 @@ permissions:
 
 jobs:
   test:
-    name: Ruby ${{ matrix.ruby }} / Rails ${{ matrix.rails }}
+    name: Ruby ${{ matrix.ruby }} / Rails ${{ matrix.rails }} / Faraday ${{ matrix.faraday }}
     strategy:
       fail-fast: false
       matrix:
-        ruby: ['3.1', '3.2','3.3', '3.4']
-        rails: ['6.1', '7.0', '7.1', '7.2']
+        ruby: ['3.1', '3.2', '3.3', '3.4', '4.0']
+        rails: ['7.0', '7.1', '7.2', '8.0', '8.1']
+        faraday: ['1.10', '2.0']
         exclude:
-          # Rails 7.2 requires Ruby 3.1+
+          # Rails 8.x requires Ruby 3.2+
           - ruby: '3.1'
-            rails: '7.2'
-          # Rails 7.1 requires Ruby 3.1+
+            rails: '8.0'
           - ruby: '3.1'
+            rails: '8.1'
+          # Upstream does not support Ruby 4.0 on Rails 7.0 / 7.1
+          - ruby: '4.0'
+            rails: '7.0'
+          - ruby: '4.0'
             rails: '7.1'
-          # Rails 6.1 requires Ruby under 3.3
-          - ruby: '3.4'
-            rails: '6.1'
 
     runs-on: ubuntu-22.04
 
     env:
       RAILS_VERSION: ${{ matrix.rails }}
+      FARADAY_VERSION: ${{ matrix.faraday }}
 
     steps:
       - uses: actions/checkout@v4
@@ -61,6 +64,10 @@ jobs:
         run: |
           bundle install
 
+      - name: Show Faraday version
+        run: |
+          bundle list | grep faraday
+
       - name: Run test
         run: |
           bundle exec rake test

data/.gitignore

@@ -6,3 +6,9 @@
 /pkg/
 /spec/reports/
 /tmp/
+vendor/
+Gemfile.lock
+tags
+sample1.jpg
+.ruby-version
+uploads/

data/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+> このファイルは v0.8.2 までの履歴です。以降のリリースノートは
+> [GitHub Releases](https://github.com/jksy/resizing-gem/releases) に一本化しています。
+
 **Merged pull requests:**
 
 - v0.8.2 [\#53](https://github.com/jksy/resizing-gem/pull/53) ([jksy](https://github.com/jksy))

data/CLAUDE.md

@@ -0,0 +1,68 @@
+# CLAUDE.md — resizing-gem
+
+[Resizing](https://www.resizing.net/) の Ruby クライアント gem（rubygems.org に `resizing` として公開）。
+
+## 開発環境
+
+devcontainer（`.devcontainer/`）を用意してある。VS Code の "Reopen in Container"、または `devcontainer up --workspace-folder .` で、Ruby・MySQL・`bundle install` まで揃った状態になる。
+
+Ruby は rbenv 管理で `.ruby-version` に従う。別バージョンを試す場合はコンテナ内で `rbenv install <version>` → `rbenv local <version>` → `bundle install`（sudo 不要）。イメージに焼くバージョンを変える場合は `.devcontainer/compose.yaml` の `RUBY_VERSION` を変更してリビルドする。
+
+devcontainer を使わない場合はテスト用に MySQL を自前で起動する（`docker compose up -d mysql`）。接続先は `MYSQL_HOST` / `MYSQL_PORT` / `MYSQL_USER` / `MYSQL_PASSWORD` で上書きでき、既定は `root:secret@127.0.0.1:3306`。
+
+データベースはテストプロセスごとに `resizing_gem_test_<ホスト識別子>_<pid>` を作成し、終了時に破棄する（並行実行しても壊れないようにするため。強制終了で残ったものは次回実行時に掃除する）。`MYSQL_DATABASE` を指定した場合はそのデータベースをそのまま使い破棄もしないので、並行実行するときは名前を分ける。
+
+## テスト・Lint
+
+外部 API 呼び出しは `test/vcr/` のカセットを使い、実 API を叩くテストは追加しない。
+
+```bash
+bundle exec rake ci                                         # RuboCop + テスト（push 前チェックと同じ）
+bundle exec rake test                                       # 全件
+bundle exec ruby -Itest -Ilib test/resizing/client_test.rb  # 単一ファイル
+RAILS_VERSION=7.1 bundle exec rake test                     # Rails バージョンを変えて実行（既定は Ruby 3.2 以上で 8.1、3.1 で 7.2）
+bundle exec rubocop
+```
+
+ローカルで実行できない場合、確認は CI に任せてよい。テストは `.github/workflows/test.yml`（Ruby 3.1〜4.0 × Rails 7.0〜8.1）、RuboCop は `.github/workflows/lint.yml`（Ruby 3.1）で走る。
+
+## push 前チェック
+
+`git push` すると `git-hooks/pre-push` が `bundle exec rake ci`（RuboCop + テスト）を実行し、失敗した時点で push を中断する。**CI が落ちる前に気づくための仕組みなので、`--no-verify` で飛ばさないこと**（飛ばした場合はその旨を報告する）。
+
+有効化はクローンごとに一度だけ必要で、`bin/setup` が `git config core.hooksPath git-hooks` を設定する。設定済みかは `git config core.hooksPath` で確認できる（worktree でも設定は共有される）。
+
+```bash
+bin/setup                        # bundle install + git hooks の有効化
+PRE_PUSH_SKIP_TESTS=1 git push   # RuboCop だけにしてテストを省く
+```
+
+チェックは gem が入っている環境で走る。`bundle check` が通る環境（devcontainer の中、または `bundle install` 済みのホスト）ならそのまま、通らなければ devcontainer CLI か docker compose 経由で devcontainer 内で実行する。
+
+## PR 運用
+
+- `master` に直接 push しない。feature ブランチ（`claude/` プレフィックス可）から PR を出す
+- **PR には種別ラベルを必ず 1 つ付ける**（`enhancement` / `improvement` / `bug` / `security` / `documentation` / `housekeeping` / `breaking change` のいずれか）。リリースノートのカテゴリ分け（`.github/release.yml`）に使われる
+  - `improvement` は gem の機能改善。CI・開発環境の整備など利用者に見えない変更は `housekeeping`
+  - バージョンバンプだけの PR には `release` を付ける（リリースノートから除外される）
+  - `ruby` / `tests` / `github_actions` / `documentation` / `dependencies` は `.github/labeler.yml` で自動付与される。種別ラベルは自動では付かない
+- Issue 番号は PR タイトルに含めず、PR 説明に `Closes #N` と書く
+- 公開 API を変える場合は `breaking change` ラベルを付け、README も更新する
+
+## リリース手順
+
+1. `lib/resizing/version.rb` を更新する PR に `release` ラベルを付けてマージする
+2. `master` で `bundle exec rake release`（rubygems.org への公開と `v<version>` タグの push）
+3. GitHub の Releases で該当タグを選び、"Generate release notes" で本文を生成して公開する
+
+`CHANGELOG.md` は v0.8.2 で更新を止めており、リリースノートは GitHub Releases に一本化している。
+
+## 言語ルール
+
+| 場所 | 言語 |
+|------|------|
+| コミットメッセージ | 英語（Issue 番号は含めない） |
+| ソースコード内コメント | 英語 |
+| PR タイトル・説明 | 日本語 |
+| コードレビューコメント | 日本語 |
+| 人間とのやり取り全般 | 日本語 |

data/Gemfile

@@ -5,12 +5,18 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in resizing.gemspec
 gemspec
 
-# Allow testing against different Rails versions
-rails_version = ENV['RAILS_VERSION'] || '7.0'
+# Allow testing against different Rails versions (e.g. RAILS_VERSION=7.1).
+# Unset, the newest supported Rails that runs on the current Ruby is used:
+# Rails 8.x needs Ruby 3.2+, so Ruby 3.1 falls back to 7.2.
+rails_version = ENV['RAILS_VERSION'] || (RUBY_VERSION >= '3.2' ? '8.1' : '7.2')
 gem 'rails', "~> #{rails_version}"
 
+# Allow testing against different Faraday versions (e.g. FARADAY_VERSION=1.10).
+# Unset, the gemspec constraint picks the latest release.
+faraday_version = ENV['FARADAY_VERSION']
+gem 'faraday', "~> #{faraday_version}" if faraday_version
+
 gem 'byebug'
-gem 'github_changelog_generator'
 gem 'mysql2'
 gem 'pry-byebug'
 gem 'rake', '~> 13.0'

data/README.md

@@ -8,7 +8,13 @@ Client and utilities for [Resizing](https://www.resizing.net/) - an image hostin
 
 ## Requirements
 
-- Ruby 3.1.0 or later
+- Ruby 3.1.0 or later (tested against 3.1, 3.2, 3.3, 3.4 and 4.0)
+- Rails 7.0 or later for the CarrierWave integration (tested against 7.0, 7.1, 7.2, 8.0 and 8.1)
+- Faraday 1.x or 2.x (tested against 1.10 and the latest 2.x)
+
+The exact combinations exercised in CI are listed in `.github/workflows/test.yml`.
+Support for a Ruby or Rails series that has reached upstream end-of-life may be dropped in
+a minor release; such changes are announced in the release notes.
 
 ## Installation
 
@@ -31,12 +37,13 @@ Or install it yourself as:
 ```ruby
 Resizing.configure = {
   image_host: 'https://img.resizing.net',
-  video_host: 'https://video.resizing.net',
   project_id: 'your-project-id',
   secret_token: 'your-secret-token'
 }
 ```
 
+`video_host` は動画 API の廃止にともない非推奨です。指定しても利用されず、`Configuration#video_host` や `Configuration::DEFAULT_VIDEO_HOST` を参照すると警告が出ます。将来のバージョンで削除します。
+
 ## Usage
 
 ### Basic Client Usage
@@ -81,10 +88,115 @@ class User
 end
 ```
 
+`process` declares the transformation applied when the browser fetches the image URL, so
+the processors are never run as local image processing on upload.
+
+The uploader validations hooked on CarrierWave's `:cache` callbacks are checked before the
+image is uploaded to Resizing:
+
+```ruby
+class ImageUploader < CarrierWave::Uploader::Base
+  include Resizing::CarrierWave
+
+  def extension_allowlist
+    %w[jpg jpeg gif png]
+  end
+
+  def content_type_allowlist
+    [%r{\Aimage/}]
+  end
+
+  def size_range
+    0..(5 * 1024 * 1024)
+  end
+end
+```
+
+`extension_denylist` and `content_type_denylist` work the same way. A rejected file is not
+uploaded, and the model becomes invalid with an error on the mounted column, as in plain
+CarrierWave.
+
+The extension checked by `extension_allowlist` / `extension_denylist` is derived from the
+content type of the file whenever it is known, not from the file name. A file downloaded
+from a Resizing URL (e.g. assigned through `remote_<column>_url=`) ends with the version
+string, so its file name has no meaningful extension; the `Content-Type` of the response
+is used instead. When the content type is unknown (`application/octet-stream`), the
+extension of the file name is used as in plain CarrierWave.
+
+Versions are not uploaded separately: a version only changes the transformation in the
+generated URL, so a single upload backs every version.
+
 ## Development
 
+### Dev Container (recommended)
+
+This repository ships a [Dev Container](https://containers.dev/) so that everyone develops
+against the same Ruby / MySQL setup.
+
+Requirements: Docker and either VS Code + the *Dev Containers* extension, or the
+[`devcontainer` CLI](https://github.com/devcontainers/cli).
+
+1. Open the repository in VS Code and run **Dev Containers: Reopen in Container**
+   (or run `devcontainer up --workspace-folder .`).
+2. `bundle install` and the MySQL wait are executed automatically by
+   `.devcontainer/post-create.sh`.
+3. Inside the container:
+
+   ```console
+   $ bundle exec rake test    # run the tests
+   $ bundle exec rubocop      # run the linter
+   $ bin/console              # interactive prompt
+   ```
+
+The container provides:
+
+- Ruby managed by [rbenv](https://github.com/rbenv/rbenv), so the version can be changed
+  from inside the container (see below)
+- MySQL 5.7 with the `resizing_gem_test` database, matching CI
+- `RAILS_VERSION` to test against another Rails version, matching the `RAILS_VERSION`
+  switch in the `Gemfile` and in CI. Unset, the `Gemfile` picks the newest supported Rails
+  that runs on the current Ruby (8.1, or 7.2 on Ruby 3.1)
+
+Gems are installed into a named volume (`/usr/local/bundle`). `vendor/`, `.bundle/` and
+`.ruby-lsp/` are kept on their own volumes so that Ruby artifacts generated on the host do
+not leak into the container through the bind mount: `vendor/` holds gems whose native
+extensions are built against the host's libraries, `.bundle/config` points `BUNDLE_PATH`
+at it, and `.ruby-lsp/` records which gems the Ruby LSP extension has installed. The host
+copies are left untouched.
+
+#### Changing the Ruby version
+
+Ruby 3.1.7 is installed when the image is built, and `.ruby-version` is honoured on
+container creation. To switch to another version from inside the container:
+
+```console
+$ rbenv install 3.3.12
+$ rbenv local 3.3.12    # writes .ruby-version (gitignored)
+$ bundle install
+```
+
+`rbenv install` needs no `sudo`; the build dependencies are already in the image. To
+change the version the image ships with, set the `RUBY_VERSION` build arg in
+`.devcontainer/compose.yaml` and rebuild.
+
+### Without a Dev Container
+
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+The tests need a MySQL server. `docker-compose.yml` in the repository root starts a
+suitable one (`docker compose up -d mysql`).
+
+Each test process creates its own database (`resizing_gem_test_<host>_<pid>`) and drops it
+when the run finishes, so several test processes can share one MySQL server without
+breaking each other's tables. Databases left behind by killed processes are cleaned up on
+the next run.
+
+The connection defaults to `root:secret@127.0.0.1:3306` and can be overridden with the
+`MYSQL_HOST`, `MYSQL_PORT`, `MYSQL_USER` and `MYSQL_PASSWORD` environment variables.
+Setting `MYSQL_DATABASE` uses that database as is and never drops it; in that case give
+each concurrent test process a different name, otherwise they will overwrite each other's
+tables.
+
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing