Skip to content

Conversation

@ashleyshaw
Copy link
Member

@ashleyshaw ashleyshaw commented Nov 13, 2025


name: "Pull Request"
about: "General changes, refactors, and maintenance"
title: "PR: Set up comprehensive branding automation scaffolds and workflows"
labels: ["status:needs-review"]

General Pull Request

Add comprehensive branding automation system including:

  • Schema files for badges, emojis, footers, and front matter validation
  • GitHub Actions workflow for automated branding application
  • Complete documentation in docs/BRANDING.md
  • Metrics tracking files (JSON snapshot and historical log)

Schema files:

  • .github/automation/badges.schema.yml: Badge definitions and mapping rules
  • .github/automation/emoji.schema.yml: Emoji application rules for H1/H2
  • .github/automation/footers.yml: Category-based footer phrase selection
  • .github/automation/front-matter.schema.json: Front matter validation schema

Workflow:

  • .github/workflows/branding.yml: Automated validation, linting, branding application, and metrics

Documentation:

  • docs/BRANDING.md: Complete specification with examples, opt-out options, and reference links

Metrics:

  • .github/metrics/branding.json: Current metrics snapshot
  • .github/metrics/branding-log.md: Historical metrics log

All schemas validated (YAML/JSON) successfully.

Relates-to: Branding automation audit and consolidation

Linked issues

Relates to: Branding automation audit and consolidation

Changelog

Added

  • Comprehensive branding automation scaffolds and workflows:
    • Schema files for badges, emojis, footers, and front matter validation:
      • .github/automation/badges.schema.yml
      • .github/automation/emoji.schema.yml
      • .github/automation/footers.yml
      • .github/automation/front-matter.schema.json
    • GitHub Actions workflow for automated branding application:
      • .github/workflows/branding.yml
    • Documentation:
      • docs/BRANDING.md (full process, opt-out, and references)
    • Metrics tracking system:
      • .github/metrics/branding.json (current snapshot)
      • .github/metrics/branding-log.md (historical log)
  • Automated front-matter validation for content files
  • Automated badge generation and emoji assignment to document headings
  • Automated footer insertion with deterministic seeding

Changed

Fixed

Removed


Risk Assessment

Risk Level: Low

Potential Impact:

  • Mainly new scaffolding and documentation; core repo/build systems are not altered.
  • If misconfigured, branding automation may apply labels or formatting incorrectly in docs/markdown files or fail validation.

Mitigation Steps:

  • Schemas fully validated (YAML/JSON).
  • Dedicated GitHub Actions workflow tested independently.
  • Documentation included for contributor clarity.
  • Branding automation does not alter production code.
  • Metrics system allows for rollback or monitoring of automated application.

How to Test

Prerequisites

  • Ensure GitHub Actions are enabled for the repo.
  • Ensure test branches contain documentation or markdown files for branding automation to act on.

Test Steps

  1. Trigger branding workflow:

    • Open or update a markdown file, push a branch, or create a PR.
    • Expected: Branding automation workflow triggers via .github/workflows/branding.yml.
  2. Review workflow output:

    • Check Actions tab for branding job status and output (validation/lint/metrics).
  3. Validate schema enforcement:

    • Introduce valid/invalid badge, emoji, footers, or front matter in docs, and observe workflow's success/failure.
  4. Test metrics updates:

    • Make changes to docs across PRs; .github/metrics/branding.json and branding-log.md should be updated.

Expected Results

  • Branding automation applies/validates badges, emojis, footers, and front matter in documentation automatically.
  • PRs with schema compliance should pass workflow.
  • Non-compliant docs should trigger clear, actionable GitHub Action errors.
  • Metrics files are updated with each workflow run.

Edge Cases to Verify

  • Workflow skips if automation is opted out in a repo or file.
  • Handles repos with no markdown/docs gracefully (no errors).
  • Validates invalid schema entries and reports errors.
  • Handles concurrent PRs without metrics corruption.
  • Outputs appropriate error for malformed YAML/JSON.
  • Documentation opt-out is respected.

Checklist (Global DoD / PR)

  • All AC met and demonstrated
  • Tests added/updated (unit/E2E as appropriate)
  • A11y considerations addressed where relevant
  • Docs/readme/changelog updated (if user-facing)
  • Security/perf impact reviewed where relevant
  • Code/design reviews approved
  • CI green; linked issues closed; release notes prepared (if shipping)
  • Risk assessment completed above
  • Testing instructions provided above

References


Summary by CodeRabbit

  • New Features

    • Automated front-matter validation for content files
    • Automated badge generation based on repository metadata
    • Automated emoji assignment for document headings
    • Automated footer insertion with deterministic seeding
  • Chores

    • Added branding automation infrastructure and metrics tracking system

Add comprehensive branding automation system including:

- Schema files for badges, emojis, footers, and front matter validation
- GitHub Actions workflow for automated branding application
- Complete documentation in docs/BRANDING.md
- Metrics tracking files (JSON snapshot and historical log)

Schema files:
- .github/automation/badges.schema.yml: Badge definitions and mapping rules
- .github/automation/emoji.schema.yml: Emoji application rules for H1/H2
- .github/automation/footers.yml: Category-based footer phrase selection
- .github/automation/front-matter.schema.json: Front matter validation schema

Workflow:
- .github/workflows/branding.yml: Automated validation, linting, branding application, and metrics

Documentation:
- docs/BRANDING.md: Complete specification with examples, opt-out options, and reference links

Metrics:
- .github/metrics/branding.json: Current metrics snapshot
- .github/metrics/branding-log.md: Historical metrics log

All schemas validated (YAML/JSON) successfully.

Relates-to: Branding automation audit and consolidation
@ashleyshaw ashleyshaw requested a review from krugazul as a code owner November 13, 2025 13:52
@coderabbitai
Copy link
Contributor

coderabbitai bot commented Nov 13, 2025

Warning

Rate limit exceeded

@ashleyshaw has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 15 minutes and 43 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

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.

📥 Commits

Reviewing files that changed from the base of the PR and between 60de9bd and 55d64ab.

📒 Files selected for processing (5)
  • .github/automation/emoji.schema.yml (1 hunks)
  • .github/automation/footers.yml (1 hunks)
  • .github/metrics/branding.json (1 hunks)
  • .github/workflows/branding.yml (1 hunks)
  • docs/BRANDING.md (1 hunks)

Note

Other AI code review bot(s) detected

CodeRabbit 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

.coderabbit.yml has unrecognized properties

CodeRabbit is using all valid settings from your configuration. Unrecognized properties (listed below) have been ignored and may indicate typos or deprecated fields that can be removed.

⚠️ Parsing warnings (1)
Validation error: Unrecognized key(s) in object: 'auto_labels', 'auto_assign', 'auto_review'
⚙️ Configuration instructions
  • Please see the configuration documentation for more information.
  • You can also validate your configuration using the online YAML validator.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
📝 Walkthrough

Walkthrough

Introduces a comprehensive branding automation framework with configuration schemas for front matter validation, badge definitions, emoji mapping, and footer management. Adds a GitHub Actions workflow that validates, lints, applies branding transformations, and tracks metrics across repository content. Includes schema definitions, workflow orchestration, and specification documentation.

Changes

Cohort / File(s) Summary
Schema Configurations
.github/automation/front-matter.schema.json, .github/automation/badges.schema.yml, .github/automation/emoji.schema.yml, .github/automation/footers.yml
New schema and configuration files defining validation rules and deterministic mappings for front matter blocks, badge display logic, emoji keyword-to-icon associations, and footer phrase selection with xorshift32 seeding strategy.
Metrics & Tracking
.github/metrics/branding.json, .github/metrics/branding-log.md
New metrics files: JSON snapshot structure with placeholder counters (ts, coverage, changes, errors, optouts) and Markdown log template with YAML front matter for historical branding automation metrics.
Workflow Automation
.github/workflows/branding.yml
GitHub Actions workflow orchestrating front-matter validation, markdown linting, link checking, branding agent execution (with conditional commit/push on non-PR events), and metrics update with sequential job dependencies.
Documentation
docs/BRANDING.md
Comprehensive Branding Agent specification covering scope, governing schemas, workflow steps, emoji/footer/badge application rules, opt-out mechanisms, examples, metrics structure, and QA/testing guidelines.

Sequence Diagram

sequenceDiagram
    participant GH as GitHub Actions
    participant FM as front-matter-validate
    participant LL as lint-and-links
    participant AB as apply-branding
    participant MU as metrics-update

    GH->>FM: Trigger (PR/push/schedule)
    GH->>LL: Trigger (PR/push/schedule)
    
    par Parallel Validation
        FM->>FM: Validate front matter<br/>in changed MD files
        LL->>LL: Run markdown lint<br/>& link checks (Lychee)
    end
    
    rect rgb(200, 220, 255)
    Note over FM,LL: Both jobs must complete
    end
    
    alt if push (not PR)
        FM-->>AB: pass
        LL-->>AB: pass
        AB->>AB: Execute brandingAgent<br/>(Node.js)
        AB->>AB: Commit content changes<br/>via bot identity
        AB-->>MU: complete
    else if PR
        Note over AB: Skipped (PR event)
        AB-->>MU: skip
    end
    
    rect rgb(240, 250, 240)
    Note over MU: Always runs after apply-branding
    end
    
    MU->>MU: Generate metrics snapshot<br/>(JSON + MD log)
    MU->>MU: Commit & push metrics
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

  • .github/workflows/branding.yml: Review job dependencies, conditional logic, Node.js agent invocation, and commit/push mechanics with bot identity configuration. Verify correct sequencing and permissions.
  • .github/automation/ configuration files: Validate schema syntax (YAML/JSON), deterministic mapping rules (badges, emoji, footers), and confirm seeding strategy documentation.
  • .github/metrics/ files: Confirm placeholder structure aligns with workflow metrics-update output.
  • docs/BRANDING.md: Cross-reference documentation against schema definitions and workflow implementation for consistency.

Possibly related PRs

Suggested labels

documentation, status:needs-review, lang:md, lang:javascript

Suggested reviewers

  • krugazul

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check ✅ Passed The PR title directly and accurately describes the main change: setting up comprehensive branding automation scaffolds and workflows, which aligns with the addition of schema files, GitHub Actions workflows, documentation, and metrics infrastructure.
Description check ✅ Passed PR description is comprehensive and follows the template structure with all major sections completed, including detailed changelog, risk assessment, test instructions, and checklist.

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions
Copy link
Contributor

⚠️ Frontmatter validation failed

Please check the workflow logs for details and ensure all frontmatter follows the schema at schemas/frontmatter/frontmatter.schema.json.

See Frontmatter Documentation for guidance.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

🧹 Nitpick comments (1)
.github/workflows/branding.yml (1)

39-46: Implement dependency caching for npm packages.

The front-matter-validate job installs a global npm package (ajv-cli) without caching. Per coding guidelines, "Cache dependencies deterministically with actions/cache using a key derived from lockfiles."

Apply this diff to add caching before the npm install step:

       - uses: actions/setup-node@v4
         with:
           node-version: '20'
+
+      - name: Cache npm dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+          restore-keys: |
+            ${{ runner.os }}-npm-
 
       - name: Validate Front Matter
         run: |
           npm i -g ajv-cli
📜 Review details

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 120b84c and 60de9bd.

📒 Files selected for processing (8)
  • .github/automation/badges.schema.yml (1 hunks)
  • .github/automation/emoji.schema.yml (1 hunks)
  • .github/automation/footers.yml (1 hunks)
  • .github/automation/front-matter.schema.json (1 hunks)
  • .github/metrics/branding-log.md (1 hunks)
  • .github/metrics/branding.json (1 hunks)
  • .github/workflows/branding.yml (1 hunks)
  • docs/BRANDING.md (1 hunks)
🧰 Additional context used
📓 Path-based instructions (15)
.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/metrics/branding-log.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/metrics/branding-log.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

Files:

  • .github/workflows/branding.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/branding.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/branding.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/branding.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/branding.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/branding.yml
**/*.{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/BRANDING.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/BRANDING.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/BRANDING.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/BRANDING.md
**/*.md

📄 CodeRabbit inference engine (.github/instructions/naming-conventions.instructions.md)

Always include a canonical file_type field in YAML frontmatter of Markdown files

Files:

  • docs/BRANDING.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/BRANDING.md
docs/**

📄 CodeRabbit inference engine (.github/instructions/reviews.instructions.md)

Update pattern or feature documentation when behavior or APIs change

Files:

  • docs/BRANDING.md
🪛 GitHub Actions: Frontmatter Validation
.github/metrics/branding-log.md

[error] 1-1: Frontmatter validation failed: tag 'file_type' must be a string in .github/metrics/branding-log.md.

🪛 LanguageTool
.github/metrics/branding-log.md

[grammar] ~8-~8: Ensure spelling is correct
Context: ...mestamp | coverage | changes | errors | optouts | |---|---:|---:|---:|---:|

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

docs/BRANDING.md

[uncategorized] ~44-~44: The official name of this software platform is spelled with a capital “H”.
Context: ...ow The branding system is triggered by branding.yml on: - Pull req...

(GITHUB)


[uncategorized] ~84-~84: The official name of this software platform is spelled with a capital “H”.
Context: ...onservative emoji application following emoji.schema.yml: - **Appl...

(GITHUB)


[uncategorized] ~179-~179: The official name of this software platform is spelled with a capital “H”.
Context: ...n The branding logic is implemented in branding.agent.js. ### Key Fun...

(GITHUB)


[uncategorized] ~194-~194: The official name of this software platform is spelled with a capital “H”.
Context: ...k: Jest (TODO: confirm) Test location: .github/agents/__tests__/ (TODO: confirm) ## ...

(GITHUB)

🔇 Additional comments (6)
.github/metrics/branding.json (1)

1-7: Well-structured metrics placeholder.

The JSON metrics file provides a clean template for the metrics-update job in the workflow. The initialization of numeric fields to 0 and an empty timestamp string aligns with the expected runtime behavior described in docs/BRANDING.md.

.github/automation/front-matter.schema.json (1)

1-14: Valid front matter schema with appropriate flexibility.

The JSON Schema is well-formed and the property definitions align with the branding automation requirements outlined in docs/BRANDING.md. The no_branding boolean flag supports the documented opt-out mechanism, and additionalProperties: true provides sensible flexibility for future extensions.

.github/automation/badges.schema.yml (1)

1-33: Well-structured badge schema with deterministic mapping rules.

The badges configuration clearly defines two badge groups (workflow and meta) with complete properties. The mapping rules are deterministic and testable, and the render order is explicit. This schema effectively supports the badge-based visibility for front-matter validation and license status described in docs/BRANDING.md.

.github/automation/emoji.schema.yml (1)

1-15: Conservative and well-reasoned emoji mapping.

The emoji schema demonstrates a thoughtful, conservative approach: limited to h1/h2 headings, excludes formal documents, uses keyword-based matching with a sensible fallback, and enforces a 0–1 emoji limit per heading. The mapping keywords (design, workflow, release, governance) align well with typical documentation categories.

docs/BRANDING.md (1)

224-226: Ensure footer is properly formatted per guidelines.

The file ends with a footer line, but per coding guidelines for docs/**/*.md files, it must be formatted as a properly marked footer. Verify that the footer text "Made with ❤️ by the LightSpeed team." is the intended fun footer variant and is positioned as the final element of the file.

Confirm that the footer is one of the approved variants from the repository's footer phrase list, and ensure it is the only footer in the file.

.github/automation/footers.yml (1)

28-31: Remove TODO or implement the seeded footer selection strategy.

The footers.yml configuration specifies a "seeded" selection strategy using xorshift32 for deterministic, per-file footer assignment. However, this entire mechanism is not implemented in the codebase. The actual footer implementation in footerUtils.js uses pure random selection via Math.random(), and the footers.yml configuration file is not consumed by any code—it appears to be documentation or aspirational specification only.

Either implement the deterministic seeding strategy described in the configuration, or remove the TODO comment and unused configuration to clarify that random selection is the intended behavior.

Comment on lines +1 to +4
---
title: 'Branding Metrics Log'
description: 'Historical log of branding automation metrics'
---
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Add required frontmatter fields to pass validation.

The file is missing critical frontmatter fields required by the coding guidelines. The pipeline failure confirms this: file_type must be a string. Per guidelines, all Markdown files require: version, last_updated, owners, file_type, and category.

Apply this diff to add the missing frontmatter fields:

 ---
 title: 'Branding Metrics Log'
 description: 'Historical log of branding automation metrics'
+version: 'v1.0'
+last_updated: '2025-11-13'
+owners: ['ashleyshaw']
+file_type: 'metrics-log'
+category: 'metrics'
 ---

Committable suggestion skipped: line range outside the PR's diff.

🧰 Tools
🪛 GitHub Actions: Frontmatter Validation

[error] 1-1: Frontmatter validation failed: tag 'file_type' must be a string in .github/metrics/branding-log.md.

🤖 Prompt for AI Agents
In .github/metrics/branding-log.md lines 1-4 the YAML frontmatter is missing
required fields which causes validation to fail; add the following frontmatter
keys with appropriate values and types: version (string, e.g. "1.0"),
last_updated (ISO date string, e.g. "2025-11-13"), owners (array of strings or
single string), file_type (string, e.g. "metrics"), and category (string, e.g.
"branding"); ensure the frontmatter is valid YAML at the top of the file
(between --- markers) and that file_type is explicitly a string.

Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR establishes the foundational scaffolding for an automated branding system that will apply consistent formatting, badges, emojis, and footers to documentation across the repository. The system includes schema definitions, a GitHub Actions workflow, metrics tracking, and comprehensive documentation.

Key changes:

  • Schema-driven branding rules for badges, emojis, footers, and front matter validation
  • Automated GitHub Actions workflow to validate and apply branding to markdown files
  • Metrics tracking system with JSON snapshot and historical log

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 9 comments.

Show a summary per file
File Description
docs/BRANDING.md Comprehensive specification documenting the branding system's scope, schemas, workflow, examples, and opt-out mechanisms
.github/workflows/branding.yml GitHub Actions workflow implementing front-matter validation, linting, branding application, and metrics tracking
.github/metrics/branding.json Initial metrics snapshot file with placeholder structure for coverage, changes, errors, and opt-outs tracking
.github/metrics/branding-log.md Historical metrics log with table structure for timestamp-based tracking
.github/automation/front-matter.schema.json JSON Schema for validating front matter structure in markdown files
.github/automation/footers.yml Category-based footer phrase definitions with seeded selection strategy
.github/automation/emoji.schema.yml Rules for conservative emoji application to H1/H2 headings with keyword mapping
.github/automation/badges.schema.yml Badge definitions, mapping rules, and render order configuration

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

FILES=$(git diff --name-only ${{ github.sha }} ${{ github.base_ref || 'HEAD~1' }} | grep -E '\.md$' || true)
for f in $FILES; do
node -e "const fs=require('fs');const s=fs.readFileSync('$f','utf8');const m=s.match(/^---\\n([\\s\\S]*?)\\n---/); if(!m){process.exit(0)}"
yq -o=json '."'"$f"'"' >/dev/null 2>&1 || true
Copy link

Copilot AI Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The workflow uses yq in line 45 but yq is never installed as a dependency in the job. The front-matter-validate job should include a step to install yq before attempting to use it, or the validation logic should be rewritten to use only installed tools.

Copilot uses AI. Check for mistakes.
Comment on lines +75 to +77
- name: Run Branding Agent
run: |
node .github/agents/branding.agent.js
Copy link

Copilot AI Nov 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The branding.agent.js file referenced in line 77 and in the documentation does not exist in this PR. The workflow will fail when it attempts to execute this missing file. Either include the agent implementation in this PR or update the workflow to use a placeholder/stub until the agent is implemented.

Copilot uses AI. Check for mistakes.
@ashleyshaw ashleyshaw changed the title Set up branding automation scaffolds and workflows PR: Set up comprehensive branding automation scaffolds and workflows Nov 13, 2025
Co-authored-by: Copilot <[email protected]>
Signed-off-by: Ash Shaw <[email protected]>
@github-actions
Copy link
Contributor

⚠️ Frontmatter validation failed

Please check the workflow logs for details and ensure all frontmatter follows the schema at schemas/frontmatter/frontmatter.schema.json.

See Frontmatter Documentation for guidance.

ashleyshaw and others added 2 commits November 13, 2025 21:19
Co-authored-by: Copilot <[email protected]>
Signed-off-by: Ash Shaw <[email protected]>
Co-authored-by: Copilot <[email protected]>
Signed-off-by: Ash Shaw <[email protected]>
@github-actions
Copy link
Contributor

⚠️ Frontmatter validation failed

Please check the workflow logs for details and ensure all frontmatter follows the schema at schemas/frontmatter/frontmatter.schema.json.

See Frontmatter Documentation for guidance.

Co-authored-by: Copilot <[email protected]>
Signed-off-by: Ash Shaw <[email protected]>
@github-actions
Copy link
Contributor

⚠️ Frontmatter validation failed

Please check the workflow logs for details and ensure all frontmatter follows the schema at schemas/frontmatter/frontmatter.schema.json.

See Frontmatter Documentation for guidance.

1 similar comment
@github-actions
Copy link
Contributor

⚠️ Frontmatter validation failed

Please check the workflow logs for details and ensure all frontmatter follows the schema at schemas/frontmatter/frontmatter.schema.json.

See Frontmatter Documentation for guidance.

ashleyshaw and others added 2 commits November 13, 2025 21:20
Co-authored-by: Copilot <[email protected]>
Signed-off-by: Ash Shaw <[email protected]>
Co-authored-by: Copilot <[email protected]>
Signed-off-by: Ash Shaw <[email protected]>
@github-actions
Copy link
Contributor

⚠️ Frontmatter validation failed

Please check the workflow logs for details and ensure all frontmatter follows the schema at schemas/frontmatter/frontmatter.schema.json.

See Frontmatter Documentation for guidance.

1 similar comment
@github-actions
Copy link
Contributor

⚠️ Frontmatter validation failed

Please check the workflow logs for details and ensure all frontmatter follows the schema at schemas/frontmatter/frontmatter.schema.json.

See Frontmatter Documentation for guidance.

ashleyshaw and others added 2 commits November 13, 2025 22:34
Co-authored-by: Copilot <[email protected]>
Signed-off-by: Ash Shaw <[email protected]>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Signed-off-by: Ash Shaw <[email protected]>
@github-actions
Copy link
Contributor

⚠️ Frontmatter validation failed

Please check the workflow logs for details and ensure all frontmatter follows the schema at schemas/frontmatter/frontmatter.schema.json.

See Frontmatter Documentation for guidance.

1 similar comment
@github-actions
Copy link
Contributor

⚠️ Frontmatter validation failed

Please check the workflow logs for details and ensure all frontmatter follows the schema at schemas/frontmatter/frontmatter.schema.json.

See Frontmatter Documentation for guidance.

ashleyshaw and others added 2 commits November 13, 2025 22:35
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Signed-off-by: Ash Shaw <[email protected]>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Signed-off-by: Ash Shaw <[email protected]>
@github-actions
Copy link
Contributor

⚠️ Frontmatter validation failed

Please check the workflow logs for details and ensure all frontmatter follows the schema at schemas/frontmatter/frontmatter.schema.json.

See Frontmatter Documentation for guidance.

@github-actions
Copy link
Contributor

⚠️ Frontmatter validation failed

Please check the workflow logs for details and ensure all frontmatter follows the schema at schemas/frontmatter/frontmatter.schema.json.

See Frontmatter Documentation for guidance.

@ashleyshaw ashleyshaw merged commit 76b1a23 into develop Nov 13, 2025
6 of 21 checks passed
@ashleyshaw ashleyshaw deleted the claude/add-branding-scaffolds-011CV5ZXuU9mpv6q19ckQAHu branch November 13, 2025 15:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants