DevOps Best Practice Document: Repository Naming Conventions

Introduction

This document outlines the recommended best practices for naming repositories within our IT software development environment. Adhering to these conventions is crucial for maintaining a well-organized codebase, fostering collaboration, enhancing code discoverability, and streamlining our DevOps workflows. Consistent naming improves clarity, reduces ambiguity, and makes it easier for all team members to understand and navigate our projects.

Core Principles of Repository Naming

• Clarity and Descriptiveness: The repository name must immediately convey its purpose, content, and primary functionality. It should be self-explanatory to anyone viewing the repository list.
• Consistency: A uniform naming scheme will be applied across all repositories, projects, and teams. This ensures predictability and ease of navigation regardless of the specific project.
• Readability: Names should be easy to read and mentally parse, avoiding overly complex or cryptic abbreviations.
• Conciseness: While descriptive, names should be as short as possible without sacrificing clarity.
• Searchability: Well-structured and consistently named repositories are significantly easier to locate using search tools and filters.
• Future-Proofing: Repository names should be stable and not require frequent changes. Avoid including information that is prone to change (e.g., version numbers).
• URL and File System Compatibility: Names must only use characters that are safe and compatible with URLs and common file system paths.

Recommended Naming Elements and Formats

General Formatting Rules

• Lowercase: All repository names MUST be in lowercase.
• Separators:
  • Hyphens (-): Preferred separator for words within a repository name (e.g., my-project-api). Hyphens enhance readability, especially in URLs, and are widely adopted.
  • Underscores (_): Are NOT to be used as word separators.
• No Spaces: Spaces are strictly forbidden in repository names.
• No Special Characters: Only alphanumeric characters (a-z, 0-9) and hyphens (-) are permitted. Avoid characters such as /, \ , :, |, ?, *, ", <, >, etc.
• No Leading/Trailing Hyphens: Repository names should not start or end with a hyphen.

Recommended Naming Structure

The general structure for repository names will follow a [PREFIX]-[COMPONENT]-[TYPE] pattern, though variations are acceptable based on the specific context.

• [PREFIX] (Required for multi-project/large organizations):
  Identifies the overarching project, product, or the owning team/department. Should NOT include elements of the organization name.
  Purpose: Helps to logically group related repositories and prevent naming conflicts in larger environments.
  Examples: ecommerce, crm, hr-payroll, devops, shared
• [COMPONENT] (Required):
  Describes the specific part, service, or feature that the repository contains. This should be as descriptive as possible.
  Purpose: Clearly states what the repository is.
  Examples: user-management, order-processing, data-ingestion, payment-gateway, notification-service, customer-portal
• [TYPE] (Recommended for clarity, especially in microservices architectures):
  Indicates the architectural type, primary technology, or deployment target of the component.
  Purpose: Provides immediate context on the nature of the codebase.
  Examples:
  • -api: For RESTful APIs or backend services.
  • -service: For general backend services or microservices.
  • -ui: For user interface/frontend applications.
  • -web: For generic web applications.
  • -mobile-ios, -mobile-android, -mobile-flutter: For mobile applications.
  • -lib, -common, -shared: For shared libraries or common utility code.
  • -docs: For project documentation.
  • -config: For configuration repositories (e.g., central config service).
  • -infra, -terraform, -cloudformation: For infrastructure-as-code.
  • -pipeline, -scripts: For CI/CD pipeline definitions or automation scripts.
  • -data-etl: For data extraction, transformation, and loading processes.
  • -cli: For command-line interface tools.

Example Repository Names

Category	Example Name(s)	Description
Backend/API	ecommerce-product-api	Backend API for product management within the e-commerce project.
	crm-customer-service	Microservice managing customer data for the CRM system.
Frontend/UI	ecommerce-admin-ui	Frontend application for the e-commerce administration panel.
	crm-customer-portal-web	Web-based customer portal for the CRM system.
Mobile	mobile-app-ios	iOS specific mobile application.
	mobile-app-android	Android specific mobile application.
Shared/Libraries	shared-java-common-lib	Common Java utility library used across multiple projects.
	devops-shared-pipeline-templates	Reusable CI/CD pipeline templates for DevOps.
Infrastructure	infra-aws-eks-cluster	Terraform/CloudFormation code for AWS EKS cluster infrastructure.
	infra-vpc-network-config	Repository holding VPC and network configuration.
Documentation	api-gateway-docs	Documentation specific to the API Gateway service.
	platform-developer-guide	General developer guide for the entire platform.
Tools/Scripts	devops-monitoring-scripts	Scripts for monitoring infrastructure and applications.
	data-etl-customer-sync	Data pipeline for synchronizing customer data.
Project-Specific	projectx-main-app	A monolithic or full-stack application for "Project X".
	projectx-auth-service	Authentication service for "Project X".

What to Avoid

• Version Numbers in Name: DO NOT include v1, v2, final, latest, staging, prod etc., in the repository name. Use Git tags, branches, or release management tools for versioning and environment-specific deployments.
• Generic Names: Avoid ambiguous names like my-repo, project-alpha, test, temp.
• Developer Names: Do not include individual developer names (e.g., john-doe-feature).
• Redundancy: Avoid repeating information that is already clear from the project context or existing naming elements.
• Acronyms without Context: While some well-known acronyms are acceptable (e.g., api, ui, cli), avoid obscure or internal-only acronyms without clear documentation.

Enforcement and Documentation

1. Training and Communication: All team members, especially new hires, will be educated on these naming conventions. Regular reminders will be issued as needed.
2. Code Review/Pull Request Checks: During code reviews or pull request processes, reviewers should ensure that any new repositories adhere to these guidelines.
3. Documentation: This document will be accessible to all developers and regularly reviewed and updated as our practices evolve. It should be linked in relevant onboarding materials and team wikis.
4. Automated Checks (Future Consideration): Where feasible, consider implementing automated checks in CI/CD pipelines or repository creation tools to enforce naming conventions programmatically.

By consistently applying these best practices, we will foster a more organized, efficient, and collaborative development environment, ultimately contributing to higher quality software delivery.