docs(protos): Reframe as temporary override, not permanent migration

This is a temporary mechanism for faster iteration on proto
definitions, not a permanent migration of ownership away from
sentry-protos. Changes should eventually be published back to
sentry-protos. Remove "migration" language throughout.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: dashed

proto/README.md

@@ -1,12 +1,8 @@
 # Proto Sources
 
-This directory is the **source of truth** for proto definitions used by sentry. Proto files here are compiled on demand during development and pre-compiled during CI/deploy for production.
+This directory holds `.proto` files that override the pip-installed `sentry-protos` package. Proto files here are compiled on demand during development and pre-compiled during CI/deploy for production.
 
-Currently migrated domains:
-
-- `billing/` — billing service protos (data categories, usage, contracts, etc.)
-
-Other domains (snuba, seer, taskbroker, etc.) remain in the `sentry-protos` pip package until migrated.
+This is a temporary mechanism for faster iteration on proto definitions without waiting for a `sentry-protos` release. Changes here should eventually be published back to `sentry-protos`.
 
 ## Directory Structure
 
@@ -18,17 +14,10 @@ proto/
         data_category.proto
         date.proto
         usage_data.proto
-        common/
-          v1/
-            address.proto
-            ...
         services/
           usage/
             v1/
               endpoint_usage.proto
-          contract/
-            v1/
-              ...
 ```
 
 ## Usage
@@ -46,16 +35,12 @@ Edit `.proto` files in this directory directly. On next import, the `proto_loade
 ## How Overrides Work
 
 1. **This directory** (`proto/`) -- highest priority
-2. **pip-installed `sentry-protos`** -- fallback for non-migrated domains
+2. **pip-installed `sentry-protos`** -- fallback
 
 See `src/sentry/utils/PROTO_OVERRIDE.md` for full documentation.
 
-## Initial Migration
-
-To migrate a new domain from `sentry-protos` into this repo:
+## Copying Protos from sentry-protos
 
 ```bash
-bin/sync-protos /path/to/sentry-protos <domain>
+bin/sync-protos /path/to/sentry-protos billing
 ```
-
-After the initial copy, maintain the protos here -- do not re-sync.

src/sentry/utils/PROTO_OVERRIDE.md

@@ -1,12 +1,10 @@
 # Proto Override System
 
-Compile and serve proto definitions directly from the sentry repo, replacing the pip-installed `sentry-protos` package for migrated domains.
+Temporarily override pip-installed `sentry-protos` modules with local `.proto` definitions for faster iteration, without waiting for a `sentry-protos` release.
 
 ## Why This Exists
 
-Proto definitions used to live exclusively in the `sentry-protos` repo, with a separate pip release cycle. Iterating on protos required publishing a new `sentry-protos` version before sentry could use the changes. This system moves proto source files into the sentry repo itself (`proto/`), compiling them at import time during development and pre-compiling them during CI/deploy for production.
-
-Domains are migrated incrementally. Non-migrated domains (snuba, seer, etc.) continue to be served from the `sentry-protos` pip package as a transparent fallback.
+Proto definitions live in the `sentry-protos` repo with a separate pip release cycle. Iterating on protos requires publishing a new `sentry-protos` version before sentry can use the changes. This system lets you place `.proto` files in `proto/` to override specific modules during development, CI, and production. Changes should eventually be published back to `sentry-protos`.
 
 ## Architecture
 
@@ -72,28 +70,26 @@ This works regardless of whether the module comes from `proto/` (override) or th
 ### Priority Order
 
 ```
-1. proto/            (in-repo, committed to git)        ← source of truth
-2. pip sentry-protos (installed package)                 ← fallback for non-migrated domains
+1. proto/            (in-repo overrides)                 ← highest priority
+2. pip sentry-protos (installed package)                 ← fallback
 ```
 
-Migrated domains (e.g., billing) are maintained in `proto/`. Non-migrated domains (snuba, seer, etc.) are served from the pip-installed `sentry-protos` package until they are migrated.
+Protos in `proto/` take precedence. Anything not overridden falls through to the pip package.
 
 ### getsentry
 
 No setup required. Both repos share one venv with sentry editable-installed, so `REPO_ROOT` in `proto_loader.py` resolves to sentry's repo root where `proto/` lives. The `install()` calls in sentry's initializer and pytest plugin cover getsentry automatically — both at runtime and in tests.
 
 Proto overrides placed in sentry's `proto/sentry_protos/` are picked up by getsentry with no getsentry-side changes.
 
-### Migrating a New Domain
+### Copying Protos from sentry-protos
 
-To migrate a domain from `sentry-protos` into this repo (one-time):
+To copy a domain's protos from a local sentry-protos checkout:
 
 ```bash
 bin/sync-protos /path/to/sentry-protos <domain>
 ```
 
-After the initial copy, maintain the protos in `proto/` — do not re-sync.
-
 ## Configuration
 
 Most setups need no environment variables — `proto/` and `.proto_cache/` work by convention.
@@ -145,16 +141,16 @@ proto/                              ← .proto sources (in git)
 
 ## Helper Script: `bin/sync-protos`
 
-A one-time migration tool for copying proto files from a `sentry-protos` checkout into `proto/`. After the initial migration, protos are maintained directly in the sentry repo.
+Copies proto files from a `sentry-protos` checkout into `proto/`.
 
 ```bash
-# One-time migration: copy billing protos from sentry-protos
+# Copy billing protos from sentry-protos
 bin/sync-protos /path/to/sentry-protos billing
 
-# Migrate multiple domains at once
+# Copy multiple domains
 bin/sync-protos /path/to/sentry-protos billing snuba
 
-# Migrate all domains
+# Copy all domains
 bin/sync-protos --all
 
 # Show current override status