README

A simple, focused coding standards system for Drupal development that creates IDE-specific guidelines.

What is Drupal Surge?

Drupal Surge is a clean, focused toolkit that creates IDE-specific coding standards based on a single source of truth. It provides:

Single Standards File: One comprehensive drupal-surge-standards.md file
Community Guidelines: Automatically detect and merge guidelines from your project's guidelines directory
Interactive Script: Simple script to create guidelines for your preferred IDE/Tool
Clean Structure: No unnecessary files or complexity
Drupal Best Practices: Comprehensive guidelines following Drupal coding standards

Community Guidelines

Drupal Surge automatically scans for community-contributed guidelines in surge-guidelines/* directories throughout your project structure using recursive scanning. This allows:

Package Authors: Include guidelines with your Drupal modules/themes
Project Teams: Share project-specific standards
Easy Discovery: Guidelines are easily found in the surge-guidelines/ directory
Seamless Integration: Community guidelines are merged with base standards

Adding Community Guidelines

To contribute guidelines to your package or project:

Create a surge-guidelines/ directory in your project root
Add .md files with your guidelines
Drupal Surge will automatically detect and merge these guidelines when you run the scan command

Recursive scanning means Drupal Surge automatically discovers guidelines in:

Main project guidelines: surge-guidelines/
Module-specific guidelines: modules/custom/your-module/surge-guidelines/
Theme-specific guidelines: themes/custom/your-theme/surge-guidelines/
Any other project subdirectory with surge-guidelines/

Example structure:

your-drupal-project/
├── surge-guidelines/                    # Main project guidelines
│   ├── project-standards.md
│   └── coding-standards.md
├── modules/custom/your-module/
│   └── surge-guidelines/                # Module-specific guidelines
│       └── module-standards.md
├── themes/custom/your-theme/
│   └── surge-guidelines/                # Theme-specific guidelines
│       └── theme-standards.md
└── composer.json

Quick Start

1. Scan for Community Guidelines (Optional but Recommended)

# Option 1: Direct command execution
php surge scan-guidelines

# Option 2: Via Composer (recommended)
composer run surge-scan

2. Run the Interactive Script

# Option 1: Direct command execution
php surge standards

# Option 2: Via Composer (recommended)
composer run surge-standards

2. Choose Your Development Tool

The script will present you with options:

Junie (PhpStorm) → Creates .junie/guidelines.md
Cursor → Creates .cursor/rules/drupal-surge-standards.md
Claude Code → Creates Claude.md in project root
Exit → Quit without creating files

Commands

`php surge standards`

Generate IDE-specific guidelines from your standards (base or merged).

`php surge scan-guidelines`

Scan for community guidelines and merge them with base standards.

Options:

--output, -o: Specify output file path
--dry-run: Preview what would be merged without writing files

Project Structure

standards/
├── drupal-surge-standards.md                    # 🎯 Base standards file
└── drupal-surge-standards-with-community.md    # 🔗 Merged standards (auto-generated)

surge-guidelines/                                # 📚 Community guidelines directory
    ├── community-example.md                     # Example community guidelines
    ├── security-standards.md                    # Security guidelines
    └── testing-standards.md                     # Testing guidelines

surge                                           # Symfony Console application

drupal / surge

Maintainers

Details