Product rename checklist

Product rename checklist

Goal: every place a person sees the old name shows the new one, and nothing that depends on the old string breaks.

1. Map it before changing anything

1. Find the name in every form: display ("OldName"), lowercase ("oldname"), uppercase env prefixes (OLDNAME_), domains, package scopes, file names, routes, and class names. Count hits per folder so the size of the job is clear.
2. Find where the name is defined. If there is no single constant, create one (name, display name, logo text, domain) and make code read from it.
3. Ask which history docs keep the old name on purpose (naming notes, changelogs, progress logs). Those get a note about the decision, not a rewrite.

2. Decide what must not change

Changing these breaks things for existing users or data. List them, keep them, and say why in the summary:

• Signing and hashing domain strings (for example oldname-sig-v1). Changing them invalidates every existing signature.
• Key-derivation labels and salts (HKDF info strings, telemetry salts). Changing them changes derived secrets and ids.
• OAuth client ids and registered redirect names.
• Ids stored in the database: scanner rule ids, event names, JSON markers inside stored documents.
• Database migrations. Never edit an applied migration.
• Seeds for generated art or tests, if changing them changes something people have already seen.
• Internal package scopes and class names, unless the owner wants them changed too. They are invisible to users and cost a lot to rename.

3. Change the name

1. Set the constants. Remember that derived names move too: the CLI binary, config folder, lock file name, env var prefix, keychain service, user agent, crawler name.

2. Sweep the rest with explicit, ordered replacements: specific forms first (domains, env prefixes, file names), then the display name, then the lowercase word with boundaries so it does not match inside identifiers you are keeping.

   • In zsh, for f in $FILES does not split on newlines. Loop with while IFS= read -r f instead, or nothing gets rewritten.
   • Watch for false matches: oldname.com (a competitor's domain in a history note) is not your new domain.
3. Rename files and routes that carry the name with git mv, and update every import and test that points at them.
4. Update user-facing copy by hand where the old name was part of a sentence, so it still reads well.
5. Rename plugin and marketplace manifests, skill folders, Docker and deploy app names, and sample URLs in tests.
6. Delete generated caches that hold old paths (framework type caches), or typecheck fails on files that no longer exist.

4. Check it

1. Grep for every old form again. Each remaining hit must be on the keep list or in a history doc.
2. Run lint, typecheck, and tests. Fix test fixtures where the sweep changed an expected value but not its input.
3. Open the app: header, titles, page metadata, icons, emails, CLI help, and any page that shows commands.
4. Write down the breaking changes for local users (new env var names, lock file name, plugin id) in the changelog.

Rules

• Show the map and the keep list, and get a yes before editing.
• One commit for the rename, with the keep list in its message.
• Never change signing, key-derivation, or stored identifiers without a migration plan the owner approved.