# 通知設計書 24-dplyr.legacy_locale オプション非推奨

## 概要

本ドキュメントは、dplyrパッケージの `dplyr.legacy_locale` グローバルオプションが非推奨となったことに関する通知の設計書です。

### 本通知の処理概要

この通知は、`options(dplyr.legacy_locale = TRUE)` を設定した場合に発生する非推奨警告の処理内容を定義します。このオプションは、dplyr 1.1.0以前のシステムロケールに基づく文字列ソート動作を維持するために使用されていました。

**業務上の目的・背景**：dplyr 1.1.0で文字列のソート動作がCロケール（ASCIIベース）に変更されました。これにより、すべてのR環境で一貫した再現可能なソート結果が得られるようになりました。`dplyr.legacy_locale` オプションは、この変更による互換性の問題に対応するための一時的な措置でしたが、dplyr 1.2.0で正式に非推奨となりました。開発者には、`arrange()` 関数の `.locale` 引数を直接使用することが推奨されます。

**通知の送信タイミング**：`dplyr.legacy_locale` オプションが `TRUE` または `FALSE` に設定されている状態で、`arrange()` や `group_by()` などのソート処理を行う関数が呼び出された際に警告が発生します。

**通知の受信者**：dplyrパッケージを使用するRユーザー（データサイエンティスト、統計分析者、Rプログラマー）が対象です。特に、システムロケール依存のソート動作に依存していた既存コードの保守者に向けた通知です。

**通知内容の概要**：警告メッセージとして、このオプションが非推奨であること、代わりに `arrange(.locale = )` を使用すべきこと、およびシステムロケールの確認方法が表示されます。

**期待されるアクション**：受信者は `dplyr.legacy_locale` オプションの設定を削除し、必要に応じて `arrange()` 関数の `.locale` 引数を使用してロケールを明示的に指定することが期待されます。

## 通知種別

コンソール警告（lifecycle::deprecate_warn）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（関数実行時即時） |
| 優先度 | 中 |
| リトライ | 無 |

### 送信先決定ロジック

Rセッション内で `dplyr.legacy_locale` オプションが設定されている状態で、`dplyr_legacy_locale()` 関数が呼び出された場合にコンソールを通じて警告メッセージが表示されます。この関数は `arrange()` や `group_by()` の内部で呼び出されます。

## 通知テンプレート

### コンソール警告の場合

| 項目 | 内容 |
|-----|------|
| 送信元 | dplyrパッケージ |
| 送信元名称 | lifecycle::deprecate_warn |
| 形式 | テキスト |

### 本文テンプレート

```
`options(dplyr.legacy_locale =)` was deprecated in dplyr 1.2.0.
i If needed for `arrange()`, use `arrange(.locale =)` instead.
i If needed for `group_by() |> summarise()`, follow up with an additional `arrange(.locale =)` call.
i Use `Sys.getlocale("LC_COLLATE")` to determine your system locale, and compare against `stringi::stri_locale_list()` to determine the `.locale` value to use.
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| when | 非推奨となったバージョン | ハードコード値 "1.2.0" | Yes |
| what | 非推奨となった機能 | ハードコード値 "`options(dplyr.legacy_locale =)`" | Yes |
| details | 追加情報（代替手段） | ハードコード値（複数行） | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 関数呼び出し | `arrange()` または `group_by()` | `options("dplyr.legacy_locale")` が非NULLである | dplyr_legacy_locale関数内でチェック |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| オプションがNULLの場合 | デフォルト動作（Cロケール）として処理される |
| `.locale` 引数が明示的に指定された場合 | オプションよりも優先され、警告は発生しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[arrange/group_by関数呼び出し] --> B[dplyr_legacy_locale関数呼び出し]
    B --> C[peek_option dplyr.legacy_locale]
    C --> D{optionがNULLか?}
    D -->|Yes| E[FALSEを返却: Cロケール使用]
    D -->|No| F[lifecycle::deprecate_warn発行]
    F --> G{optionがBOOLか?}
    G -->|Yes| H[option値を返却]
    G -->|No| I[abort: 無効な値]
    E --> J[処理継続]
    H --> J
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（インメモリ処理のみ）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 無効な値エラー | `dplyr.legacy_locale` がTRUE/FALSE以外の値 | abort関数でエラーを発生 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| セッションあたり | lifecycleパッケージのデフォルト動作（同一IDは1回のみ） |

### 配信時間帯

制限なし（関数呼び出し時に即時発行）

## セキュリティ考慮事項

特になし。本通知はユーザーコンソールへの警告表示のみで、個人情報やセキュリティに関わるデータは含まれません。

## 備考

- この非推奨警告は dplyr 1.2.0 で導入されました
- `id = "dplyr-legacy-locale-option"` により警告が識別されます
- `user_env = globalenv()` が使用されており、常に直接的な使用として扱われます
- dplyr 1.1.0より前のシステムロケール依存の動作を再現するには、`.locale` 引数を使用する必要があります
- `Sys.getlocale("LC_COLLATE")` でシステムロケールを確認し、`stringi::stri_locale_list()` と比較することで適切な `.locale` 値を決定できます

---

## コードリーディングガイド

本通知を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

まず、グローバルオプションの参照方法を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | locale.R | `R/locale.R` | `peek_option()` によるオプション取得を理解する |

**読解のコツ**: Rのグローバルオプションシステム（`options()` と `getOption()`）の理解が必要です。

#### Step 2: エントリーポイントを理解する

処理の起点となる関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | locale.R | `R/locale.R` | `dplyr_legacy_locale()` 関数の定義 |

**主要処理フロー**:
1. **行71-112**: `dplyr_legacy_locale()` 関数の完全な実装
2. **行75**: `peek_option("dplyr.legacy_locale")` によるオプション取得
3. **行77-80**: オプションがNULLの場合はFALSEを返却

#### Step 3: 非推奨チェックロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | locale.R | `R/locale.R` | `lifecycle::deprecate_warn()` 呼び出しと詳細メッセージ |

**主要処理フロー**:
- **行89-102**: `lifecycle::deprecate_warn()` 呼び出し
- **行90**: バージョン "1.2.0" の指定
- **行91**: 対象機能 "`options(dplyr.legacy_locale =)`" の指定
- **行92-99**: 代替手段の詳細メッセージ
- **行100**: `user_env = globalenv()` でエンドユーザー向けに設定
- **行101**: ID "dplyr-legacy-locale-option" の指定

### プログラム呼び出し階層図

```
arrange() / group_by()
    │
    └─ dplyr_legacy_locale()
           │
           ├─ peek_option("dplyr.legacy_locale")
           │      │
           │      └─ NULL: return(FALSE)
           │
           ├─ lifecycle::deprecate_warn()
           │      │
           │      └─ 警告メッセージ発行
           │
           └─ is_bool(option) チェック
                  │
                  ├─ TRUE: return(option)
                  │
                  └─ FALSE: abort("must be TRUE or FALSE")
```

### データフロー図

```
[入力]               [処理]                    [出力]

オプション設定 ───▶ peek_option() ───▶ 警告メッセージ
     │                   │                    │
     │                   └─▶ 値検証 ─────────┴─▶ TRUE/FALSE
     │                                             │
     └─────────────────────────────────────────────┴─▶ ソート動作の決定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| locale.R | `R/locale.R` | ソース | ロケール関連の設定と非推奨チェックの実装 |
| lifecycle | 外部パッケージ | 依存関係 | deprecate_warn関数の提供 |
| stringi | 外部パッケージ | 依存関係 | ロケールリストの提供（オプショナル） |
