microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/contributing/documentation-maintenance.md
102lines · modecode
| 1 | --- |
| 2 | title: Documentation Maintenance |
| 3 | description: How the automated ms.date freshness system detects and flags stale documentation for review |
| 4 | sidebar_position: 8 |
| 5 | author: Microsoft |
| 6 | ms.date: 2026-03-10 |
| 7 | ms.topic: reference |
| 8 | keywords: |
| 9 | - documentation |
| 10 | - ms.date |
| 11 | - freshness |
| 12 | - stale |
| 13 | - maintenance |
| 14 | estimated_reading_time: 4 |
| 15 | --- |
| 16 | |
| 17 | The automated documentation freshness system tracks the `ms.date` frontmatter field across all markdown files and alerts contributors when content becomes outdated. This page explains how the system works, how to fix staleness warnings, and how to configure thresholds for your needs. |
| 18 | |
| 19 | ## Overview |
| 20 | |
| 21 | Every documentation file in this repository is expected to carry an `ms.date` field in its YAML frontmatter. This date reflects when the content was last meaningfully reviewed or updated. The freshness system compares this date against a configurable threshold (default: 90 days) and surfaces stale files through CI annotations, GitHub issues, and a weekly summary. |
| 22 | |
| 23 | The system runs in two contexts: |
| 24 | |
| 25 | | Context | Description | |
| 26 | |-------------------------|----------------------------------------------------------------------------------------------------------------| |
| 27 | | Pull request validation | Checks only the files changed in the PR and fails if any stale files are found. | |
| 28 | | Weekly scheduled scan | Scans all documentation files on Monday mornings and opens GitHub issues for any file exceeding the threshold. | |
| 29 | |
| 30 | ## How It Works |
| 31 | |
| 32 | The `Invoke-MsDateFreshnessCheck.ps1` script reads each file's frontmatter, extracts `ms.date`, and computes the age in days. Files older than the threshold are reported as stale. Results write to: |
| 33 | |
| 34 | * `logs/msdate-freshness-results.json`: machine-readable output consumed by the issue automation workflow |
| 35 | * `logs/msdate-summary.md`: human-readable Markdown summary uploaded to the Actions job summary |
| 36 | |
| 37 | The PR check uses `changed-files-only: true` so contributors only see annotations for the files they actually touched. The weekly scan runs without this filter to find all outdated content across the repository. |
| 38 | |
| 39 | ## Fixing Stale Documentation |
| 40 | |
| 41 | When the freshness check flags a file, take these steps: |
| 42 | |
| 43 | 1. Review the flagged file and verify the content is accurate and current. |
| 44 | 2. Make any necessary content updates. |
| 45 | 3. Update the `ms.date` frontmatter field to today's date in `YYYY-MM-DD` format. |
| 46 | 4. Commit and push. The PR check will re-evaluate the updated date. |
| 47 | |
| 48 | If a file is flagged but the content is still accurate, update `ms.date` to the current date to acknowledge the review. The date reflects the last review date, not necessarily the last time content changed. |
| 49 | |
| 50 | ## Configuration |
| 51 | |
| 52 | The freshness check exposes these parameters: |
| 53 | |
| 54 | | Parameter | Default | Description | |
| 55 | |----------------------------|---------|------------------------------------------------------------------| |
| 56 | | `staleness-threshold-days` | 90 | Days since `ms.date` before a file is considered stale | |
| 57 | | `changed-files-only` | false | When true, only checks files changed relative to the base branch | |
| 58 | |
| 59 | The PR validation workflow configures the check with `changed-files-only: true`. The weekly scan uses `changed-files-only: false` with default threshold to catch all stale files. |
| 60 | |
| 61 | To adjust the threshold repository-wide, update the `staleness-threshold-days` value in both `.github/workflows/pr-validation.yml` and `.github/workflows/weekly-validation.yml`. |
| 62 | |
| 63 | ## Issue Automation |
| 64 | |
| 65 | The weekly scan feeds into `create-stale-docs-issues.yml`, which uses idempotent issue creation to avoid duplicates. Each stale file generates at most one open issue, identified by a hidden automation marker in the issue body: |
| 66 | |
| 67 | ```text |
| 68 | <!-- automation:stale-docs:{file-path} --> |
| 69 | ``` |
| 70 | |
| 71 | When the weekly scan runs again, the workflow searches for existing open issues with this marker. If one exists, it adds a comment with the updated age. If none exists, it creates a new issue labeled `documentation`, `stale-docs`, `automated`, and `needs-triage`. |
| 72 | |
| 73 | Issues are not automatically closed. After updating the documentation and merging your fixes, close the corresponding issue manually or reference it in your pull request for automatic closure. |
| 74 | |
| 75 | ## Troubleshooting |
| 76 | |
| 77 | ### Frontmatter missing or malformed |
| 78 | |
| 79 | The script skips files with no frontmatter block. Stale detection requires a valid `---` delimited YAML block with a parseable `ms.date` field. Files without `ms.date` are logged but not counted as stale. |
| 80 | |
| 81 | ### Date format errors |
| 82 | |
| 83 | Dates must use `YYYY-MM-DD` format. Values like `January 15, 2025` or `2025/01/15` will not parse and the file will be skipped with a warning. |
| 84 | |
| 85 | ### PR check annotations not appearing |
| 86 | |
| 87 | If annotations are missing, check the Actions run for the `ms.date Freshness Check` job and review the uploaded job summary artifact. |
| 88 | |
| 89 | ### Weekly workflow not triggering |
| 90 | |
| 91 | The workflow runs on Mondays at 09:00 UTC via `cron: '0 9 * * 1'`. Use `workflow_dispatch` on the `weekly-validation.yml` workflow to trigger a manual run for testing. |
| 92 | |
| 93 | ## Requirements |
| 94 | |
| 95 | * All documentation files under `docs/` must include a `ms.date` frontmatter field. |
| 96 | * Dates must follow `YYYY-MM-DD` format. |
| 97 | * Contributors are expected to update `ms.date` whenever they review or update a documentation file. |
| 98 | |
| 99 | <!-- markdownlint-disable MD036 --> |
| 100 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 101 | then carefully refined by our team of discerning human reviewers.* |
| 102 | <!-- markdownlint-enable MD036 --> |
| 103 | |