Preference Deprecation

Preference Deprecation and Cleanup Workflow

Use this skill when asked to deprecate, clean up, remove, or migrate an obsolete Chromium preference (Profile Pref or Local State Pref).

Core Principles & Overview

When removing a Chromium preference from feature code, never simply delete registration calls or constants from feature code without migrating to a delete-self state. Preferences saved on disk in User Pref JSON files must be explicitly cleaned up to prevent leaving abandoned, unread data in user profiles indefinitely.

Deleted preferences must remain in a "delete-self" state for 1 year before the cleanup logic itself is pruned.

---

Step-by-Step Execution Checklist

Step 1: Audit Preference Properties & Scope

1. Scope Check: Determine if the pref is a Profile Pref (Profile::GetPrefs()) or Local State Pref (g_browser_process->local_state()).
2. Platform & Embedder Scope Check: Determine which platforms and embedders register and use the preference (e.g., Desktop, Android, iOS, ChromeOS, or shared components/). This determines which platform migration hubs will require delete-self cleanup in Step 3.
3. Syncable Pref Check: Check if the pref had any SYNCABLE_* flag (such as user_prefs::PrefRegistrySyncable::SYNCABLE_PREF, SYNCABLE_PRIORITY_PREF, or the ChromeOS-only counterparts SYNCABLE_OS_PREF / SYNCABLE_OS_PRIORITY_PREF) or was present in a syncable prefs database:
   • components/sync_preferences/common_syncable_prefs_database.cc
   • chrome/browser/sync/prefs/chrome_syncable_prefs_database.cc
   • ios/chrome/browser/sync/model/prefs/ios_chrome_syncable_prefs_database.cc
   • Syncable Database Handling:
     • Reserved IDs: In syncable_prefs_ids inside the database .cc file (e.g., common_syncable_prefs_database.cc), do NOT delete the ID constant. Instead, comment out the entry so the numeric ID remains reserved (e.g. // kMyPref = 123, (deprecated)).
     • Remove from Allowlist Map: Delete the entry completely from the corresponding allowlist map (e.g., kCommonSyncablePrefsAllowlist, kChromeSyncablePrefsAllowlist, or kIOSChromeSyncablePrefsAllowlist).
     • Histogram Enum & Presubmit Check: Add (obsolete) to the corresponding entry label in tools/metrics/histograms/metadata/sync/enums.xml (within the SyncablePref enum, e.g., <int value="49" label="(obsolete) SyncedPrefName"/>), satisfying the change coupling presubmit check (CommonSyncablePref, ChromeSyncablePref, or IosSyncablePref).
     • Registration Flags: Remove any SYNCABLE_* flag from any active registrations.
4. Policy Check: Check if the pref is backed by an Enterprise Policy.
   • Policy-Only Exception: If the pref was only exposed via Enterprise Policy in Managed Prefs (with no UI allowing end-users to change it), it was never written to User Prefs JSON on disk. Migration/ClearPref() in browser_prefs.cc is not required.
   • If the policy pref was user-modifiable, follow docs/enterprise/add_new_policy.md to deprecate the policy for several milestones before removing pref logic.

---

Step 2: Code Cleanup in Feature Code

1. Delete call sites that read/write the obsolete pref from feature logic and UI code (including Android Java callsites such as Pref.java, PrefNames.java, or ChromePreferenceKeys where applicable).
2. Remove pref name declarations/definitions from their original locations (common locations include component pref headers such as components/<component>/.../pref_names.h, feature headers like chrome/browser/<feature>/..._prefs.h, chrome/common/pref_names.h, ash/constants/ash_pref_names.h, ios/chrome/.../pref_names.h, or local .cc/.h files).
3. Remove the registration call from the component's RegisterProfilePrefs() or RegisterLocalState() method.
4. Update or remove feature unit tests (e.g. ..._unittest.cc and Android unit or instrumentation tests) that asserted pref registration, default values, or syncability.

---

Step 3: Add Delete-Self Registration & Cleanup / Migration Logic

When removing a pref from feature code, the raw string constant must be relocated/added into the migration files (browser_prefs.cc / browser_prefs.mm) so browser_prefs can clear leftover disk data.

A. Desktop / Android / ChromeOS (chrome/browser/prefs/browser_prefs.cc)

If the pref was registered on Desktop, Android, or ChromeOS (either shared across platforms or exclusive to any of them):

1. Chronological Ordering (Primary Invariant - Year then Month):

   • All deprecation registrations and ClearPref() calls must be ordered chronologically by date (MM/YYYY).
   • Respect Year Ordering: When sorting entries, ensure the full date is considered (e.g., 08/2026 must be placed after 11/2025 and 07/2026, never sorted alphabetically by month alone).
   • Respect PRESUBMIT Markers:
     • Profile Prefs:
       • Register in RegisterProfilePrefsForMigration().
       • Clear/migrate in MigrateObsoleteProfilePrefs() within the // BEGIN_MIGRATE_OBSOLETE_PROFILE_PREFS and // END_MIGRATE_OBSOLETE_PROFILE_PREFS markers.
     • Local State Prefs:
       • Register in RegisterLocalStatePrefsForMigration().
       • Clear/migrate in MigrateObsoleteLocalStatePrefs() within the // BEGIN_MIGRATE_OBSOLETE_LOCAL_STATE_PREFS and // END_MIGRATE_OBSOLETE_LOCAL_STATE_PREFS markers.
     • Never delete or modify the marker lines as they are enforced by presubmit checks (PRESUBMIT.py).

2. Relocate Constant: Move the pref name string constant to the anonymous namespace of chrome/browser/prefs/browser_prefs.cc under // Deprecated MM/YYYY.:

   // Deprecated MM/YYYY.
   constexpr char kObsoletePrefName[] = "path.to.obsolete_pref";

3. Register Obsolete Pref:

   • Register the pref in RegisterProfilePrefsForMigration() (Profile Prefs) or RegisterLocalStatePrefsForMigration() (Local State Prefs).
   • MUST match the original pref type (Boolean, Integer, String, List, Dictionary, Time, etc.) without any SYNCABLE_* flags (e.g. SYNCABLE_PREF, SYNCABLE_PRIORITY_PREF, SYNCABLE_OS_PREF, SYNCABLE_OS_PRIORITY_PREF):

     // Deprecated MM/YYYY.
     registry->RegisterBooleanPref(kObsoletePrefName, false);
     registry->RegisterTimePref(kObsoleteTimePrefName, base::Time());
     registry->RegisterDictionaryPref(kObsoleteDictPrefName);

4. Clear Leftover Data or Migrate:

   • For Deletion: Add profile_prefs->ClearPref() in MigrateObsoleteProfilePrefs() or local_state->ClearPref() in MigrateObsoleteLocalStatePrefs() with the matching date comment:

     // Added MM/YYYY.
     profile_prefs->ClearPref(kObsoletePrefName);

   • For Migration (moving old pref value to a new key): Use GetUserPrefValue() (NOT Get*()) to avoid migrating default/policy values:

     // Added MM/YYYY.
     const base::Value* value =
         profile_prefs->GetUserPrefValue(kObsoletePrefName);
     if (value) {
       profile_prefs->Set(kNewPrefName, *value);
       profile_prefs->ClearPref(kObsoletePrefName);
     }