Skip to main content

GitHub Repository Naming

info

This content is mandatory for new repositories

This best practice describes how to name GitHub repositories.

Rationale​

Having a consistent git repo naming convention makes identifying and maintaining git repositories easier for engineers.

For each convention the relevant rationale is as follows:

  1. Having a standard case format keeps consistency across repos. We need to decide on one and this aligned more with other external repos (i.e. GitHub; see reference image below).
  2. All GitHub projects are within the CRUKorg organisation. There is no need to add another prefix as this is already prepended. Furthermore it makes sorting and searching more difficult.
  3. Clearly identifying what product is associated with a repo aids readability and search.
  4. Implementations can change over time; there is no need to specify this in the repo.
  5. This suggests a break from a monorepo approach where all product packages are within a single repo. Consider removing the suffix and combining the repos.
  6. Avoid terms that will not evolve with the product and lock in specific aspects. For example activity-management-angular-app is not future friendly if the app should move to react. Doing this avoids unnecessary repo name changes in the future.
  7. Ideally the product name should be in the repo; without it generic names are formed which are unhelpful. Names such as submission, event, server-api are too generic and are not descriptive on what the repo is.
  8. This aids search, sorting and keeps like products together.

Description​

When naming (or renaming) a GitHub repo please follow the following conventions.

  1. Use kebab-case; all lowercase letters with words separated by hyphens.
  2. Do not prefix with cruk.
  3. Keep the name clear and concise.
  4. Avoid specific implementation details i.e.: php, rest, serverless.
  5. Avoid client and server suffixes; instead use a monorepo approach.
  6. Future friendly.
  7. Descriptive.
  8. If multiple repos are required keep prefixes the same for the same product.

Renaming a legacy repository may not be possible, in which case we recommend adding an 'about' to the repo to provide further context if its name doesn't follow the above convention.

Examples​

Names that follow the convention: ✔️

  • activity-management
  • engineering-guidebook
  • semarchy
  • tibco
  • ecommerce
  • cookie-banner
  • online-payments
  • personhub

Names that do not follow the convention: ❌

  • cruk-activity-management : unnecessary cruk prefix.
  • cruk_engineering_guidebook : underscores instead of hyphens.
  • ActivityManagement : mixed case
  • activity-management-client & activity-management-service : suggests a break in monorepo convention. Combine repos where possible for the same products.
  • activity-management-haskell-websphere : Locked in implementation details that are not future proofed.