Maintaining a redirect map over years: one source file, generated rules, tests and retirement

Goal

Old URLs keep working through redesigns, domain changes and CMS migrations, without the redirect configuration turning into an unreadable pile that nobody dares to edit.

Prerequisites

A versioned repository for site configuration, a web server or host whose redirect rules can be generated from data (nginx map, a hosting provider's redirects file, or an edge function), access logs that record status codes and request paths, and the redirect-status article for choosing between 301, 302, 307 and 308.

Steps

1. Create one source file (CSV, YAML or a table in the repository) with columns: source path, target URL, status code, reason, date added, ticket or commit. Nothing is redirected that this file does not list.
2. Generate the server rules from it. With nginx, a map creates a variable whose value depends on the request URI, and the documentation notes that declaring many map variables costs nothing until the variable is used; include the generated file and issue return 301 $target; when the variable is non-empty; return takes a literal code, so generate one map per status code. Other hosts get their native format from the same generator.
3. Normalise before matching: lower-case the host, strip trailing slashes consistently with the site's URL rules, and preserve the query string only where the target needs it.
4. Choose codes by intent. Google's documentation says to use permanent redirects when you are sure the redirect will not be reverted, because a permanent redirect is then used as a signal that the target should be the canonical page, while a temporary one is not; use temporary codes for campaigns and maintenance.
5. Add a test that requests every source path and asserts the first response has the expected status and Location, and that the target answers 200 without further redirects. Run it in CI on every change and on a schedule.
6. When a target itself moves, rewrite the old entries to point at the final destination; never let entries chain.
7. Retire by evidence: an entry that has not been hit for a long period, checked in logs, may be removed; record the removal and the log window in the file's history. Entries from printed material or external links with unknown lifetime stay.

Expected result

Every redirect is explained, tested and reachable in one hop; a migration adds rows to a file and a CI run, not hand-written regular expressions.

Limits and test basis

Pattern redirects (whole directory trees) still need a few regular expressions; keep them in the same file with a test per pattern. Retention periods are a judgement, not a measurement; the linked hypothesis concerns chains, and no figures are claimed here.