From 218e741bff8e94957f62d53ba1f85713d3fa7b98 Mon Sep 17 00:00:00 2001 From: Bobby Tiernay Date: Tue, 18 Nov 2025 09:14:14 -0500 Subject: [PATCH 1/4] feat: add GitHub pull request template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add practical PR template tailored to docs-v2 monorepo structure and workflow. Template includes emoji headings matching Auth0 conventions, dedicated redirects section, references to authoring guidelines, and polite collaborative language. Key features: - Emoji headings (✏️ 📁 🔗 ✅ 🔄 📊 🚀 📝 💬) matching Auth0 style - Redirects section with guidance and JSON example (critical given 4,201+ existing redirects) - Link to .claude/skills/writing-auth0-docs/SKILL.md authoring guidelines - References section for Jira tickets and product specs - Polite, collaborative tone throughout instructions - Mintlify-specific validation commands (mint dev, mint broken-links, mint a11y) - No feature flag references (not applicable to public docs repo) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .github/pull_request_template.md | 88 ++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 000000000..9b932618e --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,88 @@ +## ✏️ Changes + +Please describe what this PR changes and why. If this touches multiple documentation sites (`main/` and `auth4genai/`), please call that out. + +## 📁 Documentation scope + +**Site(s) affected:** +- [ ] `main/` - Auth0 main documentation +- [ ] `auth4genai/` - Auth0 for AI Agents documentation +- [ ] `ui/` - Shared component library +- [ ] Infrastructure/tooling + +**Type of change:** +- [ ] New documentation +- [ ] Update to existing documentation +- [ ] Navigation/information architecture change +- [ ] Code examples or snippets +- [ ] UI component or Mintlify configuration +- [ ] Linting/tooling/workflows + +## 🔗 References + +Link to Jira issues, product specs, or related discussions: + +https://auth0team.atlassian.net/browse/ + +## 🎯 Testing + +**Local validation:** +- [ ] Ran `mint dev` in affected docs folder(s) +- [ ] Checked for broken links with `mint broken-links` (if applicable) +- [ ] Verified accessibility with `mint a11y` (if applicable) +- [ ] Built UI library with `npm run build` (if UI changes) + +**Style compliance:** +- [ ] Follows the Contribution Guidelines (TBD) +- [ ] Follows placeholder conventions (`YOUR_SOMETHING`, ``) +- [ ] Uses correct Auth0 terminology and sentence case for headings +- [ ] Code blocks include language and filename where appropriate +- [ ] All images wrapped in `` components + +## 🔄 Redirects + +**Please add redirects if:** +- [ ] Pages are being removed or URLs are changing +- [ ] Navigation structure changes affect existing URLs + +If redirects are needed, please add them to the `redirects` array in the appropriate `docs.json` file: +```json +{ + "source": "/docs/old-path", + "destination": "/docs/new-path" +} +``` + +## 📊 Impact + +**User-facing changes:** +Please describe any user-facing impact: +- Does this introduce new pages, remove pages, or change URLs? +- Does this document a new feature, Early Access capability, or breaking change? +- Are there plan restrictions (Enterprise/Professional) that need callouts? + +**Dependencies:** +Please note any dependencies or coordination needs: +- Are there related PRs or release timing considerations? +- Does this require coordination with Product, Legal, or Security teams? + +## 🚀 Deployment + +✅🚫 This can be deployed any time (Mintlify auto-deploys on merge to main) + + + +## 📝 Follow-up + +- [ ] No follow-up needed +- [ ] Follow-up issue/PR needed (describe below) + +## 💬 Additional context + +Please add any other context, screenshots, or preview links that would help reviewers. From 776e2ecf179819e7a41ab603fb755917660d2ba9 Mon Sep 17 00:00:00 2001 From: Bobby Tiernay Date: Tue, 18 Nov 2025 13:00:08 -0500 Subject: [PATCH 2/4] polish: public refinements --- .github/pull_request_template.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 9b932618e..059b29f13 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -20,9 +20,7 @@ Please describe what this PR changes and why. If this touches multiple documenta ## 🔗 References -Link to Jira issues, product specs, or related discussions: - -https://auth0team.atlassian.net/browse/ +Link to relevant GitHub issues, specifications, or related public discussions. ## 🎯 Testing @@ -34,10 +32,8 @@ https://auth0team.atlassian.net/browse/ **Style compliance:** - [ ] Follows the Contribution Guidelines (TBD) -- [ ] Follows placeholder conventions (`YOUR_SOMETHING`, ``) - [ ] Uses correct Auth0 terminology and sentence case for headings - [ ] Code blocks include language and filename where appropriate -- [ ] All images wrapped in `` components ## 🔄 Redirects From 422370cee74b459670b2103b39d9f8f7c9ff302d Mon Sep 17 00:00:00 2001 From: Bobby Tiernay Date: Tue, 18 Nov 2025 13:02:25 -0500 Subject: [PATCH 3/4] feat: add internationalization section to PR template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add i18n section to remind contributors to consider localized content updates when modifying main docs. Main docs support French Canadian (fr-ca/) and Japanese (ja-jp/) locales. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .github/pull_request_template.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 059b29f13..cb668d721 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -49,6 +49,15 @@ If redirects are needed, please add them to the `redirects` array in the appropr } ``` +## 🌍 Internationalization + +**Localized content (main docs only):** +- [ ] Not applicable - no English content changes +- [ ] Changes apply to English content only (localized versions will be updated separately) +- [ ] Changes include updates to localized versions (`fr-ca/`, `ja-jp/`) + +**Note:** Main docs support French Canadian (`main/docs/fr-ca/`) and Japanese (`main/docs/ja-jp/`). If you're updating existing pages, consider whether localized versions need corresponding updates. + ## 📊 Impact **User-facing changes:** From 4058b3b8a2c25d4ea551a44bf6ec8e5ce7cee5ac Mon Sep 17 00:00:00 2001 From: Bobby Tiernay Date: Sun, 23 Nov 2025 09:15:51 -0500 Subject: [PATCH 4/4] polish: improvements --- .github/pull_request_template.md | 167 ++++++++++++++++++++----------- 1 file changed, 111 insertions(+), 56 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index cb668d721..d63ed1ec6 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,93 +1,148 @@ +## 📝 Before you begin + +By opening this PR, you agree to the terms of the [Auth0 Code of Conduct](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md). For guidance on creating a high-quality PR, see the [Contributing Guidelines](CONTRIBUTING.md). + ## ✏️ Changes -Please describe what this PR changes and why. If this touches multiple documentation sites (`main/` and `auth4genai/`), please call that out. +Describe what this PR changes and why. Keep it brief. + +- What problem does it solve? +- Which docs or UI areas are affected? +- Does it span more than one docs site (`main/`, `auth4genai/`) or the shared UI library (`ui/`)? ## 📁 Documentation scope -**Site(s) affected:** -- [ ] `main/` - Auth0 main documentation -- [ ] `auth4genai/` - Auth0 for AI Agents documentation -- [ ] `ui/` - Shared component library -- [ ] Infrastructure/tooling +**Docs site(s) affected** + +- [ ] `main/` +- [ ] `auth4genai/` + +**Other areas** + +- [ ] Shared UI library (`ui/`) +- [ ] GitHub workflows (`.github/workflows/`) +- [ ] Tooling or scripts (`tools/`) + +**Type of change** -**Type of change:** -- [ ] New documentation -- [ ] Update to existing documentation -- [ ] Navigation/information architecture change +- [ ] New page or major section +- [ ] Update to existing content +- [ ] Navigation or structure change - [ ] Code examples or snippets - [ ] UI component or Mintlify configuration -- [ ] Linting/tooling/workflows +- [ ] GitHub workflows (`.github/workflows/`) +- [ ] Scripts or tooling (`tools/`) + +Add paths or permalinks if it helps reviewers. ## 🔗 References -Link to relevant GitHub issues, specifications, or related public discussions. +Link any related issues, design docs, or connected PRs. + +- Issue(s): # +- Related work: ## 🎯 Testing -**Local validation:** -- [ ] Ran `mint dev` in affected docs folder(s) -- [ ] Checked for broken links with `mint broken-links` (if applicable) -- [ ] Verified accessibility with `mint a11y` (if applicable) -- [ ] Built UI library with `npm run build` (if UI changes) +Mark what you validated and note anything skipped. +(Unit tests do not apply in this repo.) + +**Local validation** + +- [ ] Content-only change (no build or navigation impact) +- [ ] `mint dev` in affected folders +- [ ] `mint broken-links` (when applicable) +- [ ] `mint a11y` (when applicable) +- [ ] `npm run build` in `ui/` (for UI changes) + +**Style and structure** + +- [ ] Follows the Contributing Guidelines +- [ ] Uses correct Auth0 terminology +- [ ] Code blocks include language and filenames when needed -**Style compliance:** -- [ ] Follows the Contribution Guidelines (TBD) -- [ ] Uses correct Auth0 terminology and sentence case for headings -- [ ] Code blocks include language and filename where appropriate +**Repo checks** + +- [ ] All required GitHub checks are passing +- [ ] The correct base branch is used + +If something was not run or does not apply, note it here. ## 🔄 Redirects -**Please add redirects if:** -- [ ] Pages are being removed or URLs are changing -- [ ] Navigation structure changes affect existing URLs +Use this section only if URLs change. + +- [ ] Pages removed or permalinks changed +- [ ] Navigation changes that alter existing URLs + +If redirects are needed, update the relevant `docs.json` and list them here: -If redirects are needed, please add them to the `redirects` array in the appropriate `docs.json` file: ```json -{ - "source": "/docs/old-path", - "destination": "/docs/new-path" -} +[ + { + "source": "/docs/old-path", + "destination": "/docs/new-path" + } +] ``` -## 🌍 Internationalization +## 🌍 Internationalization (main docs only) + +* [ ] Not applicable - no English content changes in `main/` +* [ ] English only; localization handled separately +* [ ] Includes updates to localized content (for example, `main/docs/fr-ca/`, `main/docs/ja-jp/`) + +Add notes if something needs follow-up in localized folders. -**Localized content (main docs only):** -- [ ] Not applicable - no English content changes -- [ ] Changes apply to English content only (localized versions will be updated separately) -- [ ] Changes include updates to localized versions (`fr-ca/`, `ja-jp/`) +## 🧩 Impact and dependencies -**Note:** Main docs support French Canadian (`main/docs/fr-ca/`) and Japanese (`main/docs/ja-jp/`). If you're updating existing pages, consider whether localized versions need corresponding updates. +**User-facing impact** -## 📊 Impact +Summarize what readers will notice: -**User-facing changes:** -Please describe any user-facing impact: -- Does this introduce new pages, remove pages, or change URLs? -- Does this document a new feature, Early Access capability, or breaking change? -- Are there plan restrictions (Enterprise/Professional) that need callouts? +* New or removed pages +* URL changes +* New feature, Early Access feature, or breaking change +* Plan restrictions that need callouts -**Dependencies:** -Please note any dependencies or coordination needs: -- Are there related PRs or release timing considerations? -- Does this require coordination with Product, Legal, or Security teams? +**Dependencies** + +List anything this PR depends on or influences: + +* Product release timing +* Related PRs or repos +* Follow-up docs needed after merge ## 🚀 Deployment -✅🚫 This can be deployed any time (Mintlify auto-deploys on merge to main) +* [ ] Safe to deploy on merge +* [ ] Do not merge until a condition is met + +If blocked, state the condition: - +* Dependent PRs: +* Date or window: +* Other requirement: ## 📝 Follow-up -- [ ] No follow-up needed -- [ ] Follow-up issue/PR needed (describe below) +* [ ] No follow-up needed +* [ ] Follow-up work required + +Add links or describe next steps if needed. ## 💬 Additional context -Please add any other context, screenshots, or preview links that would help reviewers. +Optional. Add anything reviewers should know: + +* Specific pages in the Mintlify preview you want checked +* Screenshots or diagrams (with alt text) +* Notes for specific reviewers + +> [!TIP] +> Useful references: +> +> * [Contributing Guidelines](CONTRIBUTING.md) +> * Mintlify documentation: [https://www.mintlify.com/docs](https://www.mintlify.com/docs) +> * [main README](main/README.md) +> * [auth4genai README](auth4genai/README.md)