Set up GitHub repo documentation and governance #53
Conversation
Comprehensive documentation and governance improvements to enhance discoverability, standardization, and consumer adoption across the LightSpeed organization. ## Changes ### Added - **docs/ mini-READMEs** - Created README files for all docs subdirectories (bugherd, frontmatter, git-workflow, label-automation, ls-projects, wp-guides, wordpress, assets) with purpose, inputs/outputs, and examples - **docs/labels.md** - Comprehensive label semantics guide with usage examples, automation workflows, and best practices for all label families - **Label sync workflow** - New .github/workflows/label-sync.yml for automated label synchronization from canonical source, orphan detection, and reporting - **Consumer guide in README** - Added extensive "Reusing Workflows and Syncing Labels" section with practical examples for adopting LightSpeed standards - **Exception process in GOVERNANCE.md** - Documented how repositories can override defaults, exception requirements, and quarterly review process - **Release cadence in GOVERNANCE.md** - Defined fortnightly/quarterly release schedule, maintenance windows, and rollback procedures - **Security SLA in SECURITY.md** - Added comprehensive SLA table with response times, severity definitions, and vulnerability disclosure policy ### Changed - **PR template** - Added Risk Assessment and How to Test sections with detailed prompts for risk level, impact analysis, mitigation steps, and testing instructions - **CODEOWNERS** - Expanded with granular ownership assignments for critical paths (workflows, labels, automation, documentation, scripts, tests, schemas) - **README** - Enhanced with 10-section consumer guide including workflow reuse, label sync, branch naming, setup scripts, validation, and monitoring ### Improved - **Documentation discoverability** - Each docs subfolder now has descriptive README with clear purpose, usage examples, and cross-references - **Community health** - Enhanced SECURITY.md with detailed reporting process, SLA commitments, and security best practices - **Governance transparency** - Added exception process, release cadence, and rollback procedures for predictable org-wide updates ## Impact - Reduces onboarding friction for new repositories adopting LightSpeed standards - Improves label consistency through automated sync and orphan detection - Enhances security response with clear SLA commitments and escalation paths - Provides clear governance for exceptions and release management - Increases documentation discoverability with structured mini-READMEs ## Testing - All YAML files validated for syntax - Documentation cross-references verified - Label sync workflow tested in dry-run mode - Git operations verified on feature branch Addresses GitHub docs discoverability and community health checklist items.
|
Warning Rate limit exceeded@ashleyshaw has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 0 minutes and 41 seconds before requesting another review. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📒 Files selected for processing (2)
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. Note
|
| Cohort / File(s) | Summary |
|---|---|
PR and Workflow Templates .github/pull_request_template.md, .github/workflows/label-sync.yml |
Enhanced PR template with Risk Assessment and How to Test sections; new Label Sync workflow for organization-wide label management with canonical source synchronization, orphaned label detection, and GitHub issue creation. |
Repository Governance CODEOWNERS, GOVERNANCE.md |
Updated CODEOWNERS with global fallback and granular path-specific ownership across governance, workflows, docs, AI prompts, scripts, tests, and schemas; extended GOVERNANCE.md with Change Process, Exception Process, and Release Cadence sections. |
Repository Policies README.md, SECURITY.md |
Added Consumer Guide to README with label sync and workflow reuse instructions; replaced SECURITY.md contact block with comprehensive vulnerability reporting policy including SLA and severity definitions. |
Documentation: Asset & Frontmatter Guides docs/assets/README.md, docs/frontmatter/README.md, docs/bugherd/README.md |
New documentation files establishing asset management guidelines, YAML frontmatter schemas, and BugHerd integration guidance with standardized metadata and usage examples. |
Documentation: Workflow & Automation Guides docs/git-workflow/README.md, docs/label-automation/README.md, docs/labels.md |
New documentation files detailing Git workflow standards, label automation taxonomy, usage examples, best practices, and automation rule definitions. |
Documentation: Project & Development Guides docs/ls-projects/README.md, docs/wordpress/README.md, docs/wp-guides/README.md |
New documentation files for GitHub Projects templates, WordPress development structure, and development guides covering block themes, coding standards, and testing. |
Sequence Diagram(s)
sequenceDiagram
participant GH as GitHub
participant WF as Label Sync<br/>Workflow
participant API as GitHub API
participant Repo as Target<br/>Repository
rect rgb(220, 240, 255)
Note over WF: Initialization & Fetch
WF->>GH: Checkout repo
WF->>WF: Setup Node.js
WF->>WF: Install dependencies
end
rect rgb(240, 255, 240)
Note over WF: Fetch Canonical Labels
WF->>WF: Parse YAML (local or remote)
WF->>WF: Expose canonical labels as outputs
end
rect rgb(255, 250, 240)
Note over WF: Synchronization
API->>Repo: Fetch current repository labels
WF->>WF: Compare: canonical vs. current
alt Labels need creation
WF->>API: Create new labels
end
alt Labels need update
WF->>API: Update label color/description
end
alt Orphaned labels detected
WF->>WF: Flag for issue creation
end
end
rect rgb(255, 240, 245)
Note over WF: Orphaned Labels Handling
alt Not dry-run mode
WF->>API: Find or create issue
WF->>API: Update issue with orphaned summary
end
end
rect rgb(240, 245, 255)
Note over WF: Completion
WF->>GH: Write summary to Step Summary
WF->>WF: Report: added, updated, orphaned counts
end
Estimated code review effort
🎯 3 (Moderate) | ⏱️ ~25 minutes
- Label Sync workflow (
label-sync.yml): Complex conditional logic with GitHub API interactions, error handling, issue creation, and YAML parsing requires careful verification of control flow and edge cases. - Governance and CODEOWNERS updates: Requires understanding of intended ownership scope and authorization patterns; relatively straightforward declarations but impacts review processes.
- Documentation proliferation: Multiple new documentation files follow consistent structural patterns (frontmatter + sections), reducing per-file review complexity; ensure consistency across all new docs and verify links/references.
Possibly related PRs
- [PR] Repository hygiene, documentation, and config alignment for WordPress projects #4: Modifies overlapping GitHub configuration, label automation, and repository documentation files; foundational governance work.
- Update default PR Templates #8: Directly modifies
.github/pull_request_template.mdin parallel; coordinate PR template restructuring and checklist additions.
Suggested labels
documentation, lang:md, status:needs-review
Pre-merge checks and finishing touches
✅ Passed checks (3 passed)
| Check name | Status | Explanation |
|---|---|---|
| Title check | ✅ Passed | The title 'Set up GitHub repo documentation and governance' directly reflects the main changes: comprehensive documentation enhancements and governance improvements to the repository. |
| Description check | ✅ Passed | The PR description includes all key sections from the template (Linked issues, Changelog with Added/Changed/Fixed/Removed, and Checklist), though some sections are incomplete or use placeholder format. |
| Docstring Coverage | ✅ Passed | No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. |
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
Comment @coderabbitai help to get the list of available commands and usage tips.
There was a problem hiding this comment.
Pull Request Overview
This PR implements comprehensive documentation and governance improvements to the LightSpeed .github repository, focusing on discoverability, standardization, and consumer adoption. The changes establish a well-structured documentation system with mini-READMEs for all docs subdirectories, comprehensive label semantics guidance, automated label synchronization, detailed consumer adoption guides, and enhanced governance procedures.
Key Changes
- Created structured README files for 8 docs subdirectories (wp-guides, wordpress, ls-projects, label-automation, git-workflow, frontmatter, bugherd, assets) with clear purpose, inputs/outputs, and examples
- Added comprehensive labels guide (docs/labels.md) with 470 lines of label semantics, usage examples, and automation workflows
- Implemented automated label sync workflow with orphan detection and reporting
- Enhanced README with 10-section consumer guide for workflow reuse, label sync, and LightSpeed standards adoption
- Expanded GOVERNANCE.md with exception process, release cadence, and rollback procedures
- Enhanced SECURITY.md with detailed SLA table, severity definitions, and vulnerability disclosure policy
- Updated CODEOWNERS with granular ownership assignments for critical paths
Reviewed Changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/wp-guides/README.md | WordPress development guides README with checklists and quick references |
| docs/wordpress/README.md | Comprehensive WordPress documentation index covering block themes, Gutenberg, coding standards, and testing |
| docs/ls-projects/README.md | GitHub Projects templates and automation documentation for client delivery and product development workflows |
| docs/labels.md | Extensive label taxonomy guide with 9 label families, usage examples, automation workflows, and best practices |
| docs/label-automation/README.md | Label automation strategy documentation with workflow examples and project synchronization |
| docs/git-workflow/README.md | Git workflow and branching strategy documentation with agile integration |
| docs/frontmatter/README.md | YAML frontmatter schemas and guidelines for documentation standardization |
| docs/bugherd/README.md | BugHerd integration and tagging workflow documentation |
| docs/assets/README.md | Documentation assets organization and usage guidelines |
| SECURITY.md | Enhanced security policy with SLA commitments, severity definitions, and disclosure procedures |
| README.md | Added comprehensive 300+ line consumer guide for adopting LightSpeed standards |
| GOVERNANCE.md | Added exception process, release cadence, and rollback procedures |
| CODEOWNERS | Expanded with granular ownership for workflows, labels, automation, documentation, scripts, tests, and schemas |
| .github/workflows/label-sync.yml | New automated label synchronization workflow with orphan detection and reporting |
Comments suppressed due to low confidence (1)
SECURITY.md:1
- British spelling in line 29 'unsanitised' should match the American spelling used elsewhere in security documentation.
# Security Policy
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ```markdown | ||
| Subject: [SECURITY] XSS Vulnerability in Search Form | ||
|
|
||
| Description: Cross-site scripting (XSS) vulnerability in search form due to unsanitised user input. |
There was a problem hiding this comment.
British spelling 'unsanitised' should be 'unsanitized' for consistency with WordPress coding standards which use American English.
| Description: Cross-site scripting (XSS) vulnerability in search form due to unsanitised user input. | |
| Description: Cross-site scripting (XSS) vulnerability in search form due to unsanitized user input. |
| uses: lightspeedwp/.github/.github/workflows/label-sync.yml@develop | ||
| with: | ||
| labels_source_repo: 'lightspeedwp/.github' | ||
| labels_source_path: '.github/automation/labels.yml' |
There was a problem hiding this comment.
The consumer guide example sets dry_run: false but doesn't explain the implications. Add a comment noting that setting this to true first is recommended for testing before applying changes.
| labels_source_path: '.github/automation/labels.yml' | |
| labels_source_path: '.github/automation/labels.yml' | |
| # It is recommended to set dry_run: true first to test the workflow before making changes. | |
| # Setting dry_run: false will apply label changes to your repository. |
| ## Project Types | ||
| | Type | Use Case | Cadence | Automation | |
There was a problem hiding this comment.
The YAML code fence contains plain text comments rather than valid YAML. This should either use a different fence type (like text or markdown) or be reformatted as actual YAML with proper structure.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 22
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (5)
.github/pull_request_template.md (1)
1-6: PR template frontmatter missing asset metadata fields.Per coding guidelines (
.github/**/*.md), asset markdown files should include explicitdescription,domain,stability, andtagsfields. The current frontmatter usesaboutbut lacks the required asset taxonomy fields. Additionally, the template lacks afile_typediscriminator (required for non-instruction.github/markdown files).Apply this diff to enhance the frontmatter:
--- name: "Pull Request" about: "General changes, refactors, and maintenance" +description: "Template for general PRs, refactors, and maintenance with risk assessment and testing sections" +file_type: "pull-request-template" +domain: "generic" +stability: "stable" +tags: ["pr-template", "risk-assessment", "testing", "contribution"] title: "PR: {short summary}" labels: ["status:needs-review"] ---SECURITY.md (1)
1-3: Add YAML frontmatter to SECURITY.md.Per coding guidelines, all Markdown files must include frontmatter with
version,last_updated,owners,file_type,category, anddescription. SECURITY.md is currently missing this header.Apply this diff to add frontmatter:
+--- +title: 'Security Policy' +description: 'Vulnerability reporting procedures, SLA commitments, and security best practices for LightSpeed' +version: 'v1.0.0' +last_updated: '2025-11-12' +owners: ['LightSpeed Team', '@ashleyshaw'] +file_type: 'policy' +category: 'governance' +tags: ['security', 'vulnerability', 'disclosure', 'policy'] +--- + # Security PolicyREADME.md (2)
1-19: Add missing standard frontmatter fields and fix version format.Per coding guidelines, all Markdown files require:
file_type,category, andownersfields. The custom fields (ai_references,related_docs) should be preserved. Additionally,versionshould follow semantic versioning (e.g.,v2.0.0not2.0).Apply this diff to enhance the frontmatter:
--- title: "LightSpeed Community Health & Automation Repository" description: "Central hub for LightSpeed organization's community health files, automation standards, label management, governance documentation, and org-wide resources for GitHub usage and contribution." -version: "2.0" +version: "v2.0.0" last_updated: "2025-10-24" +file_type: "hub" +category: "documentation" +owners: ["LightSpeed Team"] maintainer: "LightSpeed Team" tags: ["community-health", "automation", "governance", "labels", "workflows", "ai", "copilot"] ai_references: - ".github/custom-instructions.md" - ".github/agents/agent.md" - ".github/prompts/prompts.md" - ".github/chatmodes/chatmodes.md" - "AGENTS.md" related_docs: - "DOCS.md" - "CONTRIBUTING.md" - "GOVERNANCE.md" - "AUTOMATION_GOVERNANCE.md" ---
827-831: Add a proper fun footer markdown.The footer should be actual markdown content at the end of the file, not a commented-out template. Per coding guidelines, all README files must end with exactly one fun footer.
Apply this diff to replace the commented footer with actual markdown:
**🏠 This repository is managed by the LightSpeed team. All organizational automation, policy, and documentation updates are maintained here.** **📧 Questions?** [Open an issue](https://github.com/lightspeedwp/.github/issues/new) or [start a discussion](https://github.com/lightspeedwp/.github/discussions/new) -<!-- RANDOM FOOTER: 🚀 Built by LightSpeedWP with ☕, 🚀, and open-source spirit! --> +--- + +🚀 **Built by LightSpeedWP with ☕, code, and open-source spirit!** Made with ❤️ for the community.GOVERNANCE.md (1)
1-4: Add required YAML frontmatter.Per the coding guidelines, every Markdown file must start with YAML frontmatter containing: version, last_updated, owners, file_type, category, and description.
Apply this diff to add the required frontmatter:
+--- +version: 'v1.0.0' +last_updated: '2025-11-12' +owners: ['@ashleyshaw', '@krugazul'] +file_type: 'governance' +category: 'community' +description: 'Governance structure, decision-making processes, and community health policies for the LightSpeed organization' +--- + # LightSpeed Community Health Repo Governance Defines maintainer/contributor roles and decision making. See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).As per coding guidelines.
🧹 Nitpick comments (7)
docs/label-automation/README.md (1)
110-112: Replace with an approved fun footer variant.The coding guidelines state: "All README and documentation files must end with exactly one fun footer. Footer text must be chosen from the approved variants list."
The current footer is informational but not "fun" as required by the guidelines.
Consider replacing with a more engaging footer variant. Would you like me to suggest approved fun footer options for this documentation?
docs/wordpress/README.md (1)
112-114: Replace with an approved fun footer variant.The coding guidelines state: "All README and documentation files must end with exactly one fun footer. Footer text must be chosen from the approved variants list."
Consider replacing with a more engaging footer variant. Would you like me to suggest approved fun footer options?
docs/ls-projects/README.md (1)
137-139: Replace with an approved fun footer variant.The coding guidelines state: "All README and documentation files must end with exactly one fun footer. Footer text must be chosen from the approved variants list."
Consider replacing with a more engaging footer variant. Would you like me to suggest approved fun footer options?
.github/workflows/label-sync.yml (4)
55-58: Permissions are too broad for the workflow's needs.The workflow grants
pull-requests: writebut doesn't appear to modify PRs. Consider restricting to the minimum required permissions.Apply this diff to use minimal permissions:
permissions: contents: read issues: write - pull-requests: writeAs per coding guidelines: "Declare explicit permissions in each workflow using the permissions key; default to contents: read and only elevate when necessary."
80-80: Consider removing npm cache if not beneficial.The workflow installs a one-off set of dependencies with
--no-save, so caching npm packages may not provide benefits and could add unnecessary complexity.Consider removing the
cache: 'npm'line if there's no package-lock.json or if the dependencies are too small to benefit from caching:- name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '20' - cache: 'npm'
224-224: Usage count TODO should be addressed or removed.Line 224 contains a TODO comment for fetching usage count of orphaned labels. This would provide valuable context for determining whether labels are safe to remove.
Would you like me to generate a script to fetch label usage counts via the GitHub API? This would enhance the orphaned label detection by showing which labels are actively used.
301-330: Consider UK English spelling in user-facing content.The coding guidelines specify "Use UK English in documentation." The issue body contains American spellings like "organization" and "Organizational."
Consider updating to UK English spellings:
- "organization" → "organisation"
- "organization-wide" → "organisation-wide"
As per coding guidelines.
📜 Review details
Configuration used: Path: .coderabbit.yml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (15)
.github/pull_request_template.md(2 hunks).github/workflows/label-sync.yml(1 hunks)CODEOWNERS(1 hunks)GOVERNANCE.md(1 hunks)README.md(1 hunks)SECURITY.md(1 hunks)docs/assets/README.md(1 hunks)docs/bugherd/README.md(1 hunks)docs/frontmatter/README.md(1 hunks)docs/git-workflow/README.md(1 hunks)docs/label-automation/README.md(1 hunks)docs/labels.md(1 hunks)docs/ls-projects/README.md(1 hunks)docs/wordpress/README.md(1 hunks)docs/wp-guides/README.md(1 hunks)
🧰 Additional context used
📓 Path-based instructions (18)
**/*.{md,mdx,markdown}
📄 CodeRabbit inference engine (.github/instructions/copilot-frontmatter.instructions.md)
**/*.{md,mdx,markdown}: Every Markdown (and template) file must start with YAML frontmatter containing: version (semantic, starting at "v0.1.0"), last_updated (UTC ISO date "YYYY-MM-DD"), owners (array of strings), file_type (string), category (string), and description (one-sentence string).
Frontmatter must be located at the very top of the file, delimited by '---' markers.
Inspect the YAML frontmatter at the top of the file before making changes.
Add or normalize the required frontmatter fields, setting sensible defaults where appropriate.
Preserve any existing frontmatter fields and their values.
Do not alter the body/content of the file when updating frontmatter.
If a field exists, do not overwrite its value unless it is outdated or incorrect.
Files:
docs/ls-projects/README.mddocs/label-automation/README.mddocs/frontmatter/README.mddocs/assets/README.mddocs/bugherd/README.mdSECURITY.mddocs/labels.mddocs/git-workflow/README.mdREADME.mddocs/wp-guides/README.mdGOVERNANCE.mddocs/wordpress/README.md
{**/README*.md,docs/**/*.md}
📄 CodeRabbit inference engine (.github/instructions/footer-header-style.instructions.md)
{**/README*.md,docs/**/*.md}: All README and documentation files must end with exactly one fun footer
Footer text must be chosen from the approved variants list (or a repo-configured override)
Insert a badges block immediately below the main# Header, wrapped between<!-- BADGES-START -->and<!-- BADGES-END -->
Recommended badges to include: License, Build Status, Coverage, Contributors, Workflows
Badges may be single-line or stacked; both layouts are acceptable within the badge block
Ensure one and only one footer exists at the end of each documentation file
Files:
docs/ls-projects/README.mddocs/label-automation/README.mddocs/frontmatter/README.mddocs/assets/README.mddocs/bugherd/README.mddocs/labels.mddocs/git-workflow/README.mdREADME.mddocs/wp-guides/README.mddocs/wordpress/README.md
**/*.{js,ts,php,css,scss,sass,html,json,md,yml,yaml,py,sh}
📄 CodeRabbit inference engine (.github/instructions/linting.instructions.md)
Apply linting checks to all supported source and config files (JavaScript, TypeScript, PHP, CSS/SCSS/Sass, HTML, JSON, Markdown, YAML, Python, Shell).
Files:
docs/ls-projects/README.mddocs/label-automation/README.mddocs/frontmatter/README.mddocs/assets/README.mddocs/bugherd/README.mdSECURITY.mddocs/labels.mddocs/git-workflow/README.mdREADME.mddocs/wp-guides/README.mdGOVERNANCE.mddocs/wordpress/README.md
**/*.{md,yml,yaml,json,toml}
📄 CodeRabbit inference engine (.github/instructions/naming-conventions.instructions.md)
Documentation and configuration filenames must use lowercase with hyphens (-) for spaces, except designated top-level summary/reference files
Files:
docs/ls-projects/README.mddocs/label-automation/README.mddocs/frontmatter/README.mddocs/assets/README.mddocs/bugherd/README.mdSECURITY.mddocs/labels.mddocs/git-workflow/README.mdREADME.mddocs/wp-guides/README.mdGOVERNANCE.mddocs/wordpress/README.md
**/*.md
📄 CodeRabbit inference engine (.github/instructions/naming-conventions.instructions.md)
Always include a canonical file_type field in YAML frontmatter of Markdown files
**/*.md: Include YAML frontmatter in all documentation Markdown files
Use UK English in documentation
Files:
docs/ls-projects/README.mddocs/label-automation/README.mddocs/frontmatter/README.mddocs/assets/README.mddocs/bugherd/README.mdSECURITY.mddocs/labels.mddocs/git-workflow/README.mdREADME.mddocs/wp-guides/README.mdGOVERNANCE.mddocs/wordpress/README.md
docs/**/*.{md,mdx}
📄 CodeRabbit inference engine (.github/instructions/patterns.instructions.md)
docs/**/*.{md,mdx}: Add pattern previews in documentation
Include teardown instructions explaining how to remove or replace the pattern safely
Files:
docs/ls-projects/README.mddocs/label-automation/README.mddocs/frontmatter/README.mddocs/assets/README.mddocs/bugherd/README.mddocs/labels.mddocs/git-workflow/README.mddocs/wp-guides/README.mddocs/wordpress/README.md
docs/**
📄 CodeRabbit inference engine (.github/instructions/reviews.instructions.md)
Update pattern or feature documentation when behavior or APIs change
Files:
docs/ls-projects/README.mddocs/label-automation/README.mddocs/frontmatter/README.mddocs/assets/README.mddocs/bugherd/README.mddocs/labels.mddocs/git-workflow/README.mddocs/wp-guides/README.mddocs/wordpress/README.md
**/*.{html,php,md}
📄 CodeRabbit inference engine (GEMINI.md)
Use semantic, accessible markup in user-facing content
Files:
docs/ls-projects/README.mddocs/label-automation/README.mddocs/frontmatter/README.mddocs/assets/README.mddocs/bugherd/README.mdSECURITY.mddocs/labels.mddocs/git-workflow/README.mdREADME.mddocs/wp-guides/README.mdGOVERNANCE.mddocs/wordpress/README.md
.github/workflows/**/*.yml
📄 CodeRabbit inference engine (.github/instructions/design-agents.instructions.md)
Integrate agents into GitHub Actions by triggering them in appropriate jobs (e.g., code review agents on pull requests)
CI must run lint, unit, and E2E tests on pull requests
Automate linting, accessibility checks, and test coverage before merge
Files:
.github/workflows/label-sync.yml
.github/workflows/**/*.{yml,yaml}
📄 CodeRabbit inference engine (.github/instructions/playwright-tests.instructions.md)
.github/workflows/**/*.{yml,yaml}: Ensure CI workflow installs dependencies and runs Playwright tests on pull requests and merges
Integrate Playwright into the CI/CD pipeline (e.g., GitHub Actions)
Files:
.github/workflows/label-sync.yml
{.github/workflows/**/*.yml,**/playwright.config.@(js|ts)}
📄 CodeRabbit inference engine (.github/instructions/testing.instructions.md)
CI should upload artifacts (videos, traces) for failing E2E runs
Files:
.github/workflows/label-sync.yml
.github/workflows/**/*.@(yml|yaml)
📄 CodeRabbit inference engine (.github/instructions/workflows.instructions.md)
.github/workflows/**/*.@(yml|yaml): Declare explicit permissions in each workflow using the permissions key; default to contents: read and only elevate when necessary
Use the concurrency key to prevent overlapping runs (e.g., concurrency: { group: '', cancel-in-progress: true })
Provide a manual trigger via workflow_dispatch and use clear, descriptive names for jobs and steps
Validate workflow syntax with actionlint locally or in CI
Include a smoke-test job that performs a minimal build or test to verify end-to-end workflow functionality
Files:
.github/workflows/label-sync.yml
{.github/workflows/**/*.@(yml|yaml),.github/actions/**/action.@(yml|yaml)}
📄 CodeRabbit inference engine (.github/instructions/workflows.instructions.md)
{.github/workflows/**/*.@(yml|yaml),.github/actions/**/action.@(yml|yaml)}: Do not pass secrets to third-party actions; use GitHub encrypted secrets and limit their scope
Cache dependencies deterministically with actions/cache using a key derived from lockfiles (e.g., package-lock.json, composer.lock)
Pin all actions to a full-length commit SHA instead of a mutable tag
Files:
.github/workflows/label-sync.yml
.github/workflows/*.{yml,yaml}
📄 CodeRabbit inference engine (GEMINI.md)
Automate linting, accessibility checks, and tests in CI before merge
Files:
.github/workflows/label-sync.yml
**/.github/workflows/*.yml
⚙️ CodeRabbit configuration file
**/.github/workflows/*.yml: Review .github workflows for CI/CD:
- Check for use of reusable workflow templates and matrix strategies.
- Validate secrets and environment variables are handled securely.
- Ensure jobs have clear names and steps are well-commented.
- Ensure workflows enforce linting, testing, and release policies.
- Validate required status checks for merges.
- Check for proper branch and path filters.
- Confirm workflows are documented, maintainable, and DRY.
- Check for agent capabilities, tool integration, and test coverage.
- Ensure agent files reference org-wide standards and indexes.
- Ensure workflows run markdownlint, test jobs, and security checks as required.
Files:
.github/workflows/label-sync.yml
README.md
📄 CodeRabbit inference engine (.github/instructions/reviews.instructions.md)
Update the README to reflect user-facing changes or setup changes
Files:
README.md
.github/**/*.md
📄 CodeRabbit inference engine (.github/instructions/tagging-and-frontmatter-conventions.instructions.md)
.github/**/*.md: Every asset markdown must include a description field (single-sentence preferred)
If deprecated is true, replacement must be provided and point to the successor file
Choose exactly one domain from the approved taxonomy (wp-core, block-theme, plugin-hardening, perf, a11y, i18n, security, headless, generic)
Use stability with value in {stable, experimental, incubating}
tags must have at most 8 items, use lowercase kebab-case, not repeat the chosen domain, and prefer existing tags
Descriptions should be concise (<= 120 characters)
Files:
.github/pull_request_template.md
.github/**/!(*.instructions).md
📄 CodeRabbit inference engine (.github/instructions/tagging-and-frontmatter-conventions.instructions.md)
All non-instruction markdown assets must include a file_type discriminator
Files:
.github/pull_request_template.md
🪛 LanguageTool
docs/ls-projects/README.md
[uncategorized] ~132-~132: The official name of this software platform is spelled with a capital “H”.
Context: ... Documentation - Automation Governance – ...
(GITHUB)
[uncategorized] ~133-~133: The official name of this software platform is spelled with a capital “H”.
Context: ...utomation strategy - Branching Strategy – Bra...
(GITHUB)
docs/label-automation/README.md
[uncategorized] ~104-~104: The official name of this software platform is spelled with a capital “H”.
Context: ...## Related Documentation - Labels YAML – Canonical labe...
(GITHUB)
[uncategorized] ~105-~105: The official name of this software platform is spelled with a capital “H”.
Context: ...ical label definitions - Labeler Config – Automated fil...
(GITHUB)
[uncategorized] ~106-~106: The official name of this software platform is spelled with a capital “H”.
Context: ...path-based labeling rules - Issue Types – Issue type...
(GITHUB)
[uncategorized] ~107-~107: The official name of this software platform is spelled with a capital “H”.
Context: ...Issue type to label mapping - PR Labels – PR label doc...
(GITHUB)
[uncategorized] ~108-~108: The official name of this software platform is spelled with a capital “H”.
Context: ...l documentation - Automation Governance – ...
(GITHUB)
docs/assets/README.md
[uncategorized] ~80-~80: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ... Always provide descriptive alt text in markdown 5. Attribution – Document image sou...
(MARKDOWN_NNP)
docs/bugherd/README.md
[uncategorized] ~60-~60: The official name of this software platform is spelled with a capital “H”.
Context: ...elated Documentation - Issue Templates – For converting BugHe...
(GITHUB)
[uncategorized] ~62-~62: The official name of this software platform is spelled with a capital “H”.
Context: ... label taxonomy - Automation Governance – ...
(GITHUB)
docs/labels.md
[uncategorized] ~17-~17: The official name of this software platform is spelled with a capital “H”.
Context: ...eed GitHub labels defined in labels.yml. ## Table of Co...
(GITHUB)
[uncategorized] ~453-~453: The official name of this software platform is spelled with a capital “H”.
Context: ...nc labels from the canonical labels.yml using the automa...
(GITHUB)
[uncategorized] ~461-~461: The official name of this software platform is spelled with a capital “H”.
Context: ... Documentation - Canonical Labels YAML – Single source ...
(GITHUB)
[uncategorized] ~462-~462: The official name of this software platform is spelled with a capital “H”.
Context: ...uth for all labels - Issue Labels Guide – Issue-spe...
(GITHUB)
[uncategorized] ~463-~463: The official name of this software platform is spelled with a capital “H”.
Context: ...c label documentation - PR Labels Guide – PR-specific ...
(GITHUB)
[uncategorized] ~465-~465: The official name of this software platform is spelled with a capital “H”.
Context: ...n documentation - Automation Governance – ...
(GITHUB)
docs/git-workflow/README.md
[uncategorized] ~103-~103: The official name of this software platform is spelled with a capital “H”.
Context: ...ted Documentation - Branching Strategy – Org...
(GITHUB)
[uncategorized] ~104-~104: The official name of this software platform is spelled with a capital “H”.
Context: ...branching rules - Automation Governance – ...
(GITHUB)
README.md
[uncategorized] ~442-~442: The official name of this software platform is spelled with a capital “H”.
Context: ...nc labels from the canonical labels.yml to ensure consis...
(GITHUB)
[uncategorized] ~446-~446: The official name of this software platform is spelled with a capital “H”.
Context: ...ll Reusable Label Sync Workflow Create .github/workflows/label-sync.yml in your repos...
(GITHUB)
[uncategorized] ~487-~487: The official name of this software platform is spelled with a capital “H”.
Context: ...nch names, and issue templates. Create .github/workflows/labeling.yml: ```yaml name:...
(GITHUB)
[uncategorized] ~574-~574: The official name of this software platform is spelled with a capital “H”.
Context: ...ority:critical` See Branching Strategy for c...
(GITHUB)
[uncategorized] ~578-~578: The official name of this software platform is spelled with a capital “H”.
Context: ...## 6. Configuring Labeler Rules Create .github/labeler.yml to auto-apply labels based...
(GITHUB)
docs/wp-guides/README.md
[uncategorized] ~85-~85: The official name of this content management system is spelled with a capital “P”.
Context: ... Documentation - WordPress Development – Comprehensive WordPress do...
(WORDPRESS)
[uncategorized] ~86-~86: The official name of this software platform is spelled with a capital “H”.
Context: ...dPress documentation - [Coding Standards](../../.github/instructions/coding-standards.instructi...
(GITHUB)
[uncategorized] ~88-~88: The official name of this software platform is spelled with a capital “H”.
Context: ...ractices - WordPress Block Instructions...
(GITHUB)
GOVERNANCE.md
[uncategorized] ~62-~62: The official name of this software platform is spelled with a capital “H”.
Context: ...ories Can Override Defaults While this .github repository provides organization-wide ...
(GITHUB)
[uncategorized] ~100-~100: The official name of this software platform is spelled with a capital “H”.
Context: ...Exceptions 1. Open a discussion in the .github repository explaining the need 2. Main...
(GITHUB)
[uncategorized] ~117-~117: The official name of this software platform is spelled with a capital “H”.
Context: ...anization-Wide Repository Updates This .github repository follows a regular release c...
(GITHUB)
docs/wordpress/README.md
[uncategorized] ~107-~107: The official name of this software platform is spelled with a capital “H”.
Context: ...reference checklists - [Coding Standards](../../.github/instructions/coding-standards.instructi...
(GITHUB)
[uncategorized] ~108-~108: The official name of this software platform is spelled with a capital “H”.
Context: ...ndards - Block Development Instructions...
(GITHUB)
[uncategorized] ~109-~109: The official name of this software platform is spelled with a capital “H”.
Context: ...lopment guide - [Theme JSON Instructions](../../.github/instructions/theme-json.instructions.md...
(GITHUB)
[uncategorized] ~110-~110: The official name of this software platform is spelled with a capital “H”.
Context: ...uide - [Pattern Development Instructions](../../.github/instructions/pattern-development.instru...
(GITHUB)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Agent
🔇 Additional comments (11)
.github/pull_request_template.md (1)
63-132: Risk Assessment and How to Test sections are well-structured.The new sections provide clear guidance for assessing change risk and testing procedures. The examples are practical and the checklist items at lines 143–144 integrate well with the global DoD.
SECURITY.md (1)
49-54: SLA table is well-structured and clear.The vulnerability response SLA with clear severity levels and timelines improves transparency and sets realistic expectations for reporters.
docs/git-workflow/README.md (1)
51-87: Excellent usage examples and branch naming conventions.The bash examples are practical and well-documented. The branch naming table with prefixes and examples provides clear guidance for contributors.
README.md (2)
23-28: Badges block is well-structured and comprehensive.The badges provide clear visual indicators of coverage, build status, documentation, AI integration, and automation status. Placement immediately below the main header is correct.
436-738: Consumer Guide section is comprehensive and actionable.The "Reusing Workflows and Syncing Labels" section provides 10 well-structured steps with practical examples, command-line snippets, and YAML configuration templates. The progression from label syncing through validation is logical and helpful for new consumers.
GOVERNANCE.md (2)
54-110: Exception Process section is well-structured.The new Exception Process section provides clear guidance on when and how repositories can deviate from organization-wide standards. The documentation requirements, example format, and quarterly review process are comprehensive and practical.
113-167: Release Cadence section provides valuable governance structure.The new Release Cadence section establishes clear expectations for organization-wide updates, including schedules, processes, maintenance windows, and rollback procedures. The concrete rollback commands are particularly helpful.
docs/labels.md (2)
49-267: Label documentation is comprehensive and well-structured.The label semantics section provides excellent detail with clear examples, workflows, and usage guidance. The categorization by family, the usage examples with concrete scenarios, and the distinction guidelines (e.g., when to use
status:needs-infovsstatus:blocked) are particularly valuable.
313-374: Automation workflows section provides clear guidance.The automation workflows section effectively documents the automatic label application rules, status transitions, and changelog enforcement. The YAML examples make the behavior easy to understand.
CODEOWNERS (2)
5-43: CODEOWNERS structure is comprehensive and well-organized.The granular ownership assignments provide clear accountability for critical paths including governance, workflows, automation, and documentation. The organization by category (Governance, Workflows, AI Instructions, etc.) makes the file easy to navigate.
30-30: Minor typo in GEMINI.md owner assignment.Line 30 has "@ashley Shaw" with a space in the username instead of "@ashleyshaw".
Apply this diff to fix the typo:
/CLAUDE.md @ashleyshaw -/GEMINI.md @ashley Shaw +/GEMINI.md @ashleyshaw /AGENTS.md @ashleyshawLikely an incorrect or invalid review comment.
| jobs: | ||
| sync-labels: | ||
| name: Sync Labels from Canonical Source | ||
| runs-on: ubuntu-latest |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add concurrency control to prevent overlapping runs.
Per the coding guidelines, workflows should use the concurrency key to prevent overlapping runs.
Apply this diff to add concurrency control:
env:
LABELS_SOURCE_REPO: ${{ inputs.labels_source_repo || 'lightspeedwp/.github' }}
LABELS_SOURCE_PATH: ${{ inputs.labels_source_path || '.github/automation/labels.yml' }}
DRY_RUN: ${{ inputs.dry_run || 'false' }}
+
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: trueAs per coding guidelines.
Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In .github/workflows/label-sync.yml around lines 65 to 68, the workflow lacks a
concurrency policy which can allow overlapping runs; add a top-level concurrency
key for the job (or workflow) with a stable group name (e.g., workflow name or
repo + job) and set cancel-in-progress: true to prevent concurrent executions
and cancel prior runs when a new one starts; place the concurrency block
immediately under the job (or at workflow root) to follow GitHub Actions syntax.
|
|
||
| steps: | ||
| - name: Checkout repository | ||
| uses: actions/checkout@v4 |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Pin actions to full-length commit SHA.
The coding guidelines require: "Pin all actions to a full-length commit SHA instead of a mutable tag."
Apply this diff to pin to SHA (example SHA - verify latest):
- - name: Checkout repository
- uses: actions/checkout@v4
+ - name: Checkout repository
+ uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1Repeat for all action uses in the workflow (lines 77, 88, 131, 148, 274).
As per coding guidelines.
Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
.github/workflows/label-sync.yml around line 72: the workflow uses
actions/checkout@v4 which is a mutable tag; replace the tag with the action's
full-length commit SHA to pin to an immutable ref (find the latest commit SHA
for actions/checkout v4 and update the uses line accordingly), and repeat this
replacement for every other action usage noted (lines 77, 88, 131, 148, 274) so
all uses are pinned to their respective full-length commit SHAs.
| --- | ||
| title: 'Documentation Assets' | ||
| description: 'Images, diagrams, and visual resources for LightSpeed documentation' | ||
| version: '1.0' | ||
| last_updated: '2025-11-12' | ||
| maintainer: 'LightSpeed Team' | ||
| tags: ['assets', 'images', 'diagrams', 'documentation'] | ||
| --- |
There was a problem hiding this comment.
Frontmatter missing required fields and version format incorrect.
Per coding guidelines, all Markdown documentation files require: owners (array), file_type, and category fields. Additionally, version should follow semantic versioning (e.g., v1.0.0 not 1.0).
Apply this diff to complete the frontmatter:
---
title: 'Documentation Assets'
description: 'Images, diagrams, and visual resources for LightSpeed documentation'
-version: '1.0'
+version: 'v1.0.0'
last_updated: '2025-11-12'
+owners: ['LightSpeed Team']
+file_type: 'guide'
+category: 'documentation'
maintainer: 'LightSpeed Team'
tags: ['assets', 'images', 'diagrams', 'documentation']
---📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| --- | |
| title: 'Documentation Assets' | |
| description: 'Images, diagrams, and visual resources for LightSpeed documentation' | |
| version: '1.0' | |
| last_updated: '2025-11-12' | |
| maintainer: 'LightSpeed Team' | |
| tags: ['assets', 'images', 'diagrams', 'documentation'] | |
| --- | |
| --- | |
| title: 'Documentation Assets' | |
| description: 'Images, diagrams, and visual resources for LightSpeed documentation' | |
| version: 'v1.0.0' | |
| last_updated: '2025-11-12' | |
| owners: ['LightSpeed Team'] | |
| file_type: 'guide' | |
| category: 'documentation' | |
| maintainer: 'LightSpeed Team' | |
| tags: ['assets', 'images', 'diagrams', 'documentation'] | |
| --- |
🤖 Prompt for AI Agents
In docs/assets/README.md around lines 1 to 8, the YAML frontmatter is missing
required fields and the version format is incorrect; add an owners field as an
array (e.g., ["team@example.com"] or ["LightSpeed Team"]), add file_type (e.g.,
"asset_manifest") and category (e.g., "assets" or "images"), and update version
to semantic format (e.g., "v1.0.0"); ensure the new fields are inserted into the
existing frontmatter block and preserve last_updated and other metadata.
| # Documentation Assets | ||
|
|
||
| This directory contains images, diagrams, and other visual resources used throughout LightSpeed documentation. |
There was a problem hiding this comment.
Add badges block and footer.
Documentation README files must include a badges block immediately below the main header and end with exactly one fun footer. See coding guidelines for {**/README*.md,docs/**/*.md}.
Apply this diff:
# Documentation Assets
+<!-- BADGES-START -->
+[](./README.md)
+[](#)
+<!-- BADGES-END -->
+
This directory contains images, diagrams, and other visual resources used throughout LightSpeed documentation.And at the end of the file:
**Maintained by LightSpeed Team** • For updates or questions, see [CONTRIBUTING.md](../../CONTRIBUTING.md)
+
+---
+
+📸 **A picture is worth a thousand words—keep those diagrams clear and docs visually engaging!** ✨📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Documentation Assets | |
| This directory contains images, diagrams, and other visual resources used throughout LightSpeed documentation. | |
| # Documentation Assets | |
| <!-- BADGES-START --> | |
| [](./README.md) | |
| [](#) | |
| <!-- BADGES-END --> | |
| This directory contains images, diagrams, and other visual resources used throughout LightSpeed documentation. |
🤖 Prompt for AI Agents
In docs/assets/README.md around lines 10 to 12, the file is missing the required
badges block immediately below the main header and the required single "fun
footer" at the end; insert a badges block directly after the top-level header
(add the standard project badges used by other README files) and append exactly
one fun footer line at the end of the file, ensuring formatting matches other
docs README files (badge block right under header, footer as the final line).
| 1. **File Naming** – Use descriptive, kebab-case names (e.g., `issue-template-bug-report.png`) | ||
| 2. **Image Formats** – Prefer SVG for diagrams, PNG for screenshots, WebP for photos | ||
| 3. **Image Optimization** – Compress images to reduce file size | ||
| 4. **Alt Text** – Always provide descriptive alt text in markdown |
There was a problem hiding this comment.
Capitalize "Markdown" per style conventions.
Per coding guidelines, "Markdown" (the formal name of the language) should be capitalized.
-4. **Alt Text** – Always provide descriptive alt text in markdown
+4. **Alt Text** – Always provide descriptive alt text in Markdown🧰 Tools
🪛 LanguageTool
[uncategorized] ~80-~80: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ... Always provide descriptive alt text in markdown 5. Attribution – Document image sou...
(MARKDOWN_NNP)
🤖 Prompt for AI Agents
In docs/assets/README.md around line 80, the word "markdown" should be
capitalized per style conventions; update the line to use "Markdown" instead of
"markdown" so the formal name is correctly capitalized.
| --- | ||
| title: 'WordPress Development Documentation' | ||
| description: 'Comprehensive WordPress development resources for block themes, Gutenberg, coding standards, and testing' | ||
| version: '1.0' | ||
| last_updated: '2025-11-12' | ||
| maintainer: 'LightSpeed Team' | ||
| tags: ['wordpress', 'block-themes', 'gutenberg', 'coding-standards', 'testing'] | ||
| --- |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Normalize YAML frontmatter to match coding guidelines.
The frontmatter is missing required fields per the coding guidelines:
owners(currently hasmaintainerinstead)file_typecategory
Additionally, the version field should use semantic versioning format starting with 'v' (e.g., v1.0.0 instead of 1.0).
Apply this diff to normalize the frontmatter:
---
title: 'WordPress Development Documentation'
description: 'Comprehensive WordPress development resources for block themes, Gutenberg, coding standards, and testing'
-version: '1.0'
+version: 'v1.0.0'
last_updated: '2025-11-12'
-maintainer: 'LightSpeed Team'
+owners: ['LightSpeed Team']
+file_type: 'documentation'
+category: 'wordpress'
tags: ['wordpress', 'block-themes', 'gutenberg', 'coding-standards', 'testing']
---As per coding guidelines.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| --- | |
| title: 'WordPress Development Documentation' | |
| description: 'Comprehensive WordPress development resources for block themes, Gutenberg, coding standards, and testing' | |
| version: '1.0' | |
| last_updated: '2025-11-12' | |
| maintainer: 'LightSpeed Team' | |
| tags: ['wordpress', 'block-themes', 'gutenberg', 'coding-standards', 'testing'] | |
| --- | |
| --- | |
| title: 'WordPress Development Documentation' | |
| description: 'Comprehensive WordPress development resources for block themes, Gutenberg, coding standards, and testing' | |
| version: 'v1.0.0' | |
| last_updated: '2025-11-12' | |
| owners: ['LightSpeed Team'] | |
| file_type: 'documentation' | |
| category: 'wordpress' | |
| tags: ['wordpress', 'block-themes', 'gutenberg', 'coding-standards', 'testing'] | |
| --- |
🤖 Prompt for AI Agents
In docs/wordpress/README.md around lines 1 to 8, the YAML frontmatter must be
normalized: replace the current maintainer field with an owners field
(preferably an array of owner identifiers/emails), add the required file_type
and category fields (e.g., file_type: "documentation", category: "wordpress"),
and change the version value to semantic format starting with 'v' (e.g.,
v1.0.0); preserve existing tags and other metadata, remove the deprecated
maintainer key, and ensure YAML syntax remains valid.
| # WordPress Development Documentation | ||
|
|
||
| This directory contains comprehensive WordPress development documentation for LightSpeed projects, including block themes, Gutenberg development, coding standards, and testing strategies. |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Add required badge block after the main header.
The coding guidelines require a badges block immediately below the main # Header, wrapped between <!-- BADGES-START --> and <!-- BADGES-END --> markers.
Apply this diff to add the badge block:
# WordPress Development Documentation
+
+<!-- BADGES-START -->
+[](../../README.md)
+[](../../CONTRIBUTING.md)
+<!-- BADGES-END -->
This directory contains comprehensive WordPress development documentation for LightSpeed projects, including block themes, Gutenberg development, coding standards, and testing strategies.As per coding guidelines.
🤖 Prompt for AI Agents
In docs/wordpress/README.md around lines 10 to 12, the file is missing the
required badges block directly below the main `#` header; insert a badges block
immediately after the header wrapped between the markers `<!-- BADGES-START -->`
and `<!-- BADGES-END -->` containing the project's required badge lines (e.g.,
status, CI, license badges) so the badges appear directly under the main header
per coding guidelines.
| --- | ||
| title: 'WordPress Development Guides' | ||
| description: 'Quick reference guides and checklists for WordPress development at LightSpeed' | ||
| version: '1.0' | ||
| last_updated: '2025-11-12' | ||
| maintainer: 'LightSpeed Team' | ||
| tags: ['wordpress', 'guides', 'checklists', 'coding-standards', 'security'] | ||
| --- |
There was a problem hiding this comment.
Frontmatter missing required fields and version format incorrect.
Per coding guidelines, all Markdown documentation files require: owners (array), file_type, and category fields. Additionally, version should follow semantic versioning (e.g., v1.0.0 not 1.0).
Apply this diff to complete the frontmatter:
---
title: 'WordPress Development Guides'
description: 'Quick reference guides and checklists for WordPress development at LightSpeed'
-version: '1.0'
+version: 'v1.0.0'
last_updated: '2025-11-12'
+owners: ['LightSpeed Team']
+file_type: 'guide'
+category: 'documentation'
maintainer: 'LightSpeed Team'
tags: ['wordpress', 'guides', 'checklists', 'coding-standards', 'security']
---📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| --- | |
| title: 'WordPress Development Guides' | |
| description: 'Quick reference guides and checklists for WordPress development at LightSpeed' | |
| version: '1.0' | |
| last_updated: '2025-11-12' | |
| maintainer: 'LightSpeed Team' | |
| tags: ['wordpress', 'guides', 'checklists', 'coding-standards', 'security'] | |
| --- | |
| --- | |
| title: 'WordPress Development Guides' | |
| description: 'Quick reference guides and checklists for WordPress development at LightSpeed' | |
| version: 'v1.0.0' | |
| last_updated: '2025-11-12' | |
| owners: ['LightSpeed Team'] | |
| file_type: 'guide' | |
| category: 'documentation' | |
| maintainer: 'LightSpeed Team' | |
| tags: ['wordpress', 'guides', 'checklists', 'coding-standards', 'security'] | |
| --- |
🤖 Prompt for AI Agents
In docs/wp-guides/README.md around lines 1 to 8, the YAML frontmatter is missing
required fields and the version format is invalid; add an owners field as an
array of strings (e.g., ["team@example.com"] or team aliases), add file_type
(e.g., "guide" or "checklist") and category (e.g., "wordpress"), and change
version to semantic format like "v1.0.0"; keep existing fields (title,
description, last_updated, maintainer, tags) intact and ensure the frontmatter
remains valid YAML with the new fields added.
| # WordPress Development Guides | ||
|
|
||
| This directory contains quick reference guides and checklists for WordPress development best practices at LightSpeed. |
There was a problem hiding this comment.
Add badges block and footer.
Documentation README files must include a badges block immediately below the main header and end with exactly one fun footer. See coding guidelines for {**/README*.md,docs/**/*.md}.
Apply this diff:
# WordPress Development Guides
+<!-- BADGES-START -->
+[](./README.md)
+[](#)
+<!-- BADGES-END -->
+
This directory contains quick reference guides and checklists for WordPress development best practices at LightSpeed.And at the end of the file:
**Maintained by LightSpeed Team** • For updates or questions, see [CONTRIBUTING.md](../../CONTRIBUTING.md)
+
+---
+
+🚀 **WordPress development done right—secure, accessible, and following best practices!** 💪Committable suggestion skipped: line range outside the PR's diff.
🤖 Prompt for AI Agents
In docs/wp-guides/README.md around lines 10 to 12, the README is missing the
required badges block directly beneath the main header and a single fun footer
at the end of the file; add a badges block immediately under the "# WordPress
Development Guides" header containing the standard project/repo badges used
across docs (e.g., build, license, docs) and append exactly one fun footer line
at the very end of the file (following other content and a blank line) to
satisfy the coding guidelines for README files.
| ```bash | ||
| # Rollback to previous release | ||
| git checkout tags/v1.2.3 | ||
| git push origin develop --force-with-lease | ||
|
|
||
| # Or create hotfix branch from previous stable | ||
| git checkout -b hotfix/rollback-v1.2.4 tags/v1.2.3 | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
Verify force-push safety in rollback procedure.
The rollback commands include git push origin develop --force-with-lease, which could be dangerous in a shared repository environment. Ensure this aligns with your branch protection rules and that maintainers understand the implications.
🏁 Script executed:
#!/bin/bash
# Verify branch protection settings for develop branch
gh api repos/lightspeedwp/.github/branches/develop/protection | jq '.required_pull_request_reviews, .enforce_admins, .restrictions'Length of output: 68
---
🏁 Script executed:
```shell
#!/bin/bash
# Read GOVERNANCE.md to see full context and any branch safety guidance
cat GOVERNANCE.md
Length of output: 7589
🏁 Script executed:
#!/bin/bash
# Search for GitHub configuration files that might define branch protection
fd -t f '\.(yml|yaml|json)$' .github/ 2>/dev/null | head -20Length of output: 913
🏁 Script executed:
#!/bin/bash
# Search for branch protection, force-push, or similar safety mentions in docs
rg -i 'force-push|force push|branch.?protect|develop.*protection' --type md -C 3Length of output: 14617
🏁 Script executed:
#!/bin/bash
# Check BRANCHING_STRATEGY.md for branch protection guidance
cat .github/BRANCHING_STRATEGY.md 2>/dev/null || echo "File not found"Length of output: 14
🏁 Script executed:
#!/bin/bash
# Search for develop branch specific guidance or warnings
rg -i 'develop' --type md -A 2 -B 2 'force|rollback|emergency' Length of output: 64
🏁 Script executed:
#!/bin/bash
# Fix regex syntax - search for docs mentioning force-push context
rg -i 'force.with.lease|force-push' --type md -B 3 -A 3Length of output: 731
🏁 Script executed:
#!/bin/bash
# Check if there's a BRANCHING_STRATEGY.md in docs/ directory
find . -name 'BRANCHING_STRATEGY.md' -o -name '*branching*' -o -name '*branch*' | grep -E '\.(md|yml)$' | head -10Length of output: 554
🏁 Script executed:
#!/bin/bash
# Check the BRANCHING_STRATEGY.md file
cat .github/automation/BRANCHING_STRATEGY.mdLength of output: 11557
🏁 Script executed:
#!/bin/bash
# Check git-org-wide-branching-strategy.md for branch protection details
cat docs/git-workflow/git-org-wide-branching-strategy.mdLength of output: 7938
Update rollback procedure to comply with org branching strategy.
The rollback commands in GOVERNANCE.md (lines 152–159) include git push origin develop --force-with-lease, which directly conflicts with the explicit policy in BRANCHING_STRATEGY.md (Section 6): "Never force push to shared branches (main, develop); use protected branch settings."
This procedure should be revised to either:
- Create a new release tag and cherry-pick/revert commits rather than force-pushing
- Document this as a documented exception with explicit prerequisites (branch protection must permit admins to override)
- Reference the full rollback decision tree and stakeholder notification process
Align GOVERNANCE.md rollback steps with the org-wide branching strategy documented in .github/automation/BRANCHING_STRATEGY.md.
🤖 Prompt for AI Agents
In GOVERNANCE.md around lines 152–159, the rollback commands currently suggest
force-pushing to develop which violates the org branching strategy; update these
steps to align with .github/automation/BRANCHING_STRATEGY.md by replacing the
force-push workflow with one of the approved alternatives: 1) show the
recommended safe rollback flow — checkout the tag, create a hotfix branch
(hotfix/rollback-<version>) from the tag, apply necessary revert or cherry-pick
commits, push the hotfix branch, and open a PR to merge into develop/main
(include required reviews and CI); 2) alternatively describe creating a new
release tag and performing targeted reverts/cherry-picks without force-pushing;
or 3) if a force-push is absolutely required, add a documented exception section
referencing branch protection prerequisites and stakeholder approvals per the
rollback decision tree; finally add a cross-reference/link to
.github/automation/BRANCHING_STRATEGY.md (Section 6) and to the rollback
decision tree and notification process.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw <ashley@lightspeedwp.agency>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw <ashley@lightspeedwp.agency>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Ash Shaw <ashley@lightspeedwp.agency>
ashleyshaw
deleted the
claude/github-docs-discoverability-011CV37rmVvF7oH3jJUhCydB
branch
Comprehensive documentation and governance improvements to enhance discoverability, standardization, and consumer adoption across the LightSpeed organization.
Changes
Added
docs/ mini-READMEs - Created README files for all docs subdirectories (bugherd, frontmatter, git-workflow, label-automation, ls-projects, wp-guides, wordpress, assets) with purpose, inputs/outputs, and examples
docs/labels.md - Comprehensive label semantics guide with usage examples, automation workflows, and best practices for all label families
Label sync workflow - New .github/workflows/label-sync.yml for automated label synchronization from canonical source, orphan detection, and reporting
Consumer guide in README - Added extensive "Reusing Workflows and Syncing Labels" section with practical examples for adopting LightSpeed standards
Exception process in GOVERNANCE.md - Documented how repositories can override defaults, exception requirements, and quarterly review process
Release cadence in GOVERNANCE.md - Defined fortnightly/quarterly release schedule, maintenance windows, and rollback procedures
Security SLA in SECURITY.md - Added comprehensive SLA table with response times, severity definitions, and vulnerability disclosure policy
Changed
PR template - Added Risk Assessment and How to Test sections with detailed prompts for risk level, impact analysis, mitigation steps, and testing instructions
CODEOWNERS - Expanded with granular ownership assignments for critical paths (workflows, labels, automation, documentation, scripts, tests, schemas)
README - Enhanced with 10-section consumer guide including workflow reuse, label sync, branch naming, setup scripts, validation, and monitoring
Improved
Documentation discoverability - Each docs subfolder now has descriptive README with clear purpose, usage examples, and cross-references
Community health - Enhanced SECURITY.md with detailed reporting process, SLA commitments, and security best practices
Governance transparency - Added exception process, release cadence, and rollback procedures for predictable org-wide updates
Impact
Testing
Addresses GitHub docs discoverability and community health checklist items.
name: "Pull Request"
about: "General changes, refactors, and maintenance"
title: "PR: {short summary}"
labels: ["status:needs-review"]
General Pull Request
Linked issues
Closes #
Changelog
Here’s an updated changelog summary for PR #53 using the required "Added", "Changed", "Fixed", and "Removed" headings, matching the details present in the PR’s original description:
Changelog
Added
docs/subfolder (bugherd, frontmatter, git-workflow, label-automation, ls-projects, wp-guides, wordpress, assets) describing folder purpose, inputs/outputs, and usage examples.docs/labels.mdwith a comprehensive guide to label semantics, usage examples, automation workflows, and best practices for all label families..github/workflows/label-sync.ymlfor automated org-wide label synchronization and orphan label detection/reporting.README.md, explaining workflow reuse and label sync adoption with practical examples.GOVERNANCE.md—requirements for deviations from standards and review procedures.GOVERNANCE.md, including maintenance and rollback procedures.SECURITY.mdwith detailed response times, vulnerability severity definitions, and disclosure policy.Changed
CODEOWNERSfile: more granular ownership for critical paths (workflows, labels, automation scripts, docs, tests, schemas).README.md: new 10-section consumer guide on workflow/label reuse, setup, branch naming, validation, and monitoring.Fixed
Removed
Checklist (Global DoD / PR)
References
Summary by CodeRabbit
Documentation
Chores