Skip to content

Governance standard

This document defines the project creation, naming, structure, and change management rules that apply across all HCS projects on ADO, GitHub, and GitLab.

Naming conventions

GitHub repos

  • Format: lowercase-kebab-case
  • Be specific enough to distinguish the repo at a glance
  • Prefix with the project family when repos are related: azurelocal-ranger, azurelocal-surveyor
  • Examples: platform-engineering, azure-scout, hcs-bicep-modules

ADO projects

  • Format: Title Case with spaces
  • Examples: Platform Engineering, Azure Local Cloud, TierPoint Automation

ADO area paths

Every ADO project has a defined area path structure. Area paths reflect the domains of work in that project. Example for Platform Engineering: - Standards and Governance - Documentation - Templates - Integrations - Onboarding - Tooling

Area paths are created once per project and should not be renamed without updating all existing work items.

ADO iterations

Iterations follow a monthly cadence: 2026-05, 2026-06, etc. Sprint-based projects may use: Sprint 1, Sprint 2, etc. Establish the pattern for a project at creation time.

GitLab repos

  • Same kebab-case convention as GitHub
  • Prefix group name matches the ADO project or GitHub org it mirrors

Required files in every new repo

Every repo that is created, regardless of size, purpose, or audience, must have these files at the root before any functional work is committed:

File Purpose
README.md Public-facing description: what it is, prerequisites, quick start, links to docs
CLAUDE.md Claude Code context. Generated from templates/CLAUDE.md.template. Required before any Claude Code session.
.gitignore Start from templates/repo-scaffold/.gitignore.template. Customize as needed.
LICENSE MIT by default for open-source repos. Proprietary for internal HCS tooling.

Repo visibility

  • Private by default. A new repo is private until there is a deliberate decision to make it public.
  • Public only for: published open-source tools, documentation sites, sample code intended for public reference.
  • Never public: anything containing internal architecture, identity references, customer data, or unreleased product work.

Branch strategy

  • main is the protected default branch. Direct commits to main are prohibited.
  • Feature work goes on branches named feature/short-description — e.g., feature/add-kv-loader
  • Bug fixes: fix/short-description
  • Documentation: docs/short-description
  • Chores: chore/short-description
  • Branches are deleted after merge — no long-lived feature branches.

Branch protection rules (apply to every repo)

  • Require at least one approval before merge (self-approval counts for solo repos)
  • Require the branch to be up to date before merging
  • No force pushes to main
  • No deletion of main

Pull request requirements

Every PR must have:

  1. A description — at minimum one sentence explaining what changed and why
  2. A linked ADO work item — include AB#<id> in the PR title or description
  3. A reviewer — at minimum self-review with deliberate sign-off; team repos require one peer review
  4. Passing CI — if a pipeline is configured, it must pass before merge

PR titles follow the same commit format: type(scope): short description

Commit message format

type(scope): short description under 72 characters

Optional longer body explaining the why, not the what.
Link work items: AB#1234

Types:

Type Use for
feat New feature or capability
fix Bug fix
docs Documentation only
chore Maintenance, dependency updates, config changes
refactor Code change that neither adds a feature nor fixes a bug
test Adding or updating tests

How to register a new project

When starting a new project:

  1. Create the repo (GitHub or ADO) following the naming convention above
  2. Copy templates/repo-scaffold/ into the repo root
  3. Fill in templates/CLAUDE.md.template and commit it as CLAUDE.md
  4. Create or identify the ADO project and area path for work items
  5. If the project introduces new secrets or identities, register them in docs/identity/ in this repo
  6. If the project introduces new standards deviations or extensions, document them in the repo's own CLAUDE.md

There is no formal registration table in this repo — the git history, ADO work items, and docs/identity/ registries collectively serve as the record.

New repo setup checklist

Complete these steps in order when standing up any new HCS repo. Do not skip steps — the order matters.

Step Action
1 Create the repo under the correct org (ADO or GitHub) following the naming convention
2 Clone locally and initialize with git init if not cloned from remote
3 Add required root files: README.md, CLAUDE.md, .gitignore, LICENSE
4 Add docs/ directory with index.md or equivalent landing page
5 Add mkdocs.yml if the repo will have a documentation site
6 Add .ado/ or .github/workflows/ with at minimum a CI validation pipeline
7 Add config/variables.example.yml if the repo deploys infrastructure
8 Register any new secrets or service principals in docs/identity/ in this (platform) repo
9 Set branch protection on main: require PR, require 1 approval, no force push
10 Add the repo to the ADO project board under the correct area path
11 Add required labels (see issue management section below)

Required root files

File Purpose
README.md What it is, prerequisites, quick start, links to full docs
CLAUDE.md Claude Code context, generated from templates/CLAUDE.md.template
.gitignore Start from templates/repo-scaffold/.gitignore.template
LICENSE MIT for open-source, proprietary for internal HCS tooling

Required docs/ structure

docs/
├── index.md                    # Landing page
├── standards/                  # If the repo has its own standards extensions
└── architecture/               # draw.io + PNG diagrams
    ├── overview.drawio
    └── overview.png

Required directory structure if deploying infrastructure

config/
├── variables.example.yml       # Template with all keys, no secret values
└── variables.yml               # Local override — gitignored, never committed

Issue management model

Labels

Labels classify what kind of work an issue represents. Every issue must have exactly one type/* label and exactly one priority/* label.

Type labels:

Label Use for
type/feature New feature or capability
type/bug Something is not working
type/docs Documentation changes only
type/infra Pipeline, workflow, or repo config changes
type/refactor Code restructure with no behavior change
type/security Security fix or hardening
type/question Question or discussion

Priority labels:

Label Use for
priority/critical Must fix immediately — blocks release or active work
priority/high Next sprint
priority/medium Planned
priority/low Nice to have

Status labels (supplementary):

Label Use for
status/blocked Blocked by an external dependency
status/needs-info Waiting for more information
status/wontfix Declined — close with explanation

Milestones

Milestones group issues by delivery phase within a repo. They answer "when does this land?" — not "what kind of work is this?"

Each repo defines milestones that match its delivery phases. Common pattern:

  • Planning — architecture, design, pre-implementation
  • Foundation — core scaffolding, required files, CI setup
  • V1 — first functional release
  • Post-V1 — extensions and backlog

Every issue representing planned delivery work should have a milestone. Housekeeping issues may omit one.

Tracker issues

For large workstreams, open a single tracker issue that lists sub-tasks as checkboxes. This gives a single URL to share that shows overall progress. Link child issues with AB#<id> in the body.

## Scope

This issue tracks all work for the platform engineering repo scaffold.

## Tasks

- [x] AB#101 — Scaffold required root files
- [x] AB#102 — Write identity documentation
- [ ] AB#103 — Standards documentation complete
- [ ] AB#104 — Templates finalized

Release model

All HCS repos that ship versioned artifacts use release-please for automated changelog generation and release management.

How it works

  1. Contributors use conventional commits when merging to main.
  2. Release-please reads commit messages and maintains an open release PR that updates CHANGELOG.md and bumps the version.
  3. When the release PR is merged, release-please creates a release and tag.

Required files

File Purpose
CHANGELOG.md Maintained by release-please. Do not edit manually.
release-please-config.json Release-please configuration.
.release-please-manifest.json Version tracking manifest.

release-please-config.json

{
  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
  "release-type": "simple",
  "bump-minor-pre-major": true,
  "changelog-sections": [
    { "type": "feat",     "section": "Features" },
    { "type": "fix",      "section": "Bug Fixes" },
    { "type": "docs",     "section": "Documentation" },
    { "type": "chore",    "section": "Chores", "hidden": false }
  ]
}

Exceptions

Repos that are purely documentation, experimental, or have no versioned artifact may omit release-please. Document the exception in the repo's README.md.