diff --git a/.acrolinx-config.edn b/.acrolinx-config.edn index cddebf863..7ca95fa35 100644 --- a/.acrolinx-config.edn +++ b/.acrolinx-config.edn @@ -1,5 +1,5 @@ {:allowed-branchname-matches ["main"] - :allowed-filename-matches ["playfab-docs/features" "playfab-docs/data-analytics" "playfab-docs/playstream" "playfab-docs/gamemanager" "playfab-docs/miscellaneous" "playfab-docs/release-notes" "playfab-docs/resources" "playfab-docs/sdks"] + :allowed-filename-matches ["playfab-docs/data-analytics" "playfab-docs/demo-game" "playfab-docs/economy-monetization" "playfab-docs/get-started" "playfab-docs/identity" "playfab-docs/includes" "playfab-docs/live-service-management" "playfab-docs/media" "playfab-docs/miscellaneous" "playfab-docs/multiplayer" "playfab-docs/player-progression" "playfab-docs/pricing" "playfab-docs/release-notes" "playfab-docs/resources" "playfab-docs/sdks" "playfab-docs/test-documents" "playfab-docs/whats-new"] :targets { @@ -11,7 +11,7 @@ } :scores { ;;:terminology 100 - :qualityscore 70 + :qualityscore 80 ;;:spelling 40 } } diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 6b7393165..0ba70ebab 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -5,4 +5,4 @@ # The '*' pattern is global owners. -/playfab-docs/ @KevinAsgari @williacj @thomasgu +/playfab-docs/ @MicrosoftDocs/xbox-learning-resources diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..198e45db6 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,23 @@ +## What changed + + + +## Related work items + + + +## Checklist + +- [ ] All new/modified articles have complete frontmatter (`author`, `title`, `description`, `ms.author`, `ms.topic`, `ms.date`, `ms.service`) +- [ ] `title` field is present (required for builds) +- [ ] `ms.date` updated on edited articles +- [ ] New articles added to the relevant `toc.yml` +- [ ] Images have descriptive alt-text for accessibility +- [ ] No raw HTML — use only standard Markdown and Learn extensions +- [ ] No broken links to other articles +- [ ] Cross-repo links use site-relative paths (no `.md` extension) +- [ ] Content is public-friendly (no confidential info or codenames) +- [ ] Build validation email reviewed — errors and warnings resolved +- [ ] Acrolinx score is 80+ (check automated PR test results) +- [ ] Ran `.\scripts\validate-docs.ps1` locally +- [ ] PR targets **main** diff --git a/.github/agents/docs-reviewer.md b/.github/agents/docs-reviewer.md new file mode 100644 index 000000000..77ba80b77 --- /dev/null +++ b/.github/agents/docs-reviewer.md @@ -0,0 +1,248 @@ +--- +name: docs-reviewer +description: > + Reviews changed PlayFab documentation files for compliance with authoring standards. + Validates frontmatter fields, markdown restrictions, TOC consistency, image alt-text, + heading structure, cross-repo linking rules, and writing style (Acrolinx). Reports + issues without modifying files. +tools: + - grep + - glob + - view + - powershell +--- + +# PlayFab Documentation Reviewer Agent + +You are a documentation reviewer for the PlayFab docs repo. Your job is to **review changed files** and **report issues** — never modify files. + +## How to Run a Review + +1. Get the list of changed `.md` and `toc.yml` files relative to `main`: + +``` +git --no-pager diff --name-only main -- 'playfab-docs/**/*.md' 'playfab-docs/**/toc.yml' +``` + +If that fails (e.g., no `main` branch locally), fall back to uncommitted changes: + +``` +git --no-pager diff --name-only HEAD -- 'playfab-docs/**/*.md' 'playfab-docs/**/toc.yml' +``` + +2. For each changed file, run the applicable checks below. +3. Produce a summary report at the end. + +--- + +## Checks for Markdown Files (`playfab-docs/**/*.md`) + +### 1. Required Frontmatter Fields + +Every `.md` file must have YAML frontmatter (`---` delimiters). The following fields are **always** required: + +| Field | Validation | +|---|---| +| `author` | Must be present and non-empty | +| `ms.author` | Must be present and non-empty | +| `ms.topic` | Must be one of: `article`, `conceptual`, `reference`, `include`, `hub-page`, `overview`, `release-notes` | +| `ms.date` | Must be present, format `MM/DD/YYYY` | +| `ms.service` | Must be `azure-playfab` | + +The following fields are required for **article pages** (any `ms.topic` value except `include`): + +| Field | Validation | +|---|---| +| `title` | Must be present and non-empty. **Build fails without it on article pages.** | +| `description` | Must be present, under 160 characters | + +> **Note:** `title` and `description` are not required for `ms.topic: include` files but are still allowed. + +Flag: `MISSING_FIELD`, `INVALID_VALUE`, or `EMPTY_FIELD` with the field name. + +### 2. Raw HTML Detection + +Scan the body (below frontmatter) for raw HTML tags. HTML is not permitted — only standard Markdown and Learn extensions. + +Skip content inside fenced code blocks (` ``` `). + +Common tags to detect: `