ASR-0002 Decouple Engineering and Product Names

Andi Lamprecht ·2026-05-11· 2 min read· Accepted

Decouple Engineering Resources from Product Names

Summary

Engineering resources should use unique, internal only names that do not reference external product names. By decoupling resource naming, engineering resources will not need to change to align with changing product concerns.

Leagues are a product facing concern intended to encapsulate the resources supporting a specific product. As such, they should not be used as an identifier inside of engineering.

Requirements

Engineering resources do not map 1:1 to Leagues and should not use the League name or other product facing names as an identifier.

Engineering resource names are intended only for internal use. Customers should never need to map what the resource name is to a product.

Resource names should be unique and follow a consistent pattern:

• If auto-generated, all resources should use the same auto-generated pattern. EG: adjective-noun-number
• If human supplied, a naming scheme should be identified to make naming across the resource consistent and easily identifiable.

When autogenerating resource names, prefer human readable slugs (eg “gray-heron-19”) over naming schemas intended only for machine to machine processes (eg UUIDs).

A single source of truth should be maintained that maps engineering resource identifiers to any product facing names, the team or teams responsible for the development and management of the resource, and any dependencies.

• Example: “blue-tango-12” = [league:uncrew, team:apollo, service:internal-api, github:blue-tango-api]

Key names for resources should be immutable and unique. EG: a GCP project should have 1 and only 1 name throughout its life, when performing a lookup of that name in the source of truth it should only ever map to that 1 GCP project.

The object values for the datastore should assume any and every associated resource is mutable and fungible. Examples:

• A service could move ownership from one team to another.
• A product League may change its name.
• A GCP project could be managed by multiple engineering teams.

Wherever possible, resources should use documentation, tags, descriptions, or other metadata to list all associated resources.