Skip to content

AGENTS.md

Latest commit

 

History

History
295 lines (217 loc) · 9.94 KB

AGENTS.md

File metadata and controls

295 lines (217 loc) · 9.94 KB
Raw

Mergify Documentation Site

Official documentation for Mergify - the merge queue and CI optimization platform.

Design System

See DESIGN.md for the docs site's design system: tokens, typography utilities, dark-mode rules, and STRICT code rules.

When you write or modify any styling, read DESIGN.md first. The rules there override defaults — no hex literals, no Chakra references, no --color-mergify-blue references, and components should use semantic tokens by default so dark mode works automatically. Product-specific UI elements (callouts, brand-colored buttons, product pills) may use var(--color-*) primitives directly as a narrow documented exception — see DESIGN.md for the policy.

Quick Facts

  • Framework: Astro 5.x with MDX
  • UI Libraries: React 19, Vue (for specific components)
  • Language: TypeScript (strict mode)
  • Node Version: 24 (see .node-version)
  • Formatter: Biome (primary), Prettier (for .astro files)
  • Linter: ESLint 9 (flat config)
  • Testing: Vitest
  • Deployment: Cloudflare Pages

Key Commands

# Development
pnpm start             # Start dev server (pages build on-demand)
pnpm build             # Full production build with type checking
pnpm preview           # Preview production build locally

# Code Quality
pnpm check             # Run all checks: astro check + eslint + biome
pnpm format            # Auto-format with Biome
pnpm format:check      # Check formatting without modifying

# Testing
pnpm test              # Run Vitest unit tests
./scripts/detect-broken-links.sh  # Check for broken links

# Safety
pnpm check:internal-leaks  # Scan docs for leaked internal information

Key Directories

  • src/content/docs/ - Main documentation pages (MDX files)
  • src/content/changelog/ - Changelog entries
  • src/components/ - Astro and React components
  • src/layouts/ - Page layout templates
  • src/util/ - Utility functions (with tests)
  • integrations/ - Custom Astro integrations
  • plugins/ - Custom Remark/Rehype plugins
  • public/ - Static assets

Code Style

TypeScript

  • Strict mode enabled
  • Use ~/* path alias for imports from src/
  • Prefer interfaces over types (except unions)

MDX Documentation Files

  • Always include YAML frontmatter with title and description
  • Import components at top of file
  • Use custom components for callouts: <Aside type="note|tip|caution|danger">
  • Code blocks use Shiki syntax highlighting

Formatting

  • 100 character line width
  • Single quotes
  • 2-space indentation
  • Trailing commas (ES5 style)
  • Semicolons required

Content Structure

Documentation is organized into sections:

  • configuration/ - Mergify configuration reference
  • merge-queue/ - Merge queue features and setup
  • workflow/ - Workflow automation
  • commands/ - GitHub comment commands
  • ci-insights/ - CI analytics and optimization
  • merge-protections/ - Branch protection rules
  • integrations/ - Third-party integrations
  • enterprise/ - Enterprise features

Callout Boxes

When writing documentation, use directive syntax for callouts:

:::note
  Important information here.
:::

:::tip
  Helpful suggestion.
:::

:::caution
  Be careful about this.
:::

:::danger
  Critical warning.
:::

Note: Content inside directives should be indented with 2 spaces.

Git Workflow

Creating Branches

When creating a new branch, always track the main branch:

git checkout -b my-feature-branch --track origin/main

Pushing Changes

Use Mergify's stack command to push:

mergify stack push

Do NOT use regular git push - always use mergify stack push.

Critical Rules

  1. Always run pnpm check before committing - Catches TypeScript, lint, and format errors

  2. MDX files must have valid frontmatter - Title and description required

  3. Images go in src/content/docs/images/ - Use relative imports

  4. Test locally with pnpm build - Ensures SSG works correctly

  5. Use mergify stack push to push - Not regular git push

  6. Never modify changelog entries - Files in src/content/changelog/ are autogenerated externally and must not be created, edited, or deleted

  7. No dated deprecation/migration notices in docs prose - Do not add "deprecated, will be removed on <date>" or migration callouts to pages in src/content/docs/. These rot quickly, and the changelog is the single source of truth for deprecations and removals. A dateless marker on a deprecated option's own reference page (matching existing action pages) is acceptable; dated migration notices are not.

  8. Never publish internal information - Ticket IDs, customer names, private repo paths, internal links, and credentials must never reach src/content/docs/. See the section below; it applies to every change, with no size threshold.

Never Publish Internal Information

Docs are usually written from internal material: a support case, a private PR, an engine source file, a Linear ticket. That material travels with the draft. The reader never needs to know where a page came from, so anything describing the provenance of a doc is a leak, not context. A leaked identifier cannot be unpublished.

Never write any of these into src/content/docs/ - prose, code blocks, comments, frontmatter, alt text, or screenshots:

  • Support ticket and thread IDs - Plain refs (T-1234), thread IDs (th_01JQ...), app.plain.com links, or the equivalent from any helpdesk.
  • Customer, org, and account identifiers - a customer's GitHub org or repo, account and subscription IDs, Stripe customer or invoice IDs, email addresses, real seat or contributor counts.
  • Private repositories and internal code paths - Mergifyio/monorepo, mergify_shadow_office/..., mergify_engine/..., dashboard source paths, internal module or function names, file:line references into private code.
  • Internal URLs and tools - Linear and Notion links, admin consoles, internal dashboards, staging or internal Mergify hostnames, runbooks.
  • Credentials - real tokens, API keys, private keys, webhook secrets. Placeholders (ghp_*, <your-token>) are fine.
  • Internal-only framing - employee names in an internal context, quotes from a support conversation, "as discussed with the customer", unreleased work, or an explanation that only makes sense if you read the ticket.

The fix is almost never deletion. State the product behavior and drop the provenance: "customer acme-corp on ticket T-1234 was billed after cancelling" becomes "if you cancel mid-period, a final invoice may still arrive on the last day of the period."

Enforcement, in order of what catches what:

  1. pnpm check:internal-leaks - deterministic scan for the mechanical patterns (ticket IDs, internal paths, internal trackers and hosts). Run it before committing any docs change. It also runs in CI. It cannot catch customer names, copied examples, or internal framing, so a clean run is not a pass.
  2. The proofread-leaks subagent - judgment-level review of the diff. Unlike the other proofreaders, this one runs on every docs change, including sub-10-line edits, frontmatter-only edits, and code-block-only edits.
  3. If something internal did reach a commit, say so plainly instead of quietly amending it. A value that was pushed may need scrubbing beyond the branch.

Documentation Proofreading

After editing MDX files in src/content/docs/, if the total changed/added lines across all edited docs files is 10 or more lines, you MUST run the proofreading pipeline before considering the work done.

How It Works

  1. Collect the diff: Get the diff of all changed MDX files in src/content/docs/ (use git diff for staged/unstaged changes).

  2. Spawn 5 proofreading subagents in parallel using the Agent tool, each with the diff and the list of changed files:

    • Style (proofread-style): AI patterns, banned words, tone, voice

    • Technical (proofread-technical): code examples, config keys, links, feature names

    • Structure (proofread-structure): frontmatter, headings, callouts, missing context

    • Consistency (proofread-consistency): terminology drift, capitalization, naming

    • Leaks (proofread-leaks): ticket IDs, customer names, private paths, internal links, secrets

  3. Each subagent:

    • Reads the skill with the Skill tool for its full guidelines

    • Reviews ONLY the changed/added lines

    • Fixes issues directly in the files

    • Reports what it changed

    • Notes FOLLOW-UP: suggestions for issues in surrounding unchanged content (does NOT edit those)

  4. After all subagents complete:

    • Summarize all fixes applied

    • List any FOLLOW-UP: suggestions as optional improvements for a separate commit

    • If follow-up suggestions exist, ask the user if they want to apply them as a separate change

Subagent Prompt Template

When spawning each subagent, include:

  • The skill name to invoke (e.g., "Read the proofread-style skill using the Skill tool, then follow its instructions")

  • The full diff output

  • The list of changed file paths

  • Instruction: "Fix issues directly. Report changes. Note FOLLOW-UP items for unchanged content."

When to Skip

proofread-leaks is never skipped. None of the conditions below apply to it: a leaked ticket ID is usually a one-line change, and it hides in code blocks and frontmatter as readily as in prose. Run it, plus pnpm check:internal-leaks, on every docs change.

The other four are skipped when:

  • Changes are fewer than 10 lines of docs content

  • Changes are ONLY to frontmatter metadata (title/description tweaks)

  • Changes are ONLY to code blocks with no prose changes

  • Changes are to files outside src/content/docs/

Common Issues

  • Build fails on MDX: Check for unclosed JSX tags or invalid frontmatter
  • Component not found: Ensure correct import path with ~/ alias
  • Styling issues: Check CSS scoping in components