loujaybee · November 24, 2025 18:38
diff --git a/gistfile1.txt b/gistfile1.txt
 # RFC-2024-023: Standardize Backstage Catalog Metadata Across All Repositories

 **Status:** Accepted  
 **Author:** Platform Engineering Team  
 **Created:** 2024-10-15  
 **Last Updated:** 2024-11-20  
 **Decision Date:** 2024-11-18

 ## Summary

 All repositories within the organization must include a `catalog-info.yaml` file at the root level to ensure complete service catalog coverage in Backstage. This RFC defines the required fields, acceptable values, and implementation timeline.

 ## Context

 Our Backstage service catalog currently covers only 42% of our repositories. This creates significant blind spots in our understanding of service ownership, dependencies, and system architecture. Platform teams spend considerable time manually tracking down service owners and understanding system boundaries. Engineering leaders lack visibility into technology distribution and lifecycle states across the organization.

 The incomplete catalog metadata impacts our ability to:
 - Route incidents to the correct teams quickly
 - Understand blast radius for infrastructure changes
 - Track technical debt and deprecated services
 - Plan migrations and technology upgrades
 - Onboard new engineers effectively

 ## Decision

 All repositories must contain a `catalog-info.yaml` file located at the repository root. This file must conform to the Backstage catalog format and include all required fields defined below.

 ## Required Fields

 ### metadata.name
 The unique identifier for the component. Must use the repository name in lowercase with hyphens.

 **Format:** `repository-name`  
 **Example:** `payment-service`, `user-authentication-api`

 ### metadata.description
 A concise description of what the component does, written for someone unfamiliar with the codebase.

 **Format:** Plain text, 1-2 sentences, maximum 200 characters  
 **Example:** "Handles payment processing for customer orders using Stripe and PayPal integrations."

 ### metadata.tags
 Technology stack, purpose, and team identifiers to enable filtering and discovery.

 **Required tags:**
 - Primary programming language (e.g., `python`, `typescript`, `java`, `go`)
 - Component category (e.g., `api`, `library`, `frontend`, `cli`, `data-pipeline`)
 - Visibility (must be either `internal` or `external`)

 **Optional tags:** Team name, business domain, deployment environment

 **Example:** `["python", "api", "internal", "payments-team", "fintech"]`

 ### spec.type
 The type of component according to Backstage taxonomy.

 **Acceptable values:** `service`, `library`, `website`, `documentation`

 **Guidelines:**
 - Use `service` for APIs, microservices, and backend applications
 - Use `library` for shared packages and SDK components
 - Use `website` for frontend applications and static sites
 - Use `documentation` for documentation-only repositories

 ### spec.lifecycle
 The current lifecycle stage of the component.

 **Acceptable values:** `production`, `experimental`, `deprecated`

 **Guidelines:**
 - `production`: Actively used in production environments with SLA commitments
 - `experimental`: Under development or in early testing, not production-ready
 - `deprecated`: Scheduled for retirement, no new features being added

 ### spec.owner
 The team responsible for maintaining the component.

 **Format:** Team identifier in the format `team:team-name`  
 **Example:** `team:platform-engineering`, `team:payments`, `team:data-infrastructure`

 **Note:** Team names must match the team identifiers defined in our org structure. If your team is not yet defined in Backstage, contact Platform Engineering to add it.

 ### spec.system (Required for services only)
 The larger system or product area this component belongs to.

 **Format:** System identifier in the format `system-name`  
 **Example:** `checkout-flow`, `user-management`, `analytics-platform`

 **Note:** System definitions are maintained by Platform Engineering. Reference the current system list in the Backstage catalog or request a new system be created.

 ## Optional Fields

 ### spec.dependsOn
 Components or resources this component depends on.

 **Format:** Array of component references  
 **Example:** `["component:payment-gateway", "component:user-service", "resource:postgres-primary"]`

 ### metadata.links
 Relevant links for the component.

 **Common link types:**
 - `url`: Production URL or landing page
 - `dashboard`: Monitoring or metrics dashboard
 - `docs`: Additional documentation
 - `runbook`: Operational runbooks or incident response guides

 **Example:**
 ```yaml
 links:
  - url: https://payments.example.com
    title: Production Service
  - url: https://grafana.example.com/d/payments
    title: Grafana Dashboard
 ```

 ### metadata.annotations
 Machine-readable metadata for tooling integration.

 **Common annotations:**
 - `github.com/project-slug`: GitHub repository path
 - `pagerduty.com/service-id`: PagerDuty service identifier
 - `sonarqube.org/project-key`: SonarQube project key
 - `circleci.com/project-slug`: CircleCI project path

 ## Implementation Timeline

 **Target completion:** December 31, 2024

 **Phase 1 (Nov 25 - Dec 6):** All production services  
 **Phase 2 (Dec 9 - Dec 20):** All libraries and experimental services  
 **Phase 3 (Dec 20 - Dec 31):** All remaining repositories

 ## Compliance

 Starting January 1, 2025, automated checks will run weekly to identify non-compliant repositories. Non-compliant repositories will be flagged in engineering leadership dashboards. Teams will have a two-week grace period to add or update catalog files before escalation.

 ## Example catalog-info.yaml

 ```yaml
 apiVersion: backstage.io/v1alpha1
 kind: Component
 metadata:
  name: payment-service
  description: Handles payment processing for customer orders using Stripe and PayPal integrations.
  tags:
    - python
    - api
    - internal
    - payments-team
  links:
    - url: https://payments.example.com
      title: Production Service
    - url: https://grafana.example.com/d/payments
      title: Monitoring Dashboard
  annotations:
    github.com/project-slug: example-org/payment-service
    pagerduty.com/service-id: PXYZ123
 spec:
  type: service
  lifecycle: production
  owner: team:payments
  system: checkout-flow
  dependsOn:
    - component:user-service
    - resource:postgres-payments
 ```

 ## Questions or Issues

 For questions about this RFC or help implementing catalog metadata, contact Platform Engineering via #platform-engineering on Slack or email [email protected].

 ## References

 - [Backstage Catalog Format Documentation](https://backstage.io/docs/features/software-catalog/descriptor-format)
 - [Internal Team Registry](https://backstage.example.com/catalog?filters[kind]=group)
 - [Internal System Definitions](https://backstage.example.com/catalog?filters[kind]=system)
	# RFC-2024-023: Standardize Backstage Catalog Metadata Across All Repositories

	Status: Accepted
	Author: Platform Engineering Team
	Created: 2024-10-15
	Last Updated: 2024-11-20
	Decision Date: 2024-11-18

	## Summary

	All repositories within the organization must include a `catalog-info.yaml` file at the root level to ensure complete service catalog coverage in Backstage. This RFC defines the required fields, acceptable values, and implementation timeline.

	## Context

	Our Backstage service catalog currently covers only 42% of our repositories. This creates significant blind spots in our understanding of service ownership, dependencies, and system architecture. Platform teams spend considerable time manually tracking down service owners and understanding system boundaries. Engineering leaders lack visibility into technology distribution and lifecycle states across the organization.

	The incomplete catalog metadata impacts our ability to:
	- Route incidents to the correct teams quickly
	- Understand blast radius for infrastructure changes
	- Track technical debt and deprecated services
	- Plan migrations and technology upgrades
	- Onboard new engineers effectively

	## Decision

	All repositories must contain a `catalog-info.yaml` file located at the repository root. This file must conform to the Backstage catalog format and include all required fields defined below.

	## Required Fields

	### metadata.name
	The unique identifier for the component. Must use the repository name in lowercase with hyphens.

	Format: `repository-name`
	Example: `payment-service`, `user-authentication-api`

	### metadata.description
	A concise description of what the component does, written for someone unfamiliar with the codebase.

	Format: Plain text, 1-2 sentences, maximum 200 characters
	Example: "Handles payment processing for customer orders using Stripe and PayPal integrations."

	### metadata.tags
	Technology stack, purpose, and team identifiers to enable filtering and discovery.

	Required tags:
	- Primary programming language (e.g., `python`, `typescript`, `java`, `go`)
	- Component category (e.g., `api`, `library`, `frontend`, `cli`, `data-pipeline`)
	- Visibility (must be either `internal` or `external`)

	Optional tags: Team name, business domain, deployment environment

	Example: `["python", "api", "internal", "payments-team", "fintech"]`

	### spec.type
	The type of component according to Backstage taxonomy.

	Acceptable values: `service`, `library`, `website`, `documentation`

	Guidelines:
	- Use `service` for APIs, microservices, and backend applications
	- Use `library` for shared packages and SDK components
	- Use `website` for frontend applications and static sites
	- Use `documentation` for documentation-only repositories

	### spec.lifecycle
	The current lifecycle stage of the component.

	Acceptable values: `production`, `experimental`, `deprecated`

	Guidelines:
	- `production`: Actively used in production environments with SLA commitments
	- `experimental`: Under development or in early testing, not production-ready
	- `deprecated`: Scheduled for retirement, no new features being added

	### spec.owner
	The team responsible for maintaining the component.

	Format: Team identifier in the format `team:team-name`
	Example: `team:platform-engineering`, `team:payments`, `team:data-infrastructure`

	Note: Team names must match the team identifiers defined in our org structure. If your team is not yet defined in Backstage, contact Platform Engineering to add it.

	### spec.system (Required for services only)
	The larger system or product area this component belongs to.

	Format: System identifier in the format `system-name`
	Example: `checkout-flow`, `user-management`, `analytics-platform`

	Note: System definitions are maintained by Platform Engineering. Reference the current system list in the Backstage catalog or request a new system be created.

	## Optional Fields

	### spec.dependsOn
	Components or resources this component depends on.

	Format: Array of component references
	Example: `["component:payment-gateway", "component:user-service", "resource:postgres-primary"]`

	### metadata.links
	Relevant links for the component.

	Common link types:
	- `url`: Production URL or landing page
	- `dashboard`: Monitoring or metrics dashboard
	- `docs`: Additional documentation
	- `runbook`: Operational runbooks or incident response guides

	Example:
	```yaml
	links:
	- url: https://payments.example.com
	title: Production Service
	- url: https://grafana.example.com/d/payments
	title: Grafana Dashboard
	```

	### metadata.annotations
	Machine-readable metadata for tooling integration.

	Common annotations:
	- `github.com/project-slug`: GitHub repository path
	- `pagerduty.com/service-id`: PagerDuty service identifier
	- `sonarqube.org/project-key`: SonarQube project key
	- `circleci.com/project-slug`: CircleCI project path

	## Implementation Timeline

	Target completion: December 31, 2024

	Phase 1 (Nov 25 - Dec 6): All production services
	Phase 2 (Dec 9 - Dec 20): All libraries and experimental services
	Phase 3 (Dec 20 - Dec 31): All remaining repositories

	## Compliance

	Starting January 1, 2025, automated checks will run weekly to identify non-compliant repositories. Non-compliant repositories will be flagged in engineering leadership dashboards. Teams will have a two-week grace period to add or update catalog files before escalation.

	## Example catalog-info.yaml

	```yaml
	apiVersion: backstage.io/v1alpha1
	kind: Component
	metadata:
	name: payment-service
	description: Handles payment processing for customer orders using Stripe and PayPal integrations.
	tags:
	- python
	- api
	- internal
	- payments-team
	links:
	- url: https://payments.example.com
	title: Production Service
	- url: https://grafana.example.com/d/payments
	title: Monitoring Dashboard
	annotations:
	github.com/project-slug: example-org/payment-service
	pagerduty.com/service-id: PXYZ123
	spec:
	type: service
	lifecycle: production
	owner: team:payments
	system: checkout-flow
	dependsOn:
	- component:user-service
	- resource:postgres-payments
	```

	## Questions or Issues

	For questions about this RFC or help implementing catalog metadata, contact Platform Engineering via #platform-engineering on Slack or email [email protected].

	## References

	- [Backstage Catalog Format Documentation](https://backstage.io/docs/features/software-catalog/descriptor-format)
	- [Internal Team Registry](https://backstage.example.com/catalog?filters[kind]=group)
	- [Internal System Definitions](https://backstage.example.com/catalog?filters[kind]=system)
No results found