common

Instruction file imported from wunderio/drupal-project (.cursor/rules/common.mdc). Copyright stays with the author.

Common rules for using Cursor AI Code Editor in Wunder Drupal projects

File Organization

• Keep all rule files in @.cursor/rules/ directory
• Use .mdc extension for rule files
• Name files descriptively (e.g., common.mdc)
• Each rule file should focus on a specific component or feature
• Use @.cursorindexingignore to exclude files from Cursor's indexing:
  • Database dumps and large binary files
  • Environment-specific configuration files
  • Drupal's generated files and directories
  • Vendor directories and dependencies
  • Temporary files, logs, and cache files
  • Sensitive deployment files:
    • silta/*.secrets

Key Project Files

• Configuration & Setup

  • @.ddev/config.yaml - Local development environment configuration (DDEV)
  • @composer.json - PHP dependencies and project configuration
  • @README.md - Project documentation and setup instructions
  • @.env.example - Example environment variables template
  • @phpstan.neon - PHP Static Analysis configuration
  • @phpcs.xml - PHP Code Sniffer ruleset
  • @grumphp.yml - Git hooks and code quality checks

• Deployment & CI/CD

  • @.circleci/config.yml - CircleCI configuration for CI/CD pipelines
  • @silta/silta.yml - Kubernetes deployment configuration
  • @silta/silta-main.yml - Main environment specific configuration
  • @silta/silta-prod.yml - Production environment specific configuration

• Utilities & Scripts

  • DDEV commands:
    • ddev start - Start the development environment
    • ddev composer install - Install PHP dependencies
    • ddev drush - Run Drush commands
    • ddev xdebug - Configure Xdebug

• Drupal Specific

  • @web/sites/default/settings.php - Drupal settings
  • @drush/ - Drush commands and configuration

Documentation

• Use markdown for documentation
• Reference files with @ prefix for better IDE integration
• Document dependencies and versions
• Note breaking changes
• Include future considerations
• Keep documentation up to date with code changes, especially @README.md
• Document version constraints and requirements
• Keep Cursor code functionality related rules up to date with code changes (@.cursor/rules/*.mdc)
• Reference specific rules when applicable, see: @.cursor/rules/
• When proposing code changes, always include a git commit message following the format defined in Git Commits section

Git Commits

Prefix commit message with JIRA ticket number from branch name, following Conventional Commits specification. Format commit messages using the following types:

• feat: New feature (correlates with MINOR in semantic versioning)
• fix: Bug fix (correlates with PATCH in semantic versioning)
• docs: Documentation changes
• style: Changes that do not affect the meaning of the code
• refactor: Code changes that neither fix a bug nor add a feature
• perf: Performance improvements
• test: Adding missing tests or correcting existing tests
• build: Changes that affect the build system or external dependencies
• ci: Changes to CI configuration files and scripts
• chore: Other changes that don't modify src or test files

Breaking changes must be indicated by appending a ! after the type/scope or including "BREAKING CHANGE:" in the footer.

When providing commit messages, always use Cursor's code block feature (the code block button in the editor or triple backticks in markdown). This creates a copyable code block with the "Copy" button that allows for one-click copying with exact formatting including hyphens. Always provide just the commit message itself without any surrounding explanations:

QAG-xxxx: (type) Concise description of changes

- First change detail with hyphen for GitHub markdown compatibility
- Second change detail
- Third change detail

Refs: file1.ext, file2.ext

Git Diff for Commit Messages

When creating commit messages, always analyze the actual changes using git diff for the specific file(s) modified:

• Use git diff --staged | cat as the default approach to see all staged changes. This ensures you capture all modifications intended for the commit.
• Use git diff <filename> to see specific changes to a file
• Review the diff output to identify:
  • What functionality was added, modified, or removed
  • Which files were affected
  • The scope and impact of the changes
• Ensure commit message bullet points accurately reflect the changes visible in the diff
• Be specific about what changed and why, based on the actual code modifications

Development Environment

Code Standards

• PHP version: 8.4+ (as specified in @composer.json)
• Follow Drupal coding standards (defined in @phpcs.xml)
• Follow PHP Static Analysis rules (defined in @phpstan.neon)
• Use GrumPHP for enforcing code quality standards (@grumphp.yml)
• Group related changes by component
• Use consistent naming conventions
• Comment complex logic
• Consider backward compatibility

Technology Stack

• Core Technologies

  • Drupal
  • PHP via Nginx
  • MariaDB

• Development Tools

  • Xdebug
  • PHPStan
  • PHPCS/PHPCBF with WunderDrupal and WunderSecurity rulesets
  • GrumPHP for Git hooks
  • Composer for PHP dependencies
  • NPM for front-end assets

• Infrastructure

  • DDEV for local development (containerized environment with Nginx, PHP, MariaDB)
    • Additional services: Adminer, Elasticsearch, Kibana, Mailpit, Varnish
    • Configuration in @.ddev/config.yaml and related service files
  • Silta deployment system (Wunder's Kubernetes deployment solution) @wunderio/silta
  • Helm charts for Kubernetes orchestration
  • Docker containerization (Nginx and PHP containers)
  • Google Cloud Platform (GCP) infrastructure
  • Kubernetes-based autoscaling (2-10 replicas in production)
  • Varnish caching (configurable)
  • CircleCI for continuous integration