Initial commit

2025-11-30 08:43:13 +08:00
commit f6d4a68978
178 changed files with 51030 additions and 0 deletions
--- a/skills/typo3-conformance/references/development-environment.md
+++ b/skills/typo3-conformance/references/development-environment.md
@@ -0,0 +1,524 @@
+# Development Environment Standards
+
+**Purpose:** Validate development environment setup for consistent, reproducible TYPO3 extension development
+
+## Why Development Environment Matters
+
+A properly configured development environment ensures:
+
+- ✅ **Consistency** - All developers work with identical PHP/TYPO3/database versions
+- ✅ **Onboarding** - New contributors can start immediately without complex setup
+- ✅ **CI/CD Parity** - Local environment matches production/staging
+- ✅ **Reproducibility** - Bugs are reproducible across all environments
+- ✅ **Cross-Platform** - Works on macOS, Linux, Windows (WSL)
+
+Without standardized dev environment:
+- ❌ "Works on my machine" syndrome
+- ❌ Inconsistent PHP/database versions causing bugs
+- ❌ Complex setup discourages contributions
+- ❌ CI failures that don't reproduce locally
+
+## TYPO3 Community Standards
+
+### DDEV - Primary Recommendation
+
+**DDEV** is the **de facto standard** for TYPO3 development:
+
+- ✅ Official TYPO3 core development uses DDEV
+- ✅ TYPO3 Best Practices (Tea extension) uses DDEV
+- ✅ TYPO3 documentation recommends DDEV
+- ✅ Cross-platform support (Docker-based)
+- ✅ Preconfigured for TYPO3 (`ddev config --project-type=typo3`)
+
+**Alternative:** Docker Compose (acceptable, more manual configuration)
+
+## Validation Checklist
+
+### 1. DDEV Configuration
+
+**Check for `.ddev/` directory:**
+
+```bash
+ls -la .ddev/
+```
+
+**Required files:**
+- `.ddev/config.yaml` - Core DDEV configuration
+- `.ddev/.gitignore` - Excludes dynamic files (import-db, .ddev-docker-compose-*.yaml)
+
+**Optional but recommended:**
+- `.ddev/config.typo3.yaml` - TYPO3-specific settings
+- `.ddev/commands/` - Custom DDEV commands
+- `.ddev/docker-compose.*.yaml` - Additional services
+
+**Severity if missing:** 🟡 **Medium** - Indicates no standardized dev environment
+
+### 2. DDEV config.yaml Structure
+
+**Minimum DDEV Configuration:**
+
+```yaml
+name: extension-name
+type: typo3
+docroot: .Build/public
+php_version: "8.2"  # Match composer.json minimum
+webserver_type: nginx-fpm
+router_http_port: "80"
+router_https_port: "443"
+xdebug_enabled: false
+additional_hostnames: []
+additional_fqdns: []
+database:
+  type: mariadb
+  version: "10.11"
+omit_containers: [ddev-ssh-agent]
+```
+
+**Validation Rules:**
+
+| Field | Validation | Example | Severity |
+|-------|-----------|---------|----------|
+| `name` | Should match extension key or composer name | `rte-ckeditor-image` | Low |
+| `type` | Must be `typo3` | `typo3` | High |
+| `docroot` | Should match composer.json web-dir | `.Build/public` | High |
+| `php_version` | Should match composer.json minimum PHP | `"8.2"` | High |
+| `database.type` | Should be `mariadb` (TYPO3 standard) | `mariadb` | Medium |
+| `database.version` | Should be LTS version (10.11 or 11.x) | `"10.11"` | Medium |
+
+**Example Check:**
+
+```bash
+# Extension composer.json
+"require": {
+    "php": "^8.2 || ^8.3 || ^8.4",
+    "typo3/cms-core": "^13.4"
+}
+"extra": {
+    "typo3/cms": {
+        "web-dir": ".Build/public"
+    }
+}
+
+# DDEV config.yaml SHOULD have:
+php_version: "8.2"          # ✅ Matches minimum
+docroot: .Build/public      # ✅ Matches web-dir
+type: typo3                 # ✅ Correct type
+
+# DDEV config.yaml SHOULD NOT have:
+php_version: "7.4"          # ❌ Below minimum
+docroot: public             # ❌ Doesn't match web-dir
+type: php                   # ❌ Wrong type
+```
+
+### 3. Docker Compose (Alternative)
+
+If DDEV not present, check for `docker-compose.yml`:
+
+**Minimum Docker Compose Configuration:**
+
+```yaml
+version: '3.8'
+
+services:
+  web:
+    image: ghcr.io/typo3/core-testing-php82:latest
+    volumes:
+      - .:/var/www/html
+    working_dir: /var/www/html
+    ports:
+      - "8000:80"
+    environment:
+      TYPO3_CONTEXT: Development
+
+  db:
+    image: mariadb:10.11
+    environment:
+      MYSQL_ROOT_PASSWORD: root
+      MYSQL_DATABASE: typo3
+    volumes:
+      - db_data:/var/lib/mysql
+
+volumes:
+  db_data:
+```
+
+**Validation Rules:**
+
+| Service | Validation | Severity |
+|---------|-----------|----------|
+| `web` service exists | Required | High |
+| PHP version matches composer.json | Required | High |
+| `db` service exists | Required | Medium |
+| Database type is MariaDB/MySQL | Recommended | Low |
+| Volumes preserve database data | Required | High |
+
+**Severity if missing:** 🟡 **Medium** - Harder to onboard, but not critical
+
+### 4. DevContainer (VS Code Remote Containers)
+
+Check for `.devcontainer/devcontainer.json`:
+
+**Example DevContainer Configuration:**
+
+```json
+{
+  "name": "TYPO3 Extension Development",
+  "dockerComposeFile": ["../docker-compose.yml"],
+  "service": "web",
+  "workspaceFolder": "/var/www/html",
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "bmewburn.vscode-intelephense-client",
+        "xdebug.php-debug",
+        "EditorConfig.EditorConfig"
+      ],
+      "settings": {
+        "php.validate.executablePath": "/usr/local/bin/php"
+      }
+    }
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {},
+    "ghcr.io/devcontainers/features/node:1": {}
+  }
+}
+```
+
+**Validation:**
+- File exists: ✅ Good (VS Code support)
+- References docker-compose.yml or DDEV: ✅ Integrated approach
+- Empty directory: ⚠️ Incomplete setup
+
+**Severity if missing:** 🟢 **Low** - Nice to have, not required
+
+## DDEV-Specific Best Practices
+
+### TYPO3-Optimized Settings
+
+**`.ddev/config.typo3.yaml`:**
+
+```yaml
+# TYPO3-specific DDEV configuration
+override_config: false
+web_extra_daemons:
+  - name: "typo3-backend-lock-handler"
+    command: "/var/www/html/.Build/bin/typo3 scheduler:run"
+    directory: /var/www/html
+
+hooks:
+  post-start:
+    - exec: composer install
+    - exec: .Build/bin/typo3 cache:flush
+
+# Additional PHP settings for TYPO3
+php_ini:
+  memory_limit: 512M
+  max_execution_time: 240
+  upload_max_filesize: 32M
+  post_max_size: 32M
+```
+
+### Custom DDEV Commands
+
+**`.ddev/commands/web/typo3`:**
+
+```bash
+#!/bin/bash
+## Description: Run TYPO3 CLI commands
+## Usage: typo3 [args]
+## Example: "ddev typo3 cache:flush"
+
+.Build/bin/typo3 "$@"
+```
+
+**`.ddev/commands/web/test-unit`:**
+
+```bash
+#!/bin/bash
+## Description: Run unit tests
+## Usage: test-unit [args]
+
+.Build/bin/phpunit -c Build/phpunit/UnitTests.xml "$@"
+```
+
+**`.ddev/commands/web/test-functional`:**
+
+```bash
+#!/bin/bash
+## Description: Run functional tests
+## Usage: test-functional [args]
+
+.Build/bin/phpunit -c Build/phpunit/FunctionalTests.xml "$@"
+```
+
+## Conformance Evaluation Workflow
+
+### Step 1: Detect Development Environment Type
+
+```bash
+# Check for DDEV
+if [ -f ".ddev/config.yaml" ]; then
+    DEV_ENV="ddev"
+    SCORE=20  # Full points for DDEV
+
+# Check for Docker Compose
+elif [ -f "docker-compose.yml" ]; then
+    DEV_ENV="docker-compose"
+    SCORE=15  # Good, but manual
+
+# Check for DevContainer only
+elif [ -f ".devcontainer/devcontainer.json" ]; then
+    DEV_ENV="devcontainer"
+    SCORE=10  # VS Code specific
+
+# No dev environment
+else
+    DEV_ENV="none"
+    SCORE=0
+fi
+```
+
+### Step 2: Validate Configuration Against Extension
+
+**For DDEV:**
+
+```bash
+# Extract extension requirements
+MIN_PHP=$(jq -r '.require.php' composer.json | grep -oE '[0-9]+\.[0-9]+' | head -1)
+WEB_DIR=$(jq -r '.extra.typo3.cms."web-dir"' composer.json)
+
+# Validate DDEV config
+DDEV_PHP=$(grep 'php_version:' .ddev/config.yaml | awk '{print $2}' | tr -d '"')
+DDEV_DOCROOT=$(grep 'docroot:' .ddev/config.yaml | awk '{print $2}')
+DDEV_TYPE=$(grep 'type:' .ddev/config.yaml | awk '{print $2}')
+
+# Compare
+if [ "${DDEV_PHP}" != "${MIN_PHP}" ]; then
+    echo "⚠️  PHP version mismatch: DDEV ${DDEV_PHP} vs required ${MIN_PHP}"
+fi
+
+if [ "${DDEV_DOCROOT}" != "${WEB_DIR}" ]; then
+    echo "⚠️  Docroot mismatch: DDEV ${DDEV_DOCROOT} vs composer ${WEB_DIR}"
+fi
+
+if [ "${DDEV_TYPE}" != "typo3" ]; then
+    echo "❌ DDEV type should be 'typo3', found '${DDEV_TYPE}'"
+fi
+```
+
+### Step 3: Check for Recommended Enhancements
+
+```bash
+# DDEV commands
+if [ -d ".ddev/commands/web" ]; then
+    COMMANDS=$(ls .ddev/commands/web/ 2>/dev/null | wc -l)
+    echo "✅ DDEV has ${COMMANDS} custom commands"
+else
+    echo "ℹ️  No custom DDEV commands (consider adding typo3, test-unit, test-functional)"
+fi
+
+# TYPO3-specific config
+if [ -f ".ddev/config.typo3.yaml" ]; then
+    echo "✅ TYPO3-specific DDEV configuration present"
+else
+    echo "ℹ️  No TYPO3-specific config (optional)"
+fi
+```
+
+## Conformance Report Integration
+
+### When Evaluating Development Environment:
+
+**In "Best Practices" Section:**
+
+```markdown
+### Development Environment
+
+**Configuration:**
+
+- ✅ DDEV configured (.ddev/config.yaml present)
+- ✅ PHP version matches composer.json minimum (8.2)
+- ✅ Docroot matches composer.json web-dir (.Build/public)
+- ✅ Type set to 'typo3' for TYPO3-optimized setup
+- ✅ MariaDB 10.11 (LTS) configured
+- ✅ Custom DDEV commands for testing (test-unit, test-functional)
+- ℹ️  Optional: TYPO3-specific config (.ddev/config.typo3.yaml) could enhance setup
+
+**Or with issues:**
+
+- ❌ No development environment configuration
+  - Missing: .ddev/config.yaml, docker-compose.yml
+  - Impact: Inconsistent development environments, difficult onboarding
+  - Severity: Medium
+  - Recommendation: Add DDEV configuration from Tea extension pattern
+  - Reference: https://github.com/TYPO3BestPractices/tea/tree/main/.ddev
+
+- ⚠️  DDEV PHP version mismatch
+  - File: .ddev/config.yaml
+  - Current: php_version: "7.4"
+  - Expected: php_version: "8.2" (from composer.json)
+  - Severity: High
+  - Fix: Update php_version to match minimum requirement
+
+- ⚠️  DDEV docroot mismatch
+  - File: .ddev/config.yaml
+  - Current: docroot: public
+  - Expected: docroot: .Build/public (from composer.json extra.typo3.cms.web-dir)
+  - Severity: High
+  - Fix: Update docroot to match web-dir
+```
+
+## Scoring Impact
+
+**Best Practices Score Components (out of 20):**
+
+| Component | Max Points | DDEV | Docker Compose | None |
+|-----------|-----------|------|----------------|------|
+| **Dev Environment Exists** | 6 | 6 | 4 | 0 |
+| **Configuration Correct** | 4 | 4 | 3 | 0 |
+| **Version Matching** | 3 | 3 | 2 | 0 |
+| **Documentation** | 2 | 2 | 1 | 0 |
+| **Custom Commands/Enhancements** | 2 | 2 | 0 | 0 |
+| **Other Best Practices** | 3 | 3 | 3 | 3 |
+| **Total** | 20 | 20 | 13 | 3 |
+
+**Deductions:**
+
+| Issue | Severity | Score Impact |
+|-------|----------|--------------|
+| No dev environment at all | High | -6 points |
+| PHP version mismatch | High | -3 points |
+| Docroot mismatch | High | -3 points |
+| Wrong type (not 'typo3') | Medium | -2 points |
+| Missing custom commands | Low | -1 point |
+| No documentation | Low | -1 point |
+
+## Tea Extension Reference
+
+**Source:** https://github.com/TYPO3BestPractices/tea/tree/main/.ddev
+
+**Tea DDEV Structure:**
+
+```
+.ddev/
+├── .gitignore
+├── config.yaml              # Main configuration
+├── config.typo3.yaml        # TYPO3-specific settings
+└── commands/
+    └── web/
+        ├── typo3            # TYPO3 CLI wrapper
+        ├── test-unit        # Run unit tests
+        └── test-functional  # Run functional tests
+```
+
+**Tea config.yaml (simplified):**
+
+```yaml
+name: tea
+type: typo3
+docroot: .Build/public
+php_version: "8.2"
+webserver_type: nginx-fpm
+database:
+  type: mariadb
+  version: "10.11"
+xdebug_enabled: false
+```
+
+**Usage Examples:**
+
+```bash
+# Start DDEV
+ddev start
+
+# Install dependencies
+ddev composer install
+
+# Run TYPO3 CLI
+ddev typo3 cache:flush
+
+# Run unit tests
+ddev test-unit
+
+# Run functional tests
+ddev test-functional
+
+# Access database
+ddev mysql
+
+# SSH into container
+ddev ssh
+```
+
+## Quick Reference Checklist
+
+**When evaluating development environment:**
+
+```
+□ .ddev/config.yaml exists (preferred)
+□ OR docker-compose.yml exists (acceptable)
+□ OR .devcontainer/devcontainer.json exists (VS Code only)
+□ Configuration type is 'typo3' (DDEV) or uses TYPO3 image (Docker Compose)
+□ PHP version matches composer.json minimum
+□ Docroot matches composer.json web-dir
+□ Database is MariaDB 10.11+ or MySQL 8.0+
+□ Custom commands for common tasks (DDEV)
+□ Documentation exists (README.md mentions DDEV/Docker setup)
+□ .ddev/.gitignore present (excludes dynamic files)
+□ Post-start hooks run composer install (optional but nice)
+```
+
+## Common Issues
+
+### Issue: Empty .devcontainer/
+
+**Diagnosis:**
+```bash
+ls -la .devcontainer/
+# total 8
+# drwxr-sr-x  2 user user 4096 Oct 20 20:05 .
+```
+
+**Severity:** 🟢 Low (incomplete setup, doesn't help or hurt)
+
+**Fix:** Either populate with devcontainer.json or remove directory
+
+### Issue: DDEV but no .gitignore
+
+**Diagnosis:**
+```bash
+ls -la .ddev/.gitignore
+# No such file or directory
+```
+
+**Problem:** DDEV generates dynamic files that shouldn't be committed
+
+**Fix:** Create `.ddev/.gitignore`:
+```
+/*.yaml
+.ddev-docker-compose-*.yaml
+.homeadditions
+.sshimagename
+commands/web/.ddev-docker-compose-*.yaml
+import-db/
+```
+
+### Issue: Wrong DDEV project type
+
+**Diagnosis:**
+```yaml
+# .ddev/config.yaml
+type: php  # ❌ Wrong
+```
+
+**Problem:** Misses TYPO3-specific optimizations (URL structure, etc.)
+
+**Fix:** Change to `type: typo3`
+
+## Resources
+
+- **DDEV Documentation:** https://ddev.readthedocs.io/
+- **DDEV TYPO3 Quickstart:** https://ddev.readthedocs.io/en/stable/users/quickstart/#typo3
+- **Tea Extension DDEV Setup:** https://github.com/TYPO3BestPractices/tea/tree/main/.ddev
+- **TYPO3 Docker Documentation:** https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/LocalDevelopment/