Design and implement processes and communications

1.1 Traceability & flow of work

GitHub Flow and the other flow models

GitHub Flow is a lightweight, branch-based workflow for teams that deploy continuously. There is exactly one long-lived branch (main), which is always deployable.

Feedback cycles

A "feedback cycle" is any loop that gets information back to the person who can act on it — the shorter the loop, the cheaper the fix.

Integration for tracking work

Azure Boards work item hierarchy

Azure DevOps ships four inherited process templates: Basic (default, simplest), Agile, Scrum and CMMI (adds formal change requests and risks). You customise by creating an inherited process — you cannot edit the system processes directly.

Linking commits and PRs to work items

The AB# syntax is the glue between GitHub and Azure Boards, and it is heavily tested.

# Link only (no state change)
git commit -m "Refactor the payment gateway AB#1234"

# Link AND transition the work item to its "completed" state on merge
git commit -m "Fix null reference on checkout fixes AB#5678"
git commit -m "Closes AB#199, implements AB#204"

• Transition keywords: fix, fixes, fixed, close, closes, closed, resolve, resolves, resolved — used immediately before the AB#ID.
• Inside Azure Repos the same idea uses a plain #ID mention; AB# exists because GitHub already uses # for its own issues.

Azure Boards ↔ GitHub connection

1. In Azure DevOps: Project Settings → GitHub connections → Connect your GitHub account.
2. Authenticate — the Azure Boards GitHub App is the recommended method (scoped permissions, no personal token). OAuth and a PAT are the fallbacks.
3. Select the repositories to connect. One GitHub repo can only be connected to one Azure DevOps project at a time.
4. Use AB#ID in commits, PR titles/descriptions and branch names to create links automatically.

Once connected you get: work-item links visible from the Development section of the work item, GitHub PR status shown on the Kanban card, and automatic state transitions on merge.

GitHub Projects

• Projects (the current version) is a flexible, spreadsheet-plus-board planning surface with table, board and roadmap views, custom fields (single-select, number, date, iteration), grouping, filtering and slicing.
• Items are issues, pull requests, or free-form draft issues that exist only in the project.
• Built-in workflows automate transitions — e.g. "when an item is closed, set Status to Done"; deeper automation uses the GraphQL API or GitHub Actions.
• Insights generates charts directly from project data (current and historical).

Source, bug and quality traceability

End-to-end traceability means you can start from any artefact and reach every other one:

1.2 Metrics & queries for DevOps

DORA metrics — the four keys

Flow metrics — cycle time vs lead time

Dashboards, widgets and Analytics

Azure DevOps reporting is built on the Analytics service, a read-optimised store fed from work-tracking and pipeline data. It is exposed three ways:

Metrics by discipline

The skills measured list metrics for seven areas explicitly. Know a couple of representative metrics for each.

1.3 Collaboration & communication

Wikis and process diagrams

Mermaid in wikis — the syntax differs by platform

Both platforms render Mermaid, but Azure DevOps wikis do not use fenced code blocks — they use a colon-delimited container. This distinction is directly examinable.

::: mermaid
graph TD
    A[Developer] --> B[Push code]
    B --> C{PR review}
    C -->|Approved| D[Merge to main]
    C -->|Changes| A
:::

```mermaid
graph TD
    A[Developer] --> B[Push code]
    B --> C{PR review}
    C -->|Approved| D[Merge to main]
    C -->|Changes| A
```

Release documentation

Auto-generated release notes

permissions:
  contents: write

steps:
  - uses: actions/checkout@v4
    with: { fetch-depth: 0 }

  - name: Create release
    env:
      GH_TOKEN: ${{ github.token }}
    run: |
      gh release create "${{ github.ref_name }}" \
        --generate-notes \
        --title "Release ${{ github.ref_name }}"

changelog:
  exclude:
    labels: [ignore-for-release]
  categories:
    - title: ⚠️ Breaking changes
      labels: [breaking-change]
    - title: ✨ Features
      labels: [enhancement, feature]
    - title: 🐛 Fixes
      labels: [bug]
    - title: Other changes
      labels: ["*"]

• GitHub: Generate release notes builds the changelog from merged PR titles and authors since the previous tag; .github/release.yml controls grouping and exclusions.
• Azure DevOps: query the build's associated work items and commits via the REST API (build/builds/{id}/workitems and /changes), or use a marketplace release-notes task; a build's associated items are computed from the previous successful build of the same pipeline.

API documentation

• OpenAPI/Swagger specs generated from code annotations (Swashbuckle for .NET, springdoc for Java) and published as a pipeline artifact.
• Azure API Management imports the OpenAPI spec and publishes a developer portal — automate the import as a release step so docs never drift from the deployed API.
• DocFX generates a documentation site from .NET XML comments plus Markdown; publish it to GitHub Pages or Azure Static Web Apps from the pipeline.

Automating documentation from Git history

Automated changelogs depend on machine-readable commit messages. The Conventional Commits convention is the standard the tooling assumes.

<type>[optional scope][!]: <description>

[optional body]

[optional footer(s)]   # e.g. BREAKING CHANGE: <what changed>

# Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

# Examples
feat(auth): add SSO via Entra ID          → MINOR version bump
fix(api): handle null order id             → PATCH version bump
feat(api)!: drop support for v1 endpoints  → MAJOR version bump

# All commits since the last tag, as a markdown list
git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"- %s (%h)"

# Tools that do this properly:
#   semantic-release  — full release automation (version, tag, notes, publish)
#   standard-version  — local versioning + CHANGELOG.md
#   git-cliff         — highly configurable changelog generator (Rust)
#   GitHub native     — "Generate release notes" from PR titles

Webhooks and service hooks

A webhook is an outbound HTTP POST that the platform sends to your endpoint when an event occurs — push-based, so no polling.

Integration with Microsoft Teams

Domain 1 rapid recap