diff --git a/.acrolinx-config.edn b/.acrolinx-config.edn deleted file mode 100644 index cddebf863..000000000 --- a/.acrolinx-config.edn +++ /dev/null @@ -1,42 +0,0 @@ -{: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"] - - :targets - { - :counts { - ;;:spelling 10 - ;;:grammar 3 - ;;:total 15 - ;;:issues 15 - } - :scores { - ;;:terminology 100 - :qualityscore 70 - ;;:spelling 40 - } - } - - :template-header ;; This displays in the pull request results pane. Can be overriden in repo-specific edn file. Ensure you match the indentations at the line starts exactly. - " - ## Acrolinx Scorecards - -**The minimum Acrolinx topic score of 80 is required for all content merged to the default branch.** - -Click the scorecard links for each article to review the Acrolinx feedback on grammar, spelling, punctuation, writing style, and terminology. - -| Article | Acrolinx
score | Lowest
category
score | Spelling
issues | Scorecard | Processed | -|---------|:--------------:|:--------------------:|:------:|:---------:|:---------:| -" - - :template-change ;; Can be overriden in repo-specific edn file. This displays in the pull request results pane. - "| ${s/file} | ${acrolinx/qualityscore} | ${acrolinx/scores/min-score} | ${acrolinx/flags/spelling} | [link](${acrolinx/scorecard}) | ${s/status} | -" - - :template-footer ;; Can be overriden in repo-specific edn file. This displays in the pull request results pane. - " -**More information about Acrolinx** -- [Install Acrolinx locally for VSCode](https://review.docs.microsoft.com/help/contribute/contribute-acrolinx-vscode) -- [False positives or issues](https://aka.ms/acrolinxbug) -- [Troubleshooting issues with Acrolinx](https://review.docs.microsoft.com/help/contribute/acrolinx-error-messages) -" -} diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 6b7393165..8e5994779 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -5,4 +5,9 @@ # The '*' pattern is global owners. -/playfab-docs/ @KevinAsgari @williacj @thomasgu +/playfab-docs/ @MicrosoftDocs/xbox-learning-resources + +# PlayFab Party, Lobby, and Matchmaking client SDK docs are jointly managed by the x1net team and the playfab SDKs team +/playfab-docs/multiplayer/lobby @MicrosoftDocs/xbox-learning-resources @ScottMunroMS @tomcoMSFT @BerniME @Vicodex @SebastianPD @raymondchams @yuehanlin +/playfab-docs/multiplayer/matchmaking @MicrosoftDocs/xbox-learning-resources @ScottMunroMS @tomcoMSFT @BerniME @Vicodex @SebastianPD @raymondchams @yuehanlin +/playfab-docs/multiplayer/networking @MicrosoftDocs/xbox-learning-resources @ScottMunroMS @tomcoMSFT @BerniME @Vicodex @SebastianPD @raymondchams @yuehanlin 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: `
`, ``, ``, ``, `
`, `
`, `

`, ``, ``, `