From c226654c62b63badde4075a674574e5c57401988 Mon Sep 17 00:00:00 2001 From: Alex Skrypnyk Date: Fri, 6 Feb 2026 14:12:32 +1100 Subject: [PATCH] Refactored documentation to make it AI and human friendly. --- .env | 8 +- .env.local.example | 2 +- .vortex/.ahoy.yml | 13 + .vortex/CLAUDE.md | 1612 +---------------- .vortex/docs/.utils/update-docs.sh | 2 +- .../variables/extra/acquia.variables.sh | 10 +- .../variables/extra/lagoon.variables.sh | 10 +- .vortex/docs/CLAUDE.md | 60 + .vortex/docs/content/README.mdx | 2 +- .../{workflows => }/_code-lifecycle.mdx | 0 .vortex/docs/content/architecture.mdx | 28 +- .../content/continuous-integration/README.mdx | 6 +- .../continuous-integration/circleci.mdx | 4 +- .../continuous-integration/github-actions.mdx | 4 +- .../maintenance/documentation.mdx | 43 +- .../contributing/maintenance/release.mdx | 2 +- .../contributing/maintenance/scripts.mdx | 16 +- .../contributing/maintenance/tests.mdx | 52 +- .../deployment.mdx => deployment/README.mdx} | 37 +- .vortex/docs/content/deployment/artifact.mdx | 90 + .vortex/docs/content/deployment/docker.mdx | 81 + .vortex/docs/content/deployment/lagoon.mdx | 75 + .../docs/content/deployment/notifications.mdx | 258 +++ .vortex/docs/content/deployment/webhook.mdx | 44 + .vortex/docs/content/development/README.mdx | 283 +++ .../testing.mdx => development/behat.mdx} | 149 +- .../composer.mdx} | 421 +++-- .vortex/docs/content/development/database.mdx | 98 + .../xdebug.mdx => development/debugging.mdx} | 102 +- .vortex/docs/content/development/faqs.mdx | 300 +++ .vortex/docs/content/development/phpunit.mdx | 134 ++ .../{workflows => development}/variables.mdx | 26 +- .../{composer.mdx => composer-json.mdx} | 100 +- .../docs/content/drupal/module-scaffold.mdx | 2 +- .vortex/docs/content/drupal/provision.mdx | 12 +- .vortex/docs/content/drupal/settings.mdx | 4 +- .../docs/content/drupal/theme-scaffold.mdx | 12 +- .vortex/docs/content/drupal/update-hooks.mdx | 2 +- .vortex/docs/content/faqs.mdx | 4 +- .vortex/docs/content/features.mdx | 16 +- .vortex/docs/content/hosting/README.mdx | 2 +- .vortex/docs/content/hosting/acquia.mdx | 2 +- .vortex/docs/content/hosting/lagoon.mdx | 2 +- .vortex/docs/content/installation.mdx | 2 +- .vortex/docs/content/releasing/README.mdx | 132 ++ .vortex/docs/content/releasing/gitflow.mdx | 121 ++ .vortex/docs/content/releasing/versioning.mdx | 75 + .vortex/docs/content/support.mdx | 2 +- .vortex/docs/content/tools/README.mdx | 1 - .vortex/docs/content/tools/ahoy.mdx | 4 +- .vortex/docs/content/tools/docker.mdx | 4 +- .vortex/docs/content/tools/drush.mdx | 4 +- .vortex/docs/content/tools/rector.mdx | 2 +- .../{workflows => }/updating-vortex.mdx | 8 +- .vortex/docs/content/workflows/README.mdx | 34 - .../docs/content/workflows/notifications.mdx | 365 ---- .vortex/docs/content/workflows/releasing.mdx | 313 ---- .vortex/docs/cspell.json | 1 + .vortex/docs/docusaurus.config.js | 108 ++ .vortex/docs/sidebars.js | 32 +- .vortex/installer/CLAUDE.md | 121 ++ .../installer/src/Prompts/Handlers/Tools.php | 30 + .../Fixtures/handler_process/_baseline/.env | 8 +- .../handler_process/_baseline/.env.local | 2 +- .../_baseline/.env.local.example | 2 +- .../handler_process/_baseline/CLAUDE.md | 929 +--------- .../handler_process/_baseline/docs/README.md | 16 +- .../handler_process/_baseline/docs/ci.md | 31 +- .../_baseline/docs/deployment.md | 20 +- .../handler_process/_baseline/docs/faqs.md | 168 +- .../_baseline/docs/releasing.md | 31 +- .../handler_process/_baseline/docs/testing.md | 226 ++- .../ciprovider_circleci/CLAUDE.md | 9 - .../ciprovider_circleci/docs/ci.md | 35 +- .../deploy_types_all_circleci/.env | 2 +- .../deploy_types_all_circleci/CLAUDE.md | 9 - .../deploy_types_all_circleci/docs/ci.md | 35 +- .../handler_process/deploy_types_all_gha/.env | 2 +- .../deploy_types_artifact/.env | 2 +- .../deploy_types_container_image/.env | 2 +- .../handler_process/deploy_types_lagoon/.env | 2 +- .../deploy_types_none_circleci/.env | 2 +- .../deploy_types_none_circleci/CLAUDE.md | 9 - .../deploy_types_none_circleci/docs/ci.md | 35 +- .../deploy_types_none_gha/.env | 2 +- .../CLAUDE.md | 9 - .../docs/ci.md | 35 +- .../handler_process/hosting_acquia/.env | 2 +- .../handler_process/hosting_acquia/CLAUDE.md | 52 +- .../hosting_acquia/docs/deployment.md | 95 +- .../handler_process/hosting_lagoon/.env | 2 +- .../handler_process/hosting_lagoon/CLAUDE.md | 9 - .../hosting_lagoon/docs/deployment.md | 21 +- .../hosting_project_name___acquia/.env | 2 +- .../hosting_project_name___acquia/CLAUDE.md | 52 +- .../docs/deployment.md | 95 +- .../hosting_project_name___lagoon/.env | 2 +- .../hosting_project_name___lagoon/CLAUDE.md | 9 - .../docs/deployment.md | 21 +- .../Fixtures/handler_process/names/CLAUDE.md | 6 + .../non_interactive_config_file/CLAUDE.md | 20 - .../non_interactive_config_string/CLAUDE.md | 20 - .../provision_database_lagoon/.env | 2 +- .../provision_database_lagoon/CLAUDE.md | 9 - .../docs/deployment.md | 21 +- .../services_no_clamav/CLAUDE.md | 20 - .../services_no_redis/CLAUDE.md | 20 - .../services_no_solr/CLAUDE.md | 24 - .../handler_process/services_none/CLAUDE.md | 50 - .../handler_process/theme_claro/CLAUDE.md | 49 - .../handler_process/theme_olivero/CLAUDE.md | 49 - .../handler_process/theme_stark/CLAUDE.md | 49 - .../timezone_circleci/CLAUDE.md | 9 - .../timezone_circleci/docs/ci.md | 35 +- .../CLAUDE.md | 9 - .../docs/ci.md | 35 +- .../tools_groups_no_be_tests/CLAUDE.md | 163 +- .../tools_groups_no_be_tests/docs/faqs.md | 29 - .../tools_groups_no_be_tests/docs/testing.md | 227 +++ .../CLAUDE.md | 172 +- .../docs/ci.md | 35 +- .../docs/faqs.md | 29 - .../docs/testing.md | 227 +++ .../handler_process/tools_no_behat/CLAUDE.md | 143 +- .../tools_no_behat/docs/faqs.md | 29 - .../tools_no_behat/docs/testing.md | 94 + .../tools_no_behat_circleci/CLAUDE.md | 152 +- .../tools_no_behat_circleci/docs/ci.md | 35 +- .../tools_no_behat_circleci/docs/faqs.md | 29 - .../tools_no_behat_circleci/docs/testing.md | 94 + .../tools_no_phpcs_circleci/CLAUDE.md | 9 - .../tools_no_phpcs_circleci/docs/ci.md | 35 +- .../tools_no_phpmd_circleci/CLAUDE.md | 9 - .../tools_no_phpmd_circleci/docs/ci.md | 35 +- .../tools_no_phpstan_circleci/CLAUDE.md | 9 - .../tools_no_phpstan_circleci/docs/ci.md | 35 +- .../tools_no_phpunit/CLAUDE.md | 38 +- .../tools_no_phpunit/docs/testing.md | 140 ++ .../tools_no_phpunit_circleci/CLAUDE.md | 49 +- .../tools_no_phpunit_circleci/docs/ci.md | 35 +- .../tools_no_phpunit_circleci/docs/testing.md | 140 ++ .../tools_no_rector_circleci/CLAUDE.md | 9 - .../tools_no_rector_circleci/docs/ci.md | 35 +- .../handler_process/tools_none/CLAUDE.md | 163 +- .../handler_process/tools_none/docs/faqs.md | 29 - .../tools_none/docs/testing.md | 227 +++ .../handler_process/version_scheme_other/.env | 2 +- .../version_scheme_other/docs/releasing.md | 24 +- .../version_scheme_semver/.env | 2 +- .../version_scheme_semver/docs/releasing.md | 31 +- .vortex/tests/.markdownlint.yaml | 3 + .vortex/tests/CLAUDE.md | 154 ++ CLAUDE.md | 1003 +--------- README.md | 2 +- docs/README.md | 16 +- docs/ci.md | 55 +- docs/deployment.md | 134 +- docs/faqs.md | 176 +- docs/releasing.md | 50 +- docs/testing.md | 234 ++- scripts/vortex/notify-jira.sh | 2 +- scripts/vortex/notify-newrelic.sh | 2 +- scripts/vortex/notify-slack.sh | 2 +- 163 files changed, 5071 insertions(+), 7177 deletions(-) create mode 100644 .vortex/docs/CLAUDE.md rename .vortex/docs/content/{workflows => }/_code-lifecycle.mdx (100%) rename .vortex/docs/content/{workflows/deployment.mdx => deployment/README.mdx} (78%) create mode 100644 .vortex/docs/content/deployment/artifact.mdx create mode 100644 .vortex/docs/content/deployment/docker.mdx create mode 100644 .vortex/docs/content/deployment/lagoon.mdx create mode 100644 .vortex/docs/content/deployment/notifications.mdx create mode 100644 .vortex/docs/content/deployment/webhook.mdx create mode 100644 .vortex/docs/content/development/README.mdx rename .vortex/docs/content/{workflows/testing.mdx => development/behat.mdx} (56%) rename .vortex/docs/content/{workflows/development.mdx => development/composer.mdx} (56%) create mode 100644 .vortex/docs/content/development/database.mdx rename .vortex/docs/content/{tools/xdebug.mdx => development/debugging.mdx} (54%) create mode 100644 .vortex/docs/content/development/faqs.mdx create mode 100644 .vortex/docs/content/development/phpunit.mdx rename .vortex/docs/content/{workflows => development}/variables.mdx (99%) rename .vortex/docs/content/drupal/{composer.mdx => composer-json.mdx} (97%) create mode 100644 .vortex/docs/content/releasing/README.mdx create mode 100644 .vortex/docs/content/releasing/gitflow.mdx create mode 100644 .vortex/docs/content/releasing/versioning.mdx rename .vortex/docs/content/{workflows => }/updating-vortex.mdx (95%) delete mode 100644 .vortex/docs/content/workflows/README.mdx delete mode 100644 .vortex/docs/content/workflows/notifications.mdx delete mode 100644 .vortex/docs/content/workflows/releasing.mdx create mode 100644 .vortex/installer/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/ciprovider_circleci/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/deploy_types_all_circleci/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/deploy_types_none_circleci/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/deps_updates_provider_ci_circleci/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/hosting_lagoon/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/hosting_project_name___lagoon/CLAUDE.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/names/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/non_interactive_config_file/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/non_interactive_config_string/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/provision_database_lagoon/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/services_no_clamav/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/services_no_redis/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/services_no_solr/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/services_none/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/theme_claro/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/theme_olivero/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/theme_stark/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/timezone_circleci/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_lint_circleci/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/docs/faqs.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/docs/testing.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/docs/faqs.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/docs/testing.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_no_behat/docs/faqs.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_no_behat/docs/testing.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/docs/faqs.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/docs/testing.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_no_phpcs_circleci/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_no_phpmd_circleci/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_no_phpstan_circleci/CLAUDE.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit/docs/testing.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/docs/testing.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_no_rector_circleci/CLAUDE.md delete mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_none/docs/faqs.md create mode 100644 .vortex/installer/tests/Fixtures/handler_process/tools_none/docs/testing.md create mode 100644 .vortex/tests/CLAUDE.md diff --git a/.env b/.env index 2aa6c3cbd..8ea8a315d 100644 --- a/.env +++ b/.env @@ -15,7 +15,7 @@ # To customize variables locally, copy `.env.local.example` to `.env.local`, # and add your custom values there. # -# @see https://www.vortextemplate.com/docs/workflows/variables +# @see https://www.vortextemplate.com/docs/development/variables ################################################################################ # GENERAL # @@ -223,7 +223,7 @@ VORTEX_DB_DOWNLOAD_ACQUIA_DB_NAME=your_site # Versioning scheme used for releases. # # Can be one of: calver, semver, other -# @see https://www.vortextemplate.com/docs/workflows/releasing +# @see https://www.vortextemplate.com/docs/releasing VORTEX_RELEASE_VERSION_SCHEME=calver #;< DEPLOYMENT @@ -232,7 +232,7 @@ VORTEX_RELEASE_VERSION_SCHEME=calver ################################################################################ # Deployment occurs when tests pass in the CI environment. -# @see https://www.vortextemplate.com/docs/workflows/deployment +# @see https://www.vortextemplate.com/docs/deployment VORTEX_DEPLOY_TYPES=artifact #;> DEPLOYMENT @@ -242,7 +242,7 @@ VORTEX_DEPLOY_TYPES=artifact ################################################################################ # Notificaions are sent accross multiple channels before and after deployment. -# @see https://www.vortextemplate.com/docs/workflows/notifications +# @see https://www.vortextemplate.com/docs/deployment/notifications # The channels of the notifications. # diff --git a/.env.local.example b/.env.local.example index fd7b8cf42..5c47da89e 100644 --- a/.env.local.example +++ b/.env.local.example @@ -6,7 +6,7 @@ # # The .env.local file is excluded via .gitignore and will not be committed. # -# @see https://www.vortextemplate.com/docs/workflows/variables +# @see https://www.vortextemplate.com/docs/development/variables # Local development URL. # Override only if you need to use a different URL than the default. diff --git a/.vortex/.ahoy.yml b/.vortex/.ahoy.yml index 2a0a7353b..1e4ea3c6f 100644 --- a/.vortex/.ahoy.yml +++ b/.vortex/.ahoy.yml @@ -48,9 +48,19 @@ commands: ahoy lint-docs ahoy lint-markdown + lint-fix: + name: Fix linting issues in Vortex project. + cmd: | + ahoy lint-installer-fix + ahoy lint-docs-fix + ahoy lint-markdown-fix + lint-installer: cmd: composer --working-dir installer lint + lint-installer-fix: + cmd: composer --working-dir installer lint-fix + lint-scripts: cmd: ./tests/lint.scripts.sh @@ -68,6 +78,9 @@ commands: yarn --cwd=docs run lint yarn --cwd=./docs run spellcheck + lint-docs-fix: + cmd: yarn --cwd=docs run lint-fix + test: name: Test Vortex project. cmd: | diff --git a/.vortex/CLAUDE.md b/.vortex/CLAUDE.md index 0df1890ac..ef4b388cf 100644 --- a/.vortex/CLAUDE.md +++ b/.vortex/CLAUDE.md @@ -1,1591 +1,87 @@ # Vortex Template Maintenance Guide -> **⚠️ MAINTENANCE MODE**: This file contains guidance for **maintaining the Vortex template itself**. -> -> For working with **Drupal projects created from this template**, see the main project guide: `../CLAUDE.md` +> **⚠️ MAINTENANCE MODE**: For **maintaining the Vortex template itself**. +> For **Drupal projects**, see `../CLAUDE.md` -## Project Overview - -**Vortex** is a Drupal project template by DrevOps that provides a comprehensive, production-ready Drupal development and deployment framework. - -### Project Structure +## Project Structure ```text vortex/ -├── .vortex/ # Test harness and development tools -│ ├── docs/ # Documentation for Vortex -│ ├── installer/ # Self-contained Symfony console installer -│ ├── tests/ # Unit and functional tests -│ └── CLAUDE.md # This maintenance guide +├── .vortex/ # Test harness (removed on install) +│ ├── docs/ # Documentation website +│ ├── installer/ # Template installer +│ └── tests/ # Template tests └── [root files] # The actual Drupal template - └── CLAUDE.md # Drupal development guide -``` - -**Key Principle**: Everything outside `.vortex/` is the **actual template** that gets installed for users. Everything inside `.vortex/` is the **test harness** used to test and maintain the template. - -## .vortex Directory Structure - -The `.vortex/` directory contains **three distinct subsystems**, each with its own purpose and technology stack: - -### 1. .vortex/docs/ - Documentation Website - -**Purpose**: Public-facing documentation website for Vortex users - -**Technology Stack**: - -- **Docusaurus** - Static site generator with React -- **MDX** - Markdown with React components -- **Jest** - Unit testing framework -- **ESLint/Prettier** - Code quality tools -- **cspell** - American English spellcheck validation - -**Key Features**: - -- Interactive documentation with custom React components -- Published to https://www.vortextemplate.com -- Comprehensive testing (unit tests, spellcheck, linting) -- Multi-format content system with enhanced UX - -**Commands** (from `.vortex/docs/`): - -```bash -yarn install # Install dependencies -yarn start # Development server -yarn build # Production build -yarn test # Run all tests -yarn spellcheck # Validate spelling -``` - -### 2. .vortex/installer/ - Template Installer - -**Purpose**: Self-contained installation system that customizes the Vortex template based on user selections - -**Technology Stack**: - -- **Symfony Console** - Command-line application framework -- **PHP** - Core programming language -- **PHPUnit** - Testing framework for installer logic - -**Key Features**: - -- Interactive installation wizard -- Conditional token system for template customization -- Baseline + diff fixture architecture for testing -- Handles all user prompts and template modifications - -**Architecture**: - -- `src/` - Installer source code (handlers, prompts, utilities) -- `tests/Fixtures/` - Test fixtures with baseline + scenario diffs -- `tests/Functional/` - PHPUnit tests for installation scenarios - -**Commands** (from `.vortex/installer/`): - -```bash -composer install # Install dependencies -./vendor/bin/phpunit # Run installer tests -UPDATE_SNAPSHOTS=1 composer test # Update test snapshots -``` - -### 3. .vortex/tests/ - Template Testing Harness - -**Purpose**: Comprehensive testing of the Vortex template itself through functional workflows - -**Technology Stack**: - -- **PHPUnit** - Functional testing of complete Drupal project workflows -- **BATS** - Unit testing of individual shell scripts -- **Bash** - Shell script testing and execution - -**Key Features**: - -- End-to-end workflow testing (build, provision, deploy) -- Shell script unit testing with mocking capabilities -- Real Docker container testing environment -- Coverage reporting and performance testing - -**Architecture**: - -- `phpunit/` - Functional tests for complete workflows -- `bats/` - Unit tests for individual shell scripts -- `bats/fixtures/` - Test fixtures and mock data -- `manual/` - Manual integration tests with real external services - -**Commands** (from `.vortex/`): - -```bash -ahoy install # Install all dependencies -ahoy test-bats -- tests/bats/ # Run BATS shell script tests -cd tests && ./vendor/bin/phpunit # Run PHPUnit workflow tests -``` - -## Testing Architecture Overview - -Vortex uses **four independent testing systems**, each serving different parts of the codebase: - -### 1. Documentation Tests (.vortex/docs/) - -**Scope**: Testing the documentation website components and content - -**Technology**: Jest + React Testing Library + cspell - -**What it Tests**: - -- React component functionality and interactions -- MDX content rendering and navigation -- American English spelling consistency -- Documentation build processes - -**Test Types**: - -- **Unit tests**: Component behavior (`tests/unit/`) -- **Spellcheck**: Content validation (`cspell.json`) -- **Coverage reporting**: Multiple formats (text, lcov, HTML, Cobertura) - -### 2. Installer Tests (.vortex/installer/) - -**Scope**: Testing the template installation and customization logic - -**Technology**: PHPUnit + Fixture System - -**What it Tests**: - -- User prompt handling and validation -- Template file modifications and token replacement -- Installation scenario outcomes -- Baseline vs customized template differences - -**Test Types**: - -- **Functional tests**: Complete installation scenarios -- **Handler tests**: Individual prompt and modification logic -- **Fixture tests**: Expected vs actual template output - -### 3. Template Tests (.vortex/tests/) - -**Scope**: Testing the actual Drupal template functionality - -**Technology**: PHPUnit + BATS - -**What it Tests**: - -- Complete Drupal project workflows (build, provision, deploy) -- Individual shell script functionality -- Docker container interactions -- Real-world usage scenarios - -**Test Types**: - -- **PHPUnit Functional**: End-to-end workflow testing -- **BATS Unit**: Individual shell script testing with mocking - -### 4. Manual Integration Tests (.vortex/tests/manual/) - -**Scope**: Manual verification of notification integrations with real external services - -**Technology**: Bash scripts + Real service APIs (Slack, JIRA, etc.) - -**What it Tests**: - -- Actual notification message formatting in live services -- Real API authentication and authorization -- Service-specific rendering (Slack rich attachments, JIRA ADF) -- End-to-end integration workflows (comment posting, issue transitions) - -**Test Types**: - -- **Manual Slack Tests**: Branch and PR deployment notifications to real Slack channels -- **Manual JIRA Tests**: Comment creation, transitions, and assignments on real JIRA issues -- **Authentication Verification**: API token validation and permission checks - -**Key Difference**: These tests use REAL services (not mocks) and require manual verification of output, complementing automated tests by validating actual service integration and message appearance. - -## Template BATS Testing System (.vortex/tests/bats/) - -### Overview - -**BATS (Bash Automated Testing System)** provides unit testing for individual shell scripts with sophisticated mocking and assertion capabilities. - -**Key Files**: - -- `provision.bats` - Tests for provision.sh script -- `_helper.bash` - Test helper functions -- `fixtures/` - Test fixture files -- `unit/` - Individual script unit tests - -### BATS Helpers System - -The BATS tests use a sophisticated helper system located in `node_modules/bats-helpers/src/steps.bash` that provides: - -**Step Types**: - -1. **Command Mocking**: `@ [] # [ # ]` - - Mocks shell commands with specific exit codes and output - - Example: `"@drush -y status --field=drupal-version # mocked_core_version"` - -2. **Positive Assertions**: `""` - - Asserts that output CONTAINS the specified substring - - Example: `"Fresh database detected. Performing additional example operations."` - -3. **Negative Assertions**: `"- "` - - Asserts that output does NOT contain the specified substring - - Starts with '- ' (minus followed by space) - - Example: `"- Existing database detected. Performing additional example operations."` - -**Usage Pattern**: - -```bash -declare -a STEPS=( - "@drush -y status # 0 # success" # Mock command - "Expected output string" # Should be present - "- Unwanted output string" # Should NOT be present -) - -mocks="$(run_steps "setup")" # Setup phase -# ... run code under test ... -run_steps "assert" "${mocks}" # Assert phase -``` - -## Running Tests by System - -### 1. Documentation Tests (.vortex/docs/) - -**Purpose**: Test documentation website functionality - -```bash -cd .vortex/docs - -# Install dependencies -yarn install - -# Development workflow -yarn start # Start dev server -yarn build # Build documentation - -# Testing workflow -yarn test # Run all tests -yarn test:coverage # Run with coverage -yarn test:watch # Watch mode for development - -# Quality assurance -yarn spellcheck # American English validation -yarn lint # Code quality checks -yarn lint-fix # Auto-fix code quality issues -``` - -### 2. Installer Tests (.vortex/installer/) - -**Purpose**: Test template installation scenarios - -```bash -cd .vortex/installer - -# Install dependencies -composer install - -# Run all installer tests -./vendor/bin/phpunit - -# Update test fixtures -UPDATE_SNAPSHOTS=1 composer test - -# Run specific scenarios -UPDATE_SNAPSHOTS=1 ./vendor/bin/phpunit --filter "testHandlerProcess.*baseline" -UPDATE_SNAPSHOTS=1 ./vendor/bin/phpunit --filter 'testHandlerProcess.*"services.*no.*clamav"' - -# Run handler-specific tests -./vendor/bin/phpunit --filter "Handlers\\\\" -./vendor/bin/phpunit --filter "ServicesHandlerProcessTest" -``` - -### 3. Template Tests (.vortex/tests/) - -**Purpose**: Test the actual Drupal template functionality - -```bash -cd .vortex - -# Install all dependencies (PHP, Node.js, BATS) -ahoy install - -# PHPUnit functional tests (workflow testing) -cd tests && ./vendor/bin/phpunit - -# BATS unit tests (shell script testing) -ahoy test-bats -- tests/bats/unit/notify.bats # Specific test file -ahoy test-bats -- tests/bats/provision.bats # Another test file -ahoy test-bats -- --verbose-run tests/bats/unit/ # Verbose output for directory -ahoy test-bats -- tests/bats/ # All BATS tests - -# Alternative: direct bats command (after ahoy install) -bats tests/bats/unit/notify.bats - -# Individual test suites -./test.common.sh # Common tests -./test.deployment.sh # Deployment tests -./test.workflow.sh # Workflow tests -./lint.scripts.sh # Shell script linting -``` - -### 4. Manual Integration Tests (.vortex/tests/manual/) - -**Purpose**: Manually verify notification integrations with real external services - -**Technology**: Bash scripts that invoke actual notification endpoints - -**What to Test**: - -- Real Slack webhook message formatting and delivery -- JIRA comment creation, issue transitions, and assignments -- Actual service API authentication and responses - -**Available Scripts**: - -```bash -# Slack notifications (requires SLACK_WEBHOOK_URL) -export SLACK_WEBHOOK_URL="your-webhook-url" -.vortex/tests/manual/try-slack-notification.sh branch # Test branch deployment -.vortex/tests/manual/try-slack-notification.sh pr # Test PR deployment - -# JIRA notifications (requires JIRA_TOKEN) -export JIRA_TOKEN="your-api-token" -export JIRA_USER="your-email@example.com" # Optional (default: alex@drevops.com) -export JIRA_ENDPOINT="https://your-domain.atlassian.net" # Optional (default: https://drevops.atlassian.net) -export JIRA_ISSUE="PROJECT-123" # Optional (default: DEMO-2) -.vortex/tests/manual/try-jira-notification.sh branch # Test branch deployment -.vortex/tests/manual/try-jira-notification.sh pr # Test PR deployment - -# JIRA authentication test (requires JIRA_TOKEN) -export JIRA_TOKEN="your-api-token" -.vortex/tests/manual/try-jira-auth.sh # Verify JIRA API access ``` -**When to Use**: +**Key Principle**: Outside `.vortex/` = template for users. Inside `.vortex/` = +test harness. -- During notification script refactoring to verify real output formatting -- Before committing major notification changes -- To debug integration issues with external services -- After API updates to test compatibility +## Subsystems -**Important Notes**: +| System | Technology | Purpose | +|--------------|--------------------------|------------------------| +| `docs/` | Docusaurus, Jest | vortextemplate.com | +| `installer/` | Symfony Console, PHPUnit | Template customization | +| `tests/` | PHPUnit, BATS | Template testing | -- ⚠️ These send REAL notifications to live services (use test channels/projects) -- 🔐 Never commit credentials to version control -- 📚 See `.vortex/tests/manual/README.md` for comprehensive documentation -- 🧪 Manual tests complement automated BATS tests (real services vs mocks) +Each has its own CLAUDE.md with detailed guidance. Read when working on that +subsystem: -## Installer Fixture System +- `.vortex/docs/CLAUDE.md` - Documentation system +- `.vortex/installer/CLAUDE.md` - Installer, fixtures, tokens +- `.vortex/tests/CLAUDE.md` - BATS, PHPUnit, shell scripts -### Architecture - -The installer uses a **baseline + diff** system for managing test fixtures: - -1. **Baseline** (`_baseline/`): Complete template files -2. **Scenario Fixtures**: Diff files that modify the baseline - -### Fixture Locations - -```text -.vortex/installer/tests/Fixtures/install/ -├── _baseline/ # Complete template files -├── services_no_clamav/ # Diff: removes ClamAV-related content -├── services_no_solr/ # Diff: removes Solr-related content -├── services_no_redis/ # Diff: removes Redis content -├── services_none/ # Diff: removes all services -├── hosting_acquia/ # Diff: Acquia-specific modifications -├── hosting_lagoon/ # Diff: Lagoon-specific modifications -└── [other scenarios]/ # Various configuration scenarios -``` - -### Updating Fixtures - -**CRITICAL - Use the Unified Ahoy Command**: - -The correct way to update fixtures is to use the unified `ahoy update-snapshots` command from the `.vortex` directory: +## Quick Commands ```bash cd .vortex - -# This is the CORRECT way to update all fixtures -ahoy update-snapshots -``` - -**What this command does**: - -- Updates template test fixtures in `tests/` directory -- Updates installer test fixtures in `installer/` directory -- Handles baseline fixtures first -- Updates all scenario-specific fixtures -- Runs tests twice to properly handle fixture updates (first run may fail, second should pass) - -**DO NOT manually run `UPDATE_SNAPSHOTS=1` commands** - the `ahoy update-snapshots` command handles everything automatically. - -### Alternative: Manual Fixture Updates (Advanced) - -For specific fixture updates or debugging, you can use manual commands: - -```bash -cd .vortex/installer - -# Update specific test fixtures -UPDATE_SNAPSHOTS=1 ./vendor/bin/phpunit --filter "testHandlerProcess.*baseline" -UPDATE_SNAPSHOTS=1 ./vendor/bin/phpunit --filter 'testHandlerProcess.*"services.*no.*clamav"' -``` - -**How it works**: - -1. Tests run and compare actual output vs expected fixtures -2. When `UPDATE_SNAPSHOTS=1` is set, differences automatically update fixtures -3. Baseline changes propagate to all scenario diffs -4. Each scenario maintains only its differences from baseline - -### Fixture Update Process - -1. **Use ahoy update-snapshots**: This is the standard and recommended approach -2. **Alternative - Baseline First**: Update baseline fixtures manually if needed -3. **Alternative - Scenario Diffs**: Run individual scenario tests to update specific diffs -4. **Validation**: Verify tests pass without UPDATE_SNAPSHOTS flag - -## Script Output Formatters - -### Standard Output Formatters - -Vortex uses consistent output formatting across all scripts: - -```bash -# Define in each script -info() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[34m[INFO] %s\033[0m\n" "${1}" || printf "[INFO] %s\n" "${1}"; } -pass() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[32m[ OK ] %s\033[0m\n" "${1}" || printf "[ OK ] %s\n" "${1}"; } -fail() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[31m[FAIL] %s\033[0m\n" "${1}" || printf "[FAIL] %s\n" "${1}"; } - -# For provision scripts, also include: -task() { printf " > %s\n" "${1}"; } -note() { printf " %s\n" "${1}"; } -``` - -### Usage Guidelines - -- **info()**: Main section headers and completion messages -- **pass()**: Success confirmations -- **fail()**: Error messages -- **task()**: Step-by-step operations -- **note()**: Conditional messages, details, hints - -### Example Usage - -```bash -info "Executing example operations in non-production environment." -task "Setting site name." -task "Installing contrib modules." -note "Fresh database detected. Performing additional example operations." -info "Finished executing example operations in non-production environment." -``` - -## Test Maintenance Workflow - -### When Updating Scripts with Output Formatters - -1. **Update Main Script**: Modify the script in the template (outside .vortex/) -2. **Update BATS Tests**: Update test assertions in `.vortex/tests/bats/` -3. **Update Installer Fixtures**: Run `ahoy update-snapshots` from `.vortex/` directory - -### Provision Script BATS Test Logic - -The provision example script (`scripts/custom/provision-10-example.sh`) uses conditional logic: - -```bash -if [ "${VORTEX_PROVISION_OVERRIDE_DB:-0}" = "1" ]; then - note "Fresh database detected. Performing additional example operations." -else - note "Existing database detected. Performing additional example operations." -fi -``` - -**BATS Test Expectations**: - -- **Fresh database scenarios**: Should have "Fresh database detected" and NOT have "Existing database detected" - - `"Provision: DB; no site"` - - `"Provision: DB; existing site; overwrite"` - - `"Provision: DB; no site; configs"` - - `"Provision: profile; no site"` - - `"Provision: profile; existing site; overwrite"` - -- **Existing database scenarios**: Should have "Existing database detected" and NOT have "Fresh database detected" - - `"Provision: DB; existing site"` - - `"Provision: profile; existing site"` - -**Test Pattern**: - -```bash -# Fresh database tests -" Fresh database detected. Performing additional example operations." -"- Existing database detected. Performing additional example operations." - -# Existing database tests -"- Fresh database detected. Performing additional example operations." -"Existing database detected. Performing additional example operations." -``` - -### BATS Test Updates - -When script output changes, update corresponding test files: - -```bash -# Example: provision.bats for provision.sh changes -# Update assertions to match new formatter output: -" ==> Executing example operations in non-production environment." -" > Setting site name." -" > Installing contrib modules." -" Fresh database detected. Performing additional example operations." -``` - -## Cross-System Test Dependencies - -**Important**: Each system has independent dependencies and must be set up separately: - -1. **Documentation** (`.vortex/docs/`): Requires Node.js/Yarn -2. **Installer** (`.vortex/installer/`): Requires PHP/Composer -3. **Template** (`.vortex/tests/`): Requires PHP/Composer + Node.js + BATS - -**Full Setup** (from `.vortex/`): - -```bash -ahoy install # Installs dependencies for all three systems +ahoy install # Install all dependencies +ahoy update-snapshots # Update fixtures (REQUIRES PERMISSION) +ahoy lint-scripts # Lint shell scripts +ahoy update-docs # Regenerate docs from scripts +ahoy lint-markdown # Lint markdown files ``` -## Unified Testing Commands +## Cross-System Workflow -For convenience, you can run tests across all systems: +When updating template scripts: -```bash -# From .vortex/ root -ahoy install # Install all dependencies (docs, installer, template) -ahoy lint # Code linting across all systems -ahoy test # Run all template tests - -# Individual system commands -cd docs && yarn test # Documentation tests only -cd installer && composer test # Installer tests only -cd tests && ./vendor/bin/phpunit # Template PHPUnit tests only -ahoy test-bats -- tests/bats/ # Template BATS tests only -``` +1. Modify script in `scripts/vortex/` or `scripts/custom/` +2. Run `ahoy lint-scripts` +3. Run `ahoy update-docs` +4. Update BATS tests in `.vortex/tests/bats/` +5. Run `ahoy update-snapshots` (requires permission) ## Environment Variables -### Testing - -- `TEST_VORTEX_DEBUG=1` - Enable debug output -- `TEST_NODE_INDEX` - CI runner index for parallel execution -- `VORTEX_DEV_TEST_COVERAGE_DIR` - Coverage output directory -- `UPDATE_SNAPSHOTS=1` - Enable fixture updates during tests - -### Development - -- `VORTEX_DEBUG=1` - Enable debug mode in scripts - -## Conditional Token System - -### Overview - -Vortex uses conditional tokens to strip out content from template files based on user selections during installation. This allows the same template to generate customized projects with only relevant features. - -### Token Patterns - -**Markdown files** (like `README.dist.md`, `CLAUDE.md`): - -```markdown -[//]: # (#;< TOKEN_NAME) -Content that gets removed if user doesn't select this feature -[//]: # (#;> TOKEN_NAME) -``` - -**Shell/YAML files** (like `docker-compose.yml`, shell scripts): - -```bash -#;< TOKEN_NAME -Content that gets removed if user doesn't select this feature -#;> TOKEN_NAME -``` - -### Available Tokens - -**Theme-related**: - -- `DRUPAL_THEME` - Custom theme functionality - -**Services**: - -- `SERVICE_CLAMAV` - ClamAV virus scanning -- `SERVICE_SOLR` - Solr search engine -- `SERVICE_REDIS` - Redis caching - -**CI Providers**: - -- `CI_PROVIDER_GHA` - GitHub Actions -- `CI_PROVIDER_CIRCLECI` - CircleCI -- `CI_PROVIDER_ANY` - Any CI provider selected - -**Hosting Providers**: - -- `HOSTING_LAGOON` - Lagoon hosting -- `HOSTING_ACQUIA` - Acquia hosting - -**Deployment Types**: - -- `DEPLOY_TYPES_CONTAINER_REGISTRY` - Container registry deployments -- `DEPLOY_TYPES_WEBHOOK` - Webhook deployments -- `DEPLOY_TYPES_ARTIFACT` - Artifact deployments - -**Dependencies**: - -- `DEPS_UPDATE_PROVIDER` - Automated dependency updates (RenovateBot) - -**Database**: - -- `!DB_DOWNLOAD_SOURCE_NONE` - Negated token, removes content when NO database download source is selected - -**Provisioning**: - -- `!PROVISION_TYPE_PROFILE` - Negated token for non-profile provision types - -### Token Implementation Locations - -**Handler Classes** (`.vortex/installer/src/Prompts/Handlers/`): - -- `CiProvider.php` - Defines CI_PROVIDER_* tokens -- `HostingProvider.php` - Defines HOSTING_* tokens -- `Services.php` - Defines SERVICE_* tokens -- `Theme.php` - Defines DRUPAL_THEME token -- `DependencyUpdatesProvider.php` - Defines DEPS_UPDATE_PROVIDER token - -**Token Processing** (`.vortex/installer/src/Prompts/Handlers/Internal.php:29`): - -```php -// Remove all conditional tokens during installation -File::removeTokenInDir($this->tmpDir); -``` - -### Using Conditional Tokens - -When creating or updating template files: - -1. **Identify optional features** - What content should only appear for certain configurations? -2. **Wrap with appropriate tokens** - Use the token patterns above -3. **Test with installer** - Verify tokens are properly removed/kept based on user selections -4. **Update both root and fixture files** - Ensure installer tests reflect token usage - -### Example Usage in Template Files - -**Root CLAUDE.md** - Wrapping theme-specific content: - -```markdown -[//]: # (#;< DRUPAL_THEME) - -### Theme Development -Commands and workflows for custom theme development... - -[//]: # (#;> DRUPAL_THEME) -``` - -**docker-compose.yml** - Service-specific containers: - -```yaml -#;< SERVICE_SOLR - solr: - image: solr:8 -#;> SERVICE_SOLR -``` - -### Token Discovery for New Features - -When adding new conditional features: - -1. **Check existing handlers** in `.vortex/installer/src/Prompts/Handlers/` -2. **Look at fixture directories** in `.vortex/installer/tests/Fixtures/install/` -3. **Examine baseline vs scenario diffs** to understand token usage patterns -4. **Follow existing token naming conventions** (UPPERCASE_UNDERSCORE format) - -### Token Testing - -Conditional tokens are tested through the installer fixture system: - -- **Baseline fixtures** contain all possible content -- **Scenario fixtures** show what gets removed for specific configurations -- Use `UPDATE_SNAPSHOTS=1` mechanism to regenerate after token changes - -## Directory Structure Summary - -### Template Structure (Outside .vortex/) - The Actual Drupal Project - -```text -├── scripts/ -│ ├── vortex/ # Core Vortex scripts -│ └── custom/ # Custom project scripts -│ └── provision-10-example.sh # Example provision script -├── tests/ -│ ├── behat/ # Behat tests for the template -│ └── phpunit/ # PHPUnit tests for the template -├── config/ # Drupal configuration -├── web/ # Drupal webroot -├── docker-compose.yml # Docker development environment -├── .ahoy.yml # Ahoy task definitions -├── composer.json # PHP dependencies for Drupal project -└── [other template files] # Complete Drupal project structure -``` - -### Test Harness (.vortex/) - Three Separate Systems +| Variable | Purpose | +|-----------------------|------------------------| +| `VORTEX_DEBUG=1` | Debug mode in scripts | +| `TEST_VORTEX_DEBUG=1` | Debug output in tests | +| `UPDATE_SNAPSHOTS=1` | Enable fixture updates | -**Critical Understanding**: The `.vortex/` directory contains three **completely independent subsystems**: +## AI Assistant Guidelines -1. **`.vortex/docs/`** - Docusaurus website (Node.js/React) -2. **`.vortex/installer/`** - PHP installer application (Symfony Console) -3. **`.vortex/tests/`** - Template testing harness (PHPUnit + BATS) +### Commands Requiring Permission -Each system: - -- Has its own dependencies and package managers -- Serves a different purpose in the Vortex ecosystem -- Can be developed and tested independently -- Has its own command structure and workflows - -### Test Harness (.vortex/) - Three Independent Systems - -```text -├── docs/ # 1. DOCUMENTATION WEBSITE -│ ├── src/components/ # React components (VerticalTabs, etc.) -│ ├── tests/unit/ # Jest tests for React components -│ ├── content/ # MDX documentation content -│ ├── jest.config.js # Jest test configuration -│ ├── cspell.json # Spellcheck configuration -│ ├── package.json # Node.js dependencies -│ └── yarn.lock # Lockfile for docs dependencies -│ -├── installer/ # 2. TEMPLATE INSTALLER -│ ├── src/ # Installer source code (PHP) -│ │ ├── Prompts/Handlers/ # Installation prompt handlers -│ │ └── Utilities/ # Helper classes and utilities -│ ├── tests/Fixtures/ # Installation test fixtures -│ │ ├── _baseline/ # Base template files -│ │ └── [scenarios]/ # Scenario-specific diffs -│ ├── tests/Functional/ # PHPUnit installer tests -│ ├── composer.json # PHP dependencies for installer -│ └── installer.php # Main installer entry point -│ -└── tests/ # 3. TEMPLATE TESTING - ├── bats/ # Shell script unit tests - │ ├── unit/ # Individual script tests - │ ├── fixtures/ # Test fixtures for BATS - │ └── provision.bats # Main provision script tests - ├── phpunit/ # Workflow functional tests - │ ├── Functional/ # End-to-end workflow tests - │ └── Traits/ # Shared test functionality - ├── manual/ # Manual integration tests - │ ├── try-slack-notification.sh # Slack webhook testing - │ ├── try-jira-notification.sh # JIRA API testing - │ ├── try-jira-auth.sh # JIRA authentication testing - │ └── README.md # Manual testing documentation - ├── composer.json # PHP dependencies for template tests - └── [test scripts] # Individual test executables -``` - -## System-Specific Maintenance Guidelines - -### 1. Documentation System (.vortex/docs/) - -**Common Tasks**: - -- Update React components and test with Jest -- Maintain American English spelling consistency -- Keep MDX content synchronized with code changes -- Ensure responsive design across device types - -**Best Practices**: - -- Run spellcheck before committing content changes -- Test interactive components in both development and production builds -- Maintain consistent terminology across all documentation -- **Use sentence case for all headings** - only the first letter is capitalized, except for proper nouns (Vortex, GitHub, Drupal, Docker Compose, CircleCI, etc.) and acronyms (CI/CD, SSH, API, BDD, PHPUnit, etc.) - -### 2. Installer System (.vortex/installer/) - -**Fixture Updates**: - -- **Use `ahoy update-snapshots`** from `.vortex/` directory - this is the standard approach -- The unified command updates all fixtures automatically -- Runs tests twice to handle fixture updates properly (first run may fail, second should pass) -- Be patient - full test suite can take several minutes -- For debugging specific scenarios, manual `UPDATE_SNAPSHOTS=1` commands can be used - -**Handler Development**: - -- Queue operations in handlers, execute centrally in PromptManager -- Use wrapper methods for common file operations -- Test each handler type (token removal, string replacement, custom transformation) -- Maintain execution order dependencies - -### 3. Template Testing System (.vortex/tests/) - -**Script Changes Require Multi-Level Updates**: - -1. **Main script** (template level) -2. **BATS test assertions** (unit test level) -3. **Installer fixtures** (integration test level) - -**Output Formatter Consistency**: - -- Always use the standard formatter functions -- Maintain consistent output patterns across all scripts -- Test changes with both BATS and installer fixture tests - -**PHPUnit Helper Usage**: - -- Use `cmd()` for successful commands with output assertions -- Use `cmdFail()` for expected failures -- Follow prefix rules: all-or-nothing for output assertions -- Prefer named arguments for complex parameters - -**Manual Integration Tests**: - -- Use manual scripts in `.vortex/tests/manual/` when refactoring notification integrations -- Always test with real services before updating automated BATS tests -- Verify message formatting in actual Slack/JIRA UI, not just script output -- Keep credentials in environment variables, never commit to version control -- Use test channels/projects to avoid cluttering production systems - -## System-Specific Troubleshooting - -### 1. Documentation Issues (.vortex/docs/) - -**Common Problems**: - -```bash -# Build failures -yarn build --verbose # Check for detailed build errors - -# Spellcheck failures -yarn spellcheck # Review American English violations -npx cspell "content/**/*.md" # Check specific files - -# Component test failures -yarn test --verbose # Detailed Jest output -yarn test --updateSnapshot # Update component snapshots -``` - -### 2. Installer Issues (.vortex/installer/) - -**Fixture Update Issues**: - -```bash -# RECOMMENDED: Use the unified command -cd .vortex -ahoy update-snapshots - -# ALTERNATIVE: Manual updates for specific scenarios -cd .vortex/installer -UPDATE_SNAPSHOTS=1 ./vendor/bin/phpunit --filter "testHandlerProcess.*baseline" -UPDATE_SNAPSHOTS=1 ./vendor/bin/phpunit --filter 'testHandlerProcess.*"scenario_name"' - -# Check for test timeouts - increase if needed -./vendor/bin/phpunit --timeout=600 -``` - -**Handler Development Issues**: - -- Verify execution order (handlers queue, PromptManager executes) -- Check namespace imports for `ExtendedSplFileInfo` -- Ensure complex logic is preserved in callback signatures - -### 3. Template Testing Issues (.vortex/tests/) - -**BATS Test Failures**: - -- Check output formatting matches script changes -- Verify mock commands and assertions align -- Ensure test fixtures are updated after script modifications - -**PHPUnit Workflow Failures**: - -- Verify Docker containers are running properly -- Check that cmd() prefix rules are followed correctly -- Ensure test environments are properly isolated - -**Performance Characteristics**: - -- **BATS tests**: Fast (unit level, ~seconds) -- **PHPUnit workflow tests**: Slower (integration level, ~minutes) -- **Installer tests**: Slowest (full installation simulation, ~minutes) - -### 4. Manual Integration Test Issues (.vortex/tests/manual/) - -**Missing Credentials**: - -```bash -# Verify environment variables are set -echo $SLACK_WEBHOOK_URL -echo $JIRA_TOKEN - -# If not set, export them -export SLACK_WEBHOOK_URL="your-webhook-url" -export JIRA_TOKEN="your-api-token" -``` - -**Authentication Failures**: - -- Use try-jira-auth.sh to diagnose JIRA authentication issues -- Verify API token has required permissions (comment, transition, assign) -- Check endpoint URL format (https://domain.atlassian.net) -- Ensure token hasn't expired or been revoked - -**Message Format Issues**: - -- Compare actual output in Slack/JIRA with expected format -- Check for JSON encoding issues in JIRA ADF format -- Verify URL formatting (links vs inline cards) -- Test both branch and PR scenarios to catch conditional logic issues - -**Integration Failures**: - -- Confirm services are accessible (not blocked by firewall/VPN) -- Verify webhook URLs are valid and not revoked -- Check issue keys exist and are accessible by user -- Review service-specific rate limits or quotas - -## Shell Script Development Patterns - -### Script Structure Best Practices - -Vortex shell scripts follow a consistent structure for maintainability and clarity: - -**Standard Script Structure**: - -1. **Shebang and header comments** - Script purpose and requirements -2. **Environment loading** - Load `.env` and `.env.local` files -3. **Shell options** - Set `set -eu` and optional debug mode -4. **Variable declarations** - All variables with defaults in one section -5. **Helper functions** - Output formatters and utility functions -6. **Pre-flight checks** - Verify required commands are available -7. **Argument parsing** - Parse command-line arguments (modifies variables) -8. **Main execution** - Core script logic - -**Example Structure**: - -```bash -#!/usr/bin/env bash -## -# Script purpose. -# -# shellcheck disable=SC1090,SC1091 - -# Environment loading. -t=$(mktemp) && export -p >"${t}" && set -a && . ./.env && if [ -f ./.env.local ]; then . ./.env.local; fi && set +a && . "${t}" && rm "${t}" && unset t - -set -eu -[ "${VORTEX_DEBUG-}" = "1" ] && set -x - -# Variable declarations with defaults. -VARIABLE_ONE="${VARIABLE_ONE:-default_value}" -VARIABLE_TWO="${VARIABLE_TWO:-0}" - -# ------------------------------------------------------------------------------ - -# Helper functions. -info() { printf "[INFO] %s\n" "${1}"; } -fail() { printf "[FAIL] %s\n" "${1}"; } - -# Pre-flight checks. -for cmd in required_cmd1 required_cmd2; do command -v "${cmd}" >/dev/null || { - fail "Command ${cmd} is not available" - exit 1 -}; done - -# Parse arguments. -for arg in "$@"; do - if [ "${arg}" = "--flag" ]; then - VARIABLE_TWO=1 - else - VARIABLE_ONE="${arg}" - fi -done - -# ------------------------------------------------------------------------------ - -# Main execution. -# ... script logic here ... -``` - -**Key Principles**: - -- **Keep variable section clean**: Declare all variables with defaults together, don't mix with argument parsing -- **Separate concerns**: Variable declarations → Pre-flight checks → Argument parsing → Execution -- **Consistent ordering**: Maintain the same section order across all scripts -- **Clear boundaries**: Use separator lines (`# ----...`) between major sections - -### Script Development Workflow - -When creating or modifying shell scripts, follow this workflow to ensure code quality and documentation consistency: - -1. **Create/Modify Script**: Make changes to the script in `scripts/vortex/` or `scripts/custom/` -2. **Lint Scripts**: Run `ahoy lint-scripts` from the `.vortex/` directory to check shell script quality -3. **Update Documentation**: Run `ahoy update-docs` from the `.vortex/` directory to regenerate documentation from script variables -4. **Lint Documentation**: Run `ahoy lint-docs` from the `.vortex/` directory to ensure documentation formatting is correct -5. **Lint Markdown Files**: Run `ahoy lint-markdown` from the `.vortex/` directory to check all markdown files for formatting issues - -**Example Workflow**: - -```bash -# After modifying a script, navigate to .vortex directory -cd .vortex - -# Run the quality checks -ahoy lint-scripts # Lint all shell scripts -ahoy update-docs # Update documentation from script variables -ahoy lint-docs # Lint documentation files -ahoy lint-markdown # Lint markdown files (or use ahoy lint-markdown-fix to auto-fix) -``` - -**Important Notes**: - -- **Commands must be run from `.vortex/` directory**: All commands (`lint-scripts`, `update-docs`, `lint-docs`, `lint-markdown`) must be executed from the `.vortex/` directory -- **Scripts must be linted** before committing to ensure they follow shell script best practices -- **Documentation must be updated** whenever script variables or structure changes -- **Documentation must be linted** to maintain consistent formatting across all docs -- **Markdown auto-fix available**: Use `ahoy lint-markdown-fix` to automatically fix markdown formatting issues - -### BATS Testing with Interactive Scripts - -**Critical Understanding**: BATS tests mock shell commands - they don't actually execute them. - -When testing scripts that would normally require user interaction (e.g., running with `--no-interaction` flag omitted): - -**How Mocking Works**: - -```bash -# In BATS test: -create_global_command_wrapper "php" - -# Later in test: -"@php installer.php --uri=https://example.com # 0" -``` - -This creates a mock that: - -- Intercepts calls to `php` command -- Returns immediately with exit code 0 -- Never actually executes the PHP script -- **Does not hang waiting for user input** - -**Implication**: Scripts with interactive modes can be safely tested without hanging, because the test mocks prevent actual execution. - -### Simplicity Over Complexity - -**Lesson**: When implementing new features, start with the simplest solution that works. - -**Example from `update-vortex.sh`**: - -- ✅ **Simple**: Two conditional branches with explicit commands -- ❌ **Complex**: Array building, argument iteration, dynamic construction - -**Why Simpler is Better**: - -- Easier to read and understand -- More predictable behavior -- Better test alignment (argument order is explicit) -- Fewer edge cases to handle -- Faster debugging when issues occur - -**When to Use Complexity**: Only when you need to handle many permutations or truly dynamic argument sets. For simple binary choices (interactive vs non-interactive), conditional execution is clearer. - -## Installer Development Patterns - -### Code Refactoring and Performance Optimization - -**Batch Processing Pattern**: The installer uses batch processing for file operations to improve performance. All file modifications are queued and executed in a single pass through the directory tree. - -**Key Pattern**: - -```php -// Before: Individual operations (slow) -File::replaceContentInFile($file, 'old', 'new'); -File::removeTokenInDir($dir, 'TOKEN'); - -// After: Batched operations (fast) -File::replaceContentAsync('old', 'new'); -File::replaceTokenAsync('TOKEN'); -// Execute all at once: File::runTaskDirectory($dir); -``` - -### Handler Architecture Best Practices - -**File Utility Wrapper Methods**: Use static wrapper methods to reduce code duplication across handlers: - -```php -// Unified API for content replacement -File::replaceContentAsync([ - 'search1' => 'replace1', - 'search2' => 'replace2', -]); - -// Or single replacement -File::replaceContentAsync('search', 'replace'); - -// Or custom transformation -File::replaceContentAsync(function(string $content, ExtendedSplFileInfo $file): string { - // Complex logic here - return $content; -}); -``` - -**Central Execution**: All handlers should only QUEUE operations, not execute them. Execution happens centrally in `PromptManager.php`: - -```php -// In handlers: Queue operations only -File::replaceContentAsync('old', 'new'); -File::replaceTokenAsync('TOKEN'); - -// In PromptManager: Execute all queued operations once -File::runTaskDirectory($this->config->get(Config::TMP)); -``` - -### Refactoring Workflow - -1. **Create Wrappers**: Add static methods to `File` class for common patterns -1. **Replace Usage**: Update handlers to use wrapper methods -1. **Test Systematically**: - - Run baseline test first to verify core functionality - - Run individual test scenarios to catch edge cases - - Use `UPDATE_SNAPSHOTS=1` to regenerate expected outputs when needed - -### Performance Insights - -**Critical Success Factors**: - -- Maintain execution order (handlers queue, PromptManager executes) -- Preserve complex logic in callbacks for edge cases (e.g., empty line processing exclusions) -- Test each handler type (token removal, string replacement, custom transformation) - -### Common Pitfalls - -1. **Execution in Handlers**: Don't call `File::runTaskDirectory()` in individual handlers -2. **Import Namespace Issues**: Use `AlexSkrypnyk\File\Internal\ExtendedSplFileInfo` not the root namespace -3. **Complex Logic Loss**: Don't oversimplify complex transformations - use callback signature when needed -4. **Test Order Dependencies**: Some tests depend on specific file/directory states from previous handlers - -## Installer Test Architecture - -### Handler-Specific Test Classes - -The installer tests have been refactored to use a modular, handler-focused architecture that improves maintainability and test execution flexibility. - -**Abstract Base Class**: `AbstractHandlerProcessTestCase` provides shared test logic for all installer test scenarios, including: - -- Common setup and teardown procedures -- Core `testHandlerProcess()` method with data provider integration -- Fixture management and assertion helpers -- Version replacement utilities - -**Handler Test Organization**: Each installer handler has its own dedicated test class in the `Handlers/` namespace that extends the abstract base class. This approach provides: - -- **Focused Testing**: Each test class covers scenarios specific to one handler or feature area -- **Better Maintainability**: Smaller, focused data providers that are easier to understand and modify -- **Improved Filtering**: Granular test execution capabilities using PHPUnit filters -- **Scalable Architecture**: Easy to add new handler tests following established patterns - -**Key Benefits**: - -- Run all handler tests: `--filter "Handlers\\\\"` -- Run specific handler: `--filter "HandlerNameInstallTest"` -- Run specific scenarios: `--filter "HandlerNameInstallTest.*scenario_pattern"` -- Consistent structure across all handler test classes -- Clear separation between test logic (in base class) and test data (in handler classes) - -**Usage with Fixture Updates**: The `UPDATE_SNAPSHOTS=1` mechanism works seamlessly with the new architecture, allowing systematic fixture updates across all handler test scenarios. - -### PHPUnit Test Organization Best Practices - -**File Structure Convention**: PHPUnit test files should follow a consistent organization pattern for maintainability and readability: - -1. **Test methods first** - The actual test methods using `#[DataProvider]` attributes -2. **Data providers next** - Static methods that provide test data -3. **Protected helper methods last** - Helper methods at the bottom of the file - -**Example Structure**: - -```php -class ExampleTest extends TestCase { - // 1. Test Methods First - #[DataProvider('providerValidInput')] - public function testValidInput(string $input, string $expected): void { - // Test implementation - } - - #[DataProvider('providerInvalidInput')] - public function testInvalidInput(string $input, string $expectedMessage): void { - // Test implementation with exception handling - } - - // 2. Data Providers Next - public static function providerValidInput(): array { - return [ - 'case 1' => ['input' => 'value1', 'expected' => 'result1'], - 'case 2' => ['input' => 'value2', 'expected' => 'result2'], - ]; - } - - public static function providerInvalidInput(): array { - return [ - 'invalid case' => ['input' => 'bad', 'expectedMessage' => 'Error'], - ]; - } - - // 3. Protected Helper Methods Last - protected function createTestFixture(): string { - // Helper implementation - } -} -``` - -### Data Provider Patterns - -**Consolidating Success and Error Cases**: Use conditional exception handling to merge success and error scenarios into a single test method, significantly reducing code duplication: - -```php -public static function providerTestCases(): array { - return [ - 'success case' => [ - 'input' => 'valid', - 'expectedResult' => 'success', - 'expectedException' => NULL, - 'expectedMessage' => NULL, - ], - 'error case' => [ - 'input' => 'invalid', - 'expectedResult' => NULL, - 'expectedException' => \RuntimeException::class, - 'expectedMessage' => 'Invalid input', - ], - ]; -} - -#[DataProvider('providerTestCases')] -public function testCases(string $input, ?string $expectedResult, ?string $expectedException, ?string $expectedMessage): void { - if ($expectedException !== NULL) { - /** @var class-string<\Throwable> $expectedException */ - $this->expectException($expectedException); - $this->expectExceptionMessage($expectedMessage); - } - - $result = $this->systemUnderTest->process($input); - - if ($expectedResult !== NULL) { - $this->assertEquals($expectedResult, $result); - } -} -``` - -**Benefits of This Pattern**: - -- Eliminates duplicate test setup code -- Makes test scenarios easier to understand and compare -- Reduces overall test file length by 50-85% -- Maintains clear test output with descriptive scenario names -- Simplifies adding new test cases - -**When to Use**: - -- When multiple tests share identical setup but differ only in input/output -- When testing both success and failure paths of the same method -- When test scenarios can be parameterized effectively - -**When Not to Use**: - -- When tests require significantly different setup logic -- When tests are testing fundamentally different behaviors -- When conditional logic would make tests harder to understand - -### Cross-Platform File Operations in Tests - -**Critical**: Always use the `AlexSkrypnyk\File\File` class for file system operations in tests instead of native PHP functions. This ensures cross-platform compatibility across Windows, Linux, and macOS. - -**Required Import**: - -```php -use AlexSkrypnyk\File\File; -``` - -**Test Temporary Directory**: - -All tests extending `UnitTestCase` have access to `self::$tmp` - a temporary directory that is automatically created before tests and cleaned up after. Always use this for test file operations instead of creating your own temporary directories. - -**File Operations Mapping**: - -| Native PHP Function | File Class Method | Purpose | -|---------------------|-------------------|---------| -| `mkdir($path)` | `File::mkdir($path)` | Create directory (with parents if needed) | -| `file_put_contents($path, $content)` | `File::dump($path, $content)` | Write content to file | -| `unlink($file)` | `File::remove($file)` | Remove file | -| `rmdir($dir)` recursively | `File::rmdir($dir)` | Remove directory recursively | - -**Example Usage**: - -```php -class MyTest extends UnitTestCase { - public function testSomething(): void { - // ✅ CORRECT - Cross-platform compatible using self::$tmp - $test_dir = self::$tmp . '/subdir_' . uniqid(); - File::mkdir($test_dir); - File::dump($test_dir . '/file.txt', 'content'); - $content = file_get_contents($test_dir . '/file.txt'); - File::remove($test_dir . '/file.txt'); - // No need to clean up - self::$tmp is auto-cleaned by UnitTestCase - - // ❌ INCORRECT - Platform-dependent native PHP functions - $test_dir = sys_get_temp_dir() . '/test_' . uniqid(); - mkdir($test_dir); - file_put_contents($test_dir . '/file.txt', 'content'); - unlink($test_dir . '/file.txt'); - rmdir($test_dir); - } -} -``` - -**Benefits**: - -- **Cross-platform compatibility**: Handles path separators and permissions correctly on all OS -- **Consistent error handling**: Throws `FileException` with clear messages -- **Automatic cleanup**: `self::$tmp` is automatically cleaned up by UnitTestCase tearDown -- **Better abstractions**: File class methods handle edge cases automatically - -**Reference**: Full File class documentation available at `.vortex/installer/vendor/alexskrypnyk/file/README.md` - -## PHPUnit Helper Functions - -### cmd() Function - -The `FunctionalTestCase` provides a convenient `cmd()` function that combines `processRun()` + `assertProcessSuccessful()` + output assertions: - -```php -public function cmd( - string $cmd, - array|string|null $out = NULL, - ?string $txt = NULL, - array $arg = [], - array $inp = [], - array $env = [], - int $tio = 60, - int $ito = 60, -): ?Process -``` - -**Basic Usage:** - -```php -// Simple command without output checks -$this->cmd('ahoy drush cr'); - -// Command with single output assertion -$this->cmd('ahoy doctor info', 'OPERATING SYSTEM'); - -// Command with multiple output assertions -$this->cmd('ahoy info', [ - 'Project name : star_wars', - 'Docker Compose project name : star_wars' -]); - -// Command with named parameters -$this->cmd('ahoy reset', inp: ['y'], tio: 5 * 60); -``` - -### cmdFail() Function - -For commands expected to fail, use `cmdFail()` which calls `assertProcessFailed()`: - -```php -$this->cmdFail('ahoy lint-be', tio: 120, ito: 90); -``` - -### Output Assertion Prefixes - -**CRITICAL RULE**: When using ANY prefixed strings, **ALL strings must have prefixes**. You cannot mix prefixed and non-prefixed strings. - -#### Prefix Types - -- **`+`** - Exact match present (entire output must equal this string) -- **`*`** - Substring present (string must be found within output) -- **`-`** - Exact match absent (entire output must NOT equal this string) -- **`!`** - Substring absent (string must NOT be found within output) - -#### Two Operating Modes - -**1. Shortcut Mode** (No prefixes - all treated as substring present): - -```php -$this->cmd('ahoy info', ['Docker', 'Compose']); // Both must be found in output -``` - -**2. Mixed Mode** (Any prefix present - ALL must have prefixes): - -```php -// ✅ CORRECT - all strings have prefixes -$this->cmd('ahoy info', [ - '* Xdebug', // Must contain "Xdebug" - '* Disabled', // Must contain "Disabled" - '! Enabled' // Must NOT contain "Enabled" -]); - -// ❌ INCORRECT - mixing prefixed and non-prefixed -$this->cmd('ahoy info', [ - 'Xdebug', // No prefix - '! Enabled' // Has prefix - this will throw RuntimeException -]); -``` - -**Example Conversions:** - -Before: - -```php -$this->processRun('ahoy export-db', $args); -$this->assertProcessSuccessful(); -$this->assertProcessOutputNotContains('Containers are not running.'); -``` - -After: - -```php -$this->cmd('ahoy export-db', '! Containers are not running.', arg: $args); -``` - -### When to Use cmd() vs processRun() - -**Use `cmd()`:** - -- Commands that should succeed (`assertProcessSuccessful()`) -- Simple output assertions (`assertProcessOutputContains/NotContains`) -- Most common test scenarios - -**Use `processRun()`:** - -- Commands with complex error output assertions (`assertProcessErrorOutputContains`) -- Commands requiring custom logic between execution and assertions -- Special cases like conditional retry patterns - -## System-Specific Resources - -### Documentation System - -- **Live Site**: https://www.vortextemplate.com -- **Docusaurus Docs**: https://docusaurus.io/docs -- **React Testing Library**: https://testing-library.com/docs/react-testing-library/intro/ -- **Jest Documentation**: https://jestjs.io/docs/getting-started -- **MDX Documentation**: https://mdxjs.com/docs/ - -### Installer System - -- **Symfony Console**: https://symfony.com/doc/current/console.html -- **PHPUnit Documentation**: https://phpunit.de/documentation.html -- **Composer Documentation**: https://getcomposer.org/doc/ - -### Template Testing System - -- **BATS Documentation**: https://github.com/bats-core/bats-core -- **PHPUnit Helpers**: https://github.com/AlexSkrypnyk/phpunit-helpers -- **Docker Compose**: https://docs.docker.com/compose/ - -### General - -- **Issue Tracking**: https://github.com/drevops/vortex/issues -- **Main Repository**: https://github.com/drevops/vortex - -## Important AI Assistant Guidelines - -### CRITICAL: Commands That Require User Permission - -**NEVER run these commands without explicit user permission:** - -- `ahoy update-snapshots` - Updates all test fixtures (can take 10-15 minutes, runs full test suite twice) -- `UPDATE_SNAPSHOTS=1 ./vendor/bin/phpunit` - Updates installer test fixtures -- `UPDATE_SNAPSHOTS=1 composer test` - Updates any test fixtures -- Any command with `UPDATE_SNAPSHOTS=1` environment variable - -**Why**: These commands: - -- Modify many files across the codebase -- Take significant time to complete (10-15 minutes) -- Run full test suites multiple times -- Should only be run when user explicitly requests fixture updates - -**When user needs fixture updates**: - -- Explain what the command does and how long it will take -- Ask for explicit permission before running -- Let the user run it themselves if they prefer - -### System-Specific Restrictions - -**Documentation System** (`.vortex/docs/`): - -- Maintain American English spelling throughout -- Test React components thoroughly before committing -- Preserve responsive design patterns - -**Installer System** (`.vortex/installer/`): - -- **CRITICAL**: NEVER directly modify files under `.vortex/installer/tests/Fixtures/` -- These are test fixtures that must be updated via `ahoy update-snapshots` command from `.vortex/` directory -- The unified `ahoy update-snapshots` command handles all fixture updates automatically -- For debugging, manual `UPDATE_SNAPSHOTS=1` commands can be used from `.vortex/installer/` -- Always test with baseline scenario first, then individual scenarios -- Preserve handler execution order and batching patterns - -**Template Testing System** (`.vortex/tests/`): - -- Follow PHPUnit helper function patterns (`cmd()`, `cmdFail()`) -- Maintain BATS test assertion alignment with script output -- Preserve Docker container isolation between tests -- Use appropriate test types for different validation levels - -### General Coding Standards - -**Line Length**: - -- **Code**: Keep code on single lines as much as possible. There is no character limit per line for code. -- **Comments**: Follow standard line length limits (typically 80-120 characters) for comments and documentation. - -**Rationale**: Code readability is enhanced by keeping logical units on single lines, while comments should be wrapped for readability. - -**Examples**: - -```php -// ✅ GOOD - Single-line code -throw new \RuntimeException(sprintf('Failed to download archive from: %s - %s', $url, $e->getMessage())); - -// ❌ AVOID - Multi-line code when not necessary -throw new \RuntimeException(sprintf( - 'Failed to download archive from: %s - %s', - $url, - $e->getMessage() -)); - -// ✅ GOOD - Wrapped comment for readability -// This is a long comment that explains the reasoning behind the implementation -// and should be wrapped at a reasonable character limit for easier reading -// in various editor configurations. -``` +**NEVER run without explicit user permission**: -**Exceptions**: Multi-line code is acceptable when: +- `ahoy update-snapshots` +- `UPDATE_SNAPSHOTS=1 ./vendor/bin/phpunit` +- Any `UPDATE_SNAPSHOTS=1` command -- Function signatures have many parameters -- Array definitions with multiple elements -- Chained method calls for fluent interfaces -- Complex conditional expressions that benefit from line breaks +These modify many files and take 10-15 minutes. -### Cross-System Considerations +### Key Restrictions -- Each system can be modified independently -- Changes to template (outside `.vortex/`) may require updates across all three systems -- Always run system-specific tests after making changes -- Consider impact on user workflows when modifying any system +- **NEVER** modify `.vortex/installer/tests/Fixtures/` directly +- American English spelling in documentation +- Sentence case for doc headings (capitalize proper nouns only) ---- +### Coding Standards -*This knowledge base should be updated whenever significant changes are made to any of the three Vortex subsystems or their maintenance procedures.* +- **Code**: Single lines preferred, no character limit +- **Comments**: Wrap at 80-120 characters +- Multi-line OK for: many parameters, arrays, chained methods, complex + conditionals diff --git a/.vortex/docs/.utils/update-docs.sh b/.vortex/docs/.utils/update-docs.sh index 10c1d5e7b..1f40887bd 100755 --- a/.vortex/docs/.utils/update-docs.sh +++ b/.vortex/docs/.utils/update-docs.sh @@ -14,7 +14,7 @@ ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../../" && pwd)" sed_opts=(-i) && [ "$(uname)" = "Darwin" ] && sed_opts=(-i '') -OUTPUT_FILE="./content/workflows/variables.mdx" +OUTPUT_FILE="./content/development/variables.mdx" sed "${sed_opts[@]}" '/## Variables list/,$d' "${OUTPUT_FILE}" echo "## Variables list" >>"${OUTPUT_FILE}" diff --git a/.vortex/docs/.utils/variables/extra/acquia.variables.sh b/.vortex/docs/.utils/variables/extra/acquia.variables.sh index 69e6158dd..e0795e44d 100755 --- a/.vortex/docs/.utils/variables/extra/acquia.variables.sh +++ b/.vortex/docs/.utils/variables/extra/acquia.variables.sh @@ -17,25 +17,25 @@ VORTEX_PROVISION_ACQUIA_SKIP= # NewRelic API key, usually of type 'USER'. # -# @see https://www.vortextemplate.com/docs/workflows/notifications#new-relic +# @see https://www.vortextemplate.com/docs/deployment/notifications#new-relic VORTEX_NOTIFY_NEWRELIC_APIKEY= # JIRA API token. # -# @see https://www.vortextemplate.com/docs/workflows/notifications#jira +# @see https://www.vortextemplate.com/docs/deployment/notifications#jira VORTEX_NOTIFY_JIRA_TOKEN= # GitHub token. # -# @see https://www.vortextemplate.com/docs/workflows/notifications#github +# @see https://www.vortextemplate.com/docs/deployment/notifications#github VORTEX_NOTIFY_GITHUB_TOKEN= # Slack webhook URL. # The incoming Webhook URL from your Slack app configuration. -# @see https://www.vortextemplate.com/docs/workflows/notifications#slack +# @see https://www.vortextemplate.com/docs/deployment/notifications#slack VORTEX_NOTIFY_SLACK_WEBHOOK="${VORTEX_NOTIFY_SLACK_WEBHOOK:-}" # Custom webhook URL. # -# @see https://www.vortextemplate.com/docs/workflows/notifications#webhook +# @see https://www.vortextemplate.com/docs/deployment/notifications#webhook VORTEX_NOTIFY_WEBHOOK_URL= diff --git a/.vortex/docs/.utils/variables/extra/lagoon.variables.sh b/.vortex/docs/.utils/variables/extra/lagoon.variables.sh index 385fc30ce..e3517f1f3 100755 --- a/.vortex/docs/.utils/variables/extra/lagoon.variables.sh +++ b/.vortex/docs/.utils/variables/extra/lagoon.variables.sh @@ -18,25 +18,25 @@ NEWRELIC_LICENSE= # Notification NewRelic API key, usually of type 'USER'. # -# @see https://www.vortextemplate.com/docs/workflows/notifications#new-relic +# @see https://www.vortextemplate.com/docs/deployment/notifications#new-relic VORTEX_NOTIFY_NEWRELIC_APIKEY= # Notification JIRA API token. # -# @see https://www.vortextemplate.com/docs/workflows/notifications#jira +# @see https://www.vortextemplate.com/docs/deployment/notifications#jira VORTEX_NOTIFY_JIRA_TOKEN= # Notification GitHub token. # -# @see https://www.vortextemplate.com/docs/workflows/notifications#github +# @see https://www.vortextemplate.com/docs/deployment/notifications#github VORTEX_NOTIFY_GITHUB_TOKEN= # Notification Slack webhook URL. # The incoming Webhook URL from your Slack app configuration. -# @see https://www.vortextemplate.com/docs/workflows/notifications#slack +# @see https://www.vortextemplate.com/docs/deployment/notifications#slack VORTEX_NOTIFY_SLACK_WEBHOOK="${VORTEX_NOTIFY_SLACK_WEBHOOK:-}" # Notification custom webhook URL. # -# @see https://www.vortextemplate.com/docs/workflows/notifications#webhook +# @see https://www.vortextemplate.com/docs/deployment/notifications#webhook VORTEX_NOTIFY_WEBHOOK_URL= diff --git a/.vortex/docs/CLAUDE.md b/.vortex/docs/CLAUDE.md new file mode 100644 index 000000000..4d28ee9f8 --- /dev/null +++ b/.vortex/docs/CLAUDE.md @@ -0,0 +1,60 @@ +# Documentation System Guide + +## Overview + +Docusaurus-based documentation website published to https://www.vortextemplate.com + +**Technology**: Docusaurus, React, MDX, Jest, cspell + +## Commands + +```bash +cd .vortex/docs + +yarn install # Install dependencies +yarn start # Development server +yarn build # Production build +yarn test # Run Jest tests +yarn spellcheck # American English validation +yarn lint # Code quality checks +yarn lint-fix # Auto-fix issues +``` + +## Key Directories + +``` +docs/ +├── content/ # MDX documentation pages +├── src/components/ # React components +├── tests/unit/ # Jest tests +├── sidebars.js # Sidebar configuration +└── docusaurus.config.js +``` + +## Writing Guidelines + +- **American English** spelling throughout +- **Sentence case** for headings (capitalize only first letter + proper nouns) +- Proper nouns: Vortex, GitHub, Drupal, Docker Compose, CircleCI +- Acronyms: CI/CD, SSH, API, BDD, PHPUnit + +## Sidebar Configuration + +Categories defined in `sidebars.js`. For subdirectories: +- Category label from explicit definition or directory name +- Use `sidebar_label: Overview` in README.mdx for first item + +## Troubleshooting + +```bash +# Build failures +yarn build --verbose + +# Spellcheck failures +yarn spellcheck +npx cspell "content/**/*.md" + +# Test failures +yarn test --verbose +yarn test --updateSnapshot +``` diff --git a/.vortex/docs/content/README.mdx b/.vortex/docs/content/README.mdx index 210eeced5..bed3993d1 100644 --- a/.vortex/docs/content/README.mdx +++ b/.vortex/docs/content/README.mdx @@ -145,7 +145,7 @@ foundation for developing and maintaining Drupal projects. ## 🚀 Quick start -```bash +```shell curl -SsL https://www.vortextemplate.com/install > installer.php && php installer.php ``` diff --git a/.vortex/docs/content/workflows/_code-lifecycle.mdx b/.vortex/docs/content/_code-lifecycle.mdx similarity index 100% rename from .vortex/docs/content/workflows/_code-lifecycle.mdx rename to .vortex/docs/content/_code-lifecycle.mdx diff --git a/.vortex/docs/content/architecture.mdx b/.vortex/docs/content/architecture.mdx index 07a03d390..6989f029e 100644 --- a/.vortex/docs/content/architecture.mdx +++ b/.vortex/docs/content/architecture.mdx @@ -1,7 +1,7 @@ # Architecture **Vortex** is a production-ready Drupal project template designed to simplify -onboarding, unify workflows, and ensure long-term maintainability. +onboarding, standardize processes, and ensure long-term maintainability. This page provides a high-level overview of how the template is structured, how its components work together, and how your project benefits from its @@ -32,7 +32,7 @@ The system is made up of several modular pieces that work together: - Hosting provider configurations - Automated dependency updates - Project documentation -- Workflow scripts to connect components +- Automation scripts to connect components You can see how these parts connect in the diagram below: @@ -50,7 +50,7 @@ the chance of errors and making processes predictable.
Expand to see the complete code lifecycle diagram -import CodeLifecycle from './workflows/_code-lifecycle.mdx'; +import CodeLifecycle from './_code-lifecycle.mdx'; @@ -63,7 +63,7 @@ production-grade Lagoon images. This ensures consistency between local, CI, and hosting environments. To simplify command usage, we use [Ahoy](https://ahoy-cli.dev/) as a wrapper. It -lets you run complex workflows like provisioning, testing, or database imports +lets you run complex tasks like provisioning, testing, or database imports with short, easy-to-remember commands. :::note Planned features @@ -145,7 +145,7 @@ You’ll also find scaffolds for: ## Continuous integration workflows **Vortex** supports GitHub Actions and CircleCI. You choose which one to use in your -project. The workflows include: +project. These pipelines include: - Database download and caching (for faster builds) - Full site provisioning in CI @@ -163,7 +163,7 @@ uniformity. Out of the box, **Vortex** supports Acquia and Lagoon hosting. These integrations: - Trigger provisioning with the same steps used locally and in CI -- Provide deployment workflows suited to each platform +- Provide deployment pipelines suited to each platform You can use **Vortex** with other platforms too, but these are first-class integrations. @@ -188,10 +188,10 @@ the schedule as needed. **Vortex** includes centralized documentation (what you’re reading now), as well as a scaffold for adding project-specific docs within your own repository. -## Workflow scripts +## Automation scripts -A workflow is a sequence of steps to achieve a goal. In **Vortex**, those are -defined via POSIX-compliant Bash scripts in `scripts/vortex`. +**Vortex** uses POSIX-compliant Bash scripts in `scripts/vortex` to automate +common tasks and connect components together. These scripts: @@ -199,16 +199,16 @@ These scripts: - Support environment variables to adapt behavior - Are modular and easy to extend -### Customizing workflows +### Customizing scripts -All scripts support configuration via environment variables, allowing workflows +All scripts support configuration via environment variables, allowing them to be easily adapted to specific project or environment needs. During initial project setup, `.env` file is updated with project-specific values like project name, email etc. Then, environment variables (secrets, tokens, etc.) are set in CI or hosting environments. -Refer to the [Workflows](./workflows) section for more details. +➡️ See [Development > Variables](./development/variables) ### Router scripts @@ -235,7 +235,7 @@ For example:
-➡️ See [Workflows](./workflows) +➡️ See [Variables](./development/variables) ## Environment variables @@ -245,4 +245,4 @@ local, CI, and hosting environments. These variables are either defined in the `.env` file or set within CI/hosting environments as secrets. -➡️ See [Workflows > Variables](./workflows/variables) +➡️ See [Variables](./development/variables) diff --git a/.vortex/docs/content/continuous-integration/README.mdx b/.vortex/docs/content/continuous-integration/README.mdx index ec8953c19..1c8476d7e 100644 --- a/.vortex/docs/content/continuous-integration/README.mdx +++ b/.vortex/docs/content/continuous-integration/README.mdx @@ -18,7 +18,7 @@ containerized environment to ensure consistency across runs. ## Workflow structure -import CodeLifecycle from '../workflows/_code-lifecycle.mdx'; +import CodeLifecycle from '../_code-lifecycle.mdx'; @@ -161,7 +161,7 @@ into already deployed environments which still run CI checks on new commits. To skip deployments for specific branches, set the `VORTEX_DEPLOY_SKIP_BRANCHES` variable to a comma-separated list of exact branch names: -```bash +```shell VORTEX_DEPLOY_ALLOW_SKIP=1 # Enable deployment skipping VORTEX_DEPLOY_SKIP_BRANCHES="feature/test,hotfix/urgent,project/experimental" ``` @@ -169,7 +169,7 @@ VORTEX_DEPLOY_SKIP_BRANCHES="feature/test,hotfix/urgent,project/experimental" To skip deployments for specific pull requests, set the `VORTEX_DEPLOY_SKIP_PRS` variable to a comma-separated list of PR numbers: -```bash +```shell VORTEX_DEPLOY_ALLOW_SKIP=1 # Enable deployment skipping VORTEX_DEPLOY_SKIP_PRS="123,456,789" ``` diff --git a/.vortex/docs/content/continuous-integration/circleci.mdx b/.vortex/docs/content/continuous-integration/circleci.mdx index 6d17b18e8..8148ac213 100644 --- a/.vortex/docs/content/continuous-integration/circleci.mdx +++ b/.vortex/docs/content/continuous-integration/circleci.mdx @@ -39,7 +39,7 @@ SSH key that has access to your hosting environments. 1. Generate an SSH key pair: - ```bash + ```shell ssh-keygen -m PEM -t rsa -b 4096 -C "deployer+myproject-circleci@example.com" -f ~/.ssh/deployer_myproject_circleci -N "" ``` @@ -72,7 +72,7 @@ same provider, you can use a single key for both operations. 1. Generate an SSH key pair (skip if using the same key as above): - ```bash + ```shell ssh-keygen -m PEM -t rsa -b 4096 -C "deployer+myproject-circleci@example.com" -f ~/.ssh/deploy_myproject_circleci -N "" ``` diff --git a/.vortex/docs/content/continuous-integration/github-actions.mdx b/.vortex/docs/content/continuous-integration/github-actions.mdx index 88c435423..f945dd5b9 100644 --- a/.vortex/docs/content/continuous-integration/github-actions.mdx +++ b/.vortex/docs/content/continuous-integration/github-actions.mdx @@ -40,7 +40,7 @@ SSH key that has access to your hosting environments. 1. Generate an SSH key pair: - ```bash + ```shell ssh-keygen -m PEM -t rsa -b 4096 -C "deployer+myproject-gha@example.com" -f ~/.ssh/deployer_myproject_gha -N "" ``` @@ -73,7 +73,7 @@ same provider, you can use a single key for both operations. 1. Generate an SSH key pair (skip if using the same key as above): - ```bash + ```shell ssh-keygen -m PEM -t rsa -b 4096 -C "deployer+myproject-gha@example.com" -f ~/.ssh/deployer_myproject_gha -N "" ``` diff --git a/.vortex/docs/content/contributing/maintenance/documentation.mdx b/.vortex/docs/content/contributing/maintenance/documentation.mdx index f6d7f5a24..0e3a776bb 100644 --- a/.vortex/docs/content/contributing/maintenance/documentation.mdx +++ b/.vortex/docs/content/contributing/maintenance/documentation.mdx @@ -2,21 +2,29 @@ There are 2 types of the documentation that **Vortex** provides: -1. This Documentation of **Vortex** that is then deployed - to https://www.vortextemplate.com/docs/ -2. Consumer site documentation that is distributed when **Vortex** is - installed. +1. **Vortex template documentation** (this site) - Generic information on + **how** to perform operations, applicable to all projects built with Vortex. + Deployed to https://www.vortextemplate.com/docs/ +2. **Per-project documentation** - Project-specific information on **what** the + project does, distributed in the `docs/` directory when Vortex is installed. + +The key relationship: per-project documentation describes **what** (coding +standards, testing requirements, release configuration) while referencing the +Vortex documentation for **how** to perform specific operations. ## www.vortextemplate.com -The Documentation (this site) is written in Markdown and located in -[`.vortex/docs`](https://github.com/drevops/vortex/blob/main/.vortex/docs) directory. This is -removed when you install **Vortex** for a -consumer site. +This documentation provides generic "how-to" guides suitable for any project +using the Vortex template. It covers tooling, automation, and operations that +are common across all Vortex-based projects. + +The source is written in Markdown and located in +[`.vortex/docs`](https://github.com/drevops/vortex/blob/main/.vortex/docs) +directory. This is removed when you install **Vortex** for a consumer site. ### Local build -```bash +```shell cd .vortex/docs ahoy build ``` @@ -24,7 +32,7 @@ ahoy build Parts of the documentation are generated automatically from the codebase. To update it, run: -```bash +```shell cd .vortex ahoy update-docs ``` @@ -34,7 +42,7 @@ be available immediately. ### Check spelling and links -```bash +```shell cd .vortex ahoy test-docs ``` @@ -59,3 +67,16 @@ An automated continuous integration build publishes this documentation. After **Vortex** is installed into the consumer site, these docs are intended to be used by the site maintainers and stay up-to-date with the project changes. + +This documentation describes the **what** for the project: + +- Coding standards and agreements specific to the project +- Testing requirements and configuration +- Release and deployment configuration +- Project-specific procedures and decisions + +When describing **how** to perform an operation, per-project documentation +should reference the relevant page on https://www.vortextemplate.com/docs/ +rather than duplicating instructions. This keeps project docs focused on +decisions and configuration while leveraging the maintained Vortex +documentation for operational details. diff --git a/.vortex/docs/content/contributing/maintenance/release.mdx b/.vortex/docs/content/contributing/maintenance/release.mdx index 6d9b32e0f..5db474592 100644 --- a/.vortex/docs/content/contributing/maintenance/release.mdx +++ b/.vortex/docs/content/contributing/maintenance/release.mdx @@ -23,7 +23,7 @@ When creating a new release, determine the version based on the changes: 1. **Bump MAJOR** when making incompatible breaking changes: - Removing features or configuration options - - Changing default behavior that breaks existing workflows + - Changing default behavior that breaks existing projects - Updating to new major versions of services or dependencies that require migration 2. **Bump MINOR** when adding functionality in a backward compatible manner: diff --git a/.vortex/docs/content/contributing/maintenance/scripts.mdx b/.vortex/docs/content/contributing/maintenance/scripts.mdx index 837ff1276..761fdae16 100644 --- a/.vortex/docs/content/contributing/maintenance/scripts.mdx +++ b/.vortex/docs/content/contributing/maintenance/scripts.mdx @@ -18,7 +18,7 @@ in [this issue](https://github.com/drevops/vortex/issues/1192). 1. MUST adhere to [POSIX standard](https://en.wikipedia.org/wiki/POSIX). 2. MUST pass Shellcheck code analysis scan 3. MUST start with: -```bash +```shell #!/usr/bin/env bash ## # Action description that the script performs. @@ -31,17 +31,17 @@ in [this issue](https://github.com/drevops/vortex/issues/1192). [ "${VORTEX_DEBUG-}" = "1" ] && set -x ``` 4. MUST list all variables with their default values and descriptions. i.e.: -```bash +```shell # Deployment reference, such as a git SHA. VORTEX_NOTIFY_REF="${VORTEX_NOTIFY_REF:-}" ``` 5. MUST include a delimiter between variables and the script body preceded and followed by an empty line (3 lines in total): -```bash +```shell # ------------------------------------------------------------------------------ ``` 6. SHOULD include formatting helper functions: -```bash +```shell # @formatter:off note() { printf " %s\n" "${1}"; } info() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\033[34m[INFO] %s\033[0m\n" "${1}" || printf "[INFO] %s\n" "${1}"; } @@ -50,19 +50,19 @@ fail() { [ "${TERM:-}" != "dumb" ] && tput colors >/dev/null 2>&1 && printf "\03 # @formatter:on ``` 7. SHOULD include variable values checks with errors and early exist, i.e.: -```bash +```shell [ -z "${VORTEX_NOTIFY_REF}" ] && fail "Missing required value for VORTEX_NOTIFY_REF" && exit 1 ``` 8. SHOULD include binaries checks if the script relies on them, i.e.: -```bash +```shell command -v curl > /dev/null || ( fail "curl command is not available." && exit 1 ) ``` 9. MUST contain an `info` message about the start of the script body, e.g.: -```bash +```shell info "Started GitHub notification for operation ${VORTEX_NOTIFY_EVENT}" ``` 10. MUST contain an `pass` message about the finish of the script body, e.g.: -```bash +```shell pass "Finished GitHub notification for operation ${VORTEX_NOTIFY_EVENT}" ``` 11. MUST use uppercase global variables diff --git a/.vortex/docs/content/contributing/maintenance/tests.mdx b/.vortex/docs/content/contributing/maintenance/tests.mdx index a3dbe354e..9a0e4542d 100644 --- a/.vortex/docs/content/contributing/maintenance/tests.mdx +++ b/.vortex/docs/content/contributing/maintenance/tests.mdx @@ -1,10 +1,10 @@ # Authoring tests -There are 2 types of tests in **Vortex**: +There are 2 types of tests used in **Vortex**: -- [PHPUnit](https://phpunit.de/) for functional end-to-end testing of workflows.
+- [PHPUnit](https://phpunit.de/) for functional end-to-end testing of a site build pipeline.
With help of [`phpunit-helpers`](https://github.com/AlexSkrypnyk/phpunit-helpers) testing library, we run tests -for workflows, including container builds, database imports, and Drupal +for automations, including container builds, database imports, and Drupal operations as if they were run by a consumer site developer. - [Bats](https://github.com/bats-core/bats-core) for unit testing of scripts in `scripts/vortex`.
@@ -21,7 +21,7 @@ operations as if they were run by a consumer site developer. ## Functional tests with PHPUnit -```bash +```shell cd .vortex/tests # Install Composer dependencies. @@ -39,7 +39,7 @@ Functional tests rely on database fixtures - see the section below on ## Unit tests with BATS -```bash +```shell cd .vortex/tests # Install npm dependencies. @@ -53,20 +53,20 @@ bats .vortex/tests/bats/deploy.bats There are *demo* and *test* database dumps captured as *files* and *container images*. -- Demo database dump file - *demonstration* of the database import capabilities from a *file* during a normal workflow. -- Demo database container image - *demonstration* of the database import capabilities from a *container image* during a normal workflow. -- Test database dump file - *test* of the database import capabilities from a *file* during the normal workflow. -- Test database container image - *test* of the database import capabilities from a *container image* during the normal workflow. +- Demo database dump file - *demonstration* of the database import capabilities from a *file*. +- Demo database container image - *demonstration* of the database import capabilities from a *container image*. +- Test database dump file - *test* of the database import capabilities from a *file*. +- Test database container image - *test* of the database import capabilities from a *container image*. ### Updating *demo* database dump *file* 1. Run fresh build of **Vortex** locally: -```bash +```shell rm .data/db.sql || true VORTEX_PROVISION_TYPE=profile VORTEX_PROVISION_POST_OPERATIONS_SKIP=1 AHOY_CONFIRM_RESPONSE=1 ahoy build ``` 2. Update content and config: -```bash +```shell ahoy cli drush eval "Drupal::entityTypeManager()->getStorage('node')->create([ @@ -85,7 +85,7 @@ exit ``` 3. Export DB: -```bash +```shell ahoy export-db db.demo.sql ``` 4. Upload `db.demo.sql` to the latest release as an asset and name it `db_d11.demo.sql`. @@ -93,12 +93,12 @@ ahoy export-db db.demo.sql ### Updating *demo* database *container image* 1. Run fresh build of **Vortex** locally: -```bash +```shell rm .data/db.sql || true VORTEX_PROVISION_TYPE=profile VORTEX_PROVISION_POST_OPERATIONS_SKIP=1 AHOY_CONFIRM_RESPONSE=1 ahoy build ``` 2. Update content and config: -```bash +```shell ahoy cli drush eval "Drupal::entityTypeManager()->getStorage('node')->create([ @@ -117,14 +117,14 @@ exit ``` 3. Export DB: -```bash +```shell ahoy export-db db.demo_image.sql # Update the collation to avoid issues with MariaDB 10.5+: sed -i '' 's/utf8mb4_0900_ai_ci/utf8mb4_general_ci/g' .data/db.demo_image.sql ``` 4. Seed the database container image: -```bash +```shell curl -LO https://github.com/drevops/mariadb-drupal-data/releases/latest/download/seed.sh chmod +x seed.sh ./seed.sh .data/db.demo_image.sql drevops/vortex-dev-mariadb-drupal-data-demo-11.x:latest @@ -133,18 +133,18 @@ chmod +x seed.sh ### Updating *test* database dump *file* 1. Run a fresh install of **Vortex** into a new directory and name the project `Star Wars`: -```bash +```shell mkdir /tmp/star-wars VORTEX_INSTALLER_TEMPLATE_REPO="$(pwd)" .vortex/installer/installer.php /tmp/star-wars --no-interaction cd /tmp/star-wars ``` 2. Run fresh build of **Vortex** locally: -```bash +```shell rm .data/db.sql || true VORTEX_PROVISION_TYPE=profile AHOY_CONFIRM_RESPONSE=1 ahoy build ``` 3. Update content and config: -```bash +```shell ahoy cli drush eval "Drupal::entityTypeManager()->getStorage('node')->create([ @@ -163,7 +163,7 @@ exit ``` 4. Export DB: -```bash +```shell ahoy export-db db.test.sql ``` 5. Upload `db.test.sql` to the latest release as an asset and name it `db_d11.test.sql`. @@ -171,18 +171,18 @@ ahoy export-db db.test.sql ### Updating *test* database *container image* 1. Run a fresh install of **Vortex** into a new directory and name the project `Star Wars`: -```bash +```shell mkdir /tmp/star-wars VORTEX_INSTALLER_TEMPLATE_REPO="$(pwd)" .vortex/installer/installer.php /tmp/star-wars --no-interaction cd /tmp/star-wars ``` 2. Run fresh build of **Vortex** locally: -```bash +```shell rm .data/db.sql || true VORTEX_PROVISION_TYPE=profile AHOY_CONFIRM_RESPONSE=1 ahoy build ``` 3. Update content and config: -```bash +```shell ahoy cli drush eval "Drupal::entityTypeManager()->getStorage('node')->create([ @@ -201,20 +201,20 @@ exit ``` 4. Export DB: -```bash +```shell ahoy export-db db.test_image.sql # Update the collation to avoid issues with MariaDB 10.5+: sed -i '' 's/utf8mb4_0900_ai_ci/utf8mb4_general_ci/g' .data/db.test_image.sql ``` 5. Seed the database container image: -```bash +```shell curl -LO https://github.com/drevops/mariadb-drupal-data/releases/latest/download/seed.sh chmod +x seed.sh ./seed.sh .data/db.test_image.sql drevops/vortex-dev-mariadb-drupal-data-test-11.x:latest ``` 6. Update destination container images: -```bash +```shell docker tag drevops/vortex-dev-mariadb-drupal-data-demo-11.x:latest drevops/vortex-dev-mariadb-drupal-data-demo-destination-11.x:vortex-dev-database-ii docker push drevops/vortex-dev-mariadb-drupal-data-demo-destination-11.x:vortex-dev-database-ii diff --git a/.vortex/docs/content/workflows/deployment.mdx b/.vortex/docs/content/deployment/README.mdx similarity index 78% rename from .vortex/docs/content/workflows/deployment.mdx rename to .vortex/docs/content/deployment/README.mdx index c5081bd0d..c8459ee21 100644 --- a/.vortex/docs/content/workflows/deployment.mdx +++ b/.vortex/docs/content/deployment/README.mdx @@ -1,5 +1,6 @@ --- -sidebar_position: 3 +sidebar_label: Overview +sidebar_position: 1 --- # Deployment @@ -8,22 +9,22 @@ Deployment to a remote location is performed by the [`scripts/vortex/deploy.sh`](https://github.com/drevops/vortex/blob/main/scripts/vortex/deploy.sh) _router_ script. -The script runs in continuous integration pipeline only after all tests pass. +The script runs in continuous integration pipeline `deploy` job only after all +tests pass. -The script deploys the code to a remote location by calling the +The script deploys the code to a remote location by calling the relevant scripts based on the type of deployment defined in `$VORTEX_DEPLOY_TYPES` variable as a comma-separated list of one or multiple supported deployment types: -- `webhook` - a webhook URL is called via CURL. -- `artifact` - a [code artifact is created](/docs/tools/git-artifact) and sent to a remote repository. -- `lagoon` - a Lagoon's webhook URL is called via CURL to trigger a deployment in - Lagoon. -- `docker` - a container image is built and pushed to a remote registry. +- [`webhook`](webhook) - A webhook URL is called via CURL. +- [`artifact`](artifact) - A code artifact is created and sent to a remote repository. +- [`lagoon`](lagoon) - A Lagoon webhook URL is called via CURL to trigger a deployment. +- [`docker`](docker) - A container image is built and pushed to a remote registry.
Expand to see deployment in the complete code lifecycle -import CodeLifecycle from './_code-lifecycle.mdx'; +import CodeLifecycle from '../_code-lifecycle.mdx'; @@ -74,7 +75,7 @@ To change this behavior and overwrite the database with a fresh copy from production environment, set the `$VORTEX_DEPLOY_ACTION` variable to `deploy_override_db`. -## Skipping all deployments +## Skipping deployments You can skip all deployments by setting the `VORTEX_DEPLOY_SKIP` environment variable to `1`. @@ -91,7 +92,7 @@ and provide lists in the following variables: Set `$VORTEX_DEPLOY_SKIP_PRS` to a single PR number or comma-separated list: -```bash +```shell # Skip a single PR VORTEX_DEPLOY_ALLOW_SKIP=1 VORTEX_DEPLOY_SKIP_PRS=42 @@ -105,7 +106,7 @@ VORTEX_DEPLOY_SKIP_PRS=42,123,456 Set `$VORTEX_DEPLOY_SKIP_BRANCHES` to a single branch name or comma-separated list: -```bash +```shell # Skip a single branch VORTEX_DEPLOY_ALLOW_SKIP=1 VORTEX_DEPLOY_SKIP_BRANCHES=feature/test @@ -119,8 +120,18 @@ VORTEX_DEPLOY_SKIP_BRANCHES=feature/test,hotfix/urgent,project/experimental You can use both variables together: -```bash +```shell VORTEX_DEPLOY_ALLOW_SKIP=1 VORTEX_DEPLOY_SKIP_PRS=42,123 VORTEX_DEPLOY_SKIP_BRANCHES=feature/test,hotfix/urgent ``` + +## See also + +| Topic | Description | +|-------|-------------| +| [Webhook](webhook) | Deploy by calling a webhook URL | +| [Artifact](artifact) | Deploy code artifacts to remote repositories | +| [Lagoon](lagoon) | Deploy to Lagoon hosting platform | +| [Docker](docker) | Deploy container images to registries | +| [Notifications](notifications) | Send deployment notifications | diff --git a/.vortex/docs/content/deployment/artifact.mdx b/.vortex/docs/content/deployment/artifact.mdx new file mode 100644 index 000000000..7a02d25f9 --- /dev/null +++ b/.vortex/docs/content/deployment/artifact.mdx @@ -0,0 +1,90 @@ +--- +sidebar_label: Artifact +sidebar_position: 3 +--- + +# Artifact deployment + +Artifact deployment packages your codebase and pushes it to a remote Git +repository. This is commonly used for hosting platforms like Acquia that +require pre-built code artifacts. + +## How it works + +When `artifact` is included in `$VORTEX_DEPLOY_TYPES`, the deployment script: + +1. Creates a clean code artifact using [Git Artifact](/docs/tools/git-artifact) +2. Applies the `.gitignore.artifact` rules to control which files are included +3. Pushes the artifact to the configured remote repository +4. The hosting platform then deploys from that repository + +## Configuration + +### Environment variables + +| Variable | Required | Default | Location | Description | +|----------|----------|---------|----------|-------------| +| `VORTEX_DEPLOY_ARTIFACT_GIT_REMOTE` | **Yes** | | `.env` | Remote repository URL for the artifact | +| `VORTEX_DEPLOY_ARTIFACT_ROOT` | No | Current directory | `.env` | Root directory for artifact creation | +| `VORTEX_DEPLOY_ARTIFACT_SRC` | No | Current directory | `.env` | Source directory to package | +| `VORTEX_DEPLOY_ARTIFACT_DST` | No | `.artifact` | `.env` | Destination directory for artifact | +| `VORTEX_DEPLOY_ARTIFACT_GIT_USER_NAME` | **Yes** | | CI | Git user name for commits | +| `VORTEX_DEPLOY_ARTIFACT_GIT_USER_EMAIL` | **Yes** | | CI | Git user email for commits | +| `VORTEX_DEPLOY_ARTIFACT_LOG` | No | | `.env` | Log file path | + +### Setup + +1. Add `artifact` to the `VORTEX_DEPLOY_TYPES` variable in your `.env` file: + + ```shell title=".env" + VORTEX_DEPLOY_TYPES=artifact + ``` + +2. Configure the artifact remote repository: + + ```shell title=".env" + VORTEX_DEPLOY_ARTIFACT_GIT_REMOTE=git@github.com:your-org/your-project-artifact.git + ``` + +3. Add Git user credentials to your CI provider's environment variables: + + ```shell + VORTEX_DEPLOY_ARTIFACT_GIT_USER_NAME="Deployment Bot" + VORTEX_DEPLOY_ARTIFACT_GIT_USER_EMAIL="deploy@example.com" + ``` + +## Artifact file control + +The `.gitignore.artifact` file controls which files are included in or excluded +from the artifact. This file replaces the standard `.gitignore` in the artifact +repository. + +**Vortex** provides a +[pre-configured `.gitignore.artifact`](https://github.com/drevops/vortex/blob/main/.gitignore.artifact) +that includes all required files for a production Drupal site while excluding +development dependencies. + +### Customizing the artifact + +Edit `.gitignore.artifact` to add or remove files from the artifact: + +```shell title=".gitignore.artifact" +# Include compiled assets +!/web/themes/custom/*/dist + +# Exclude test files +/tests +/behat.yml +/phpunit.xml +``` + +## Use cases + +- **Acquia hosting** - Acquia requires code artifacts pushed to their Git repository +- **Pantheon hosting** - Similar artifact-based deployment model +- **Custom hosting** - Any platform that deploys from a Git repository + +## See also + +- [Git Artifact tool](/docs/tools/git-artifact) - Detailed documentation on the artifact tool +- [Acquia hosting](/docs/hosting/acquia) - Acquia-specific deployment configuration diff --git a/.vortex/docs/content/deployment/docker.mdx b/.vortex/docs/content/deployment/docker.mdx new file mode 100644 index 000000000..e059f3a51 --- /dev/null +++ b/.vortex/docs/content/deployment/docker.mdx @@ -0,0 +1,81 @@ +--- +sidebar_label: Docker +sidebar_position: 5 +--- + +# Docker deployment + +Docker deployment builds container images and pushes them to a remote +container registry. + +## How it works + +When `docker` is included in `$VORTEX_DEPLOY_TYPES`, the deployment script: + +1. Builds Docker images for your services using `docker-compose.yml` +2. Tags images with the deployment reference (branch, tag, or commit) +3. Pushes images to the configured container registry +4. The hosting platform pulls and deploys the new images + +## Configuration + +### Environment variables + +| Variable | Required | Default | Location | Description | +|----------|----------|---------|----------|-------------| +| `VORTEX_DEPLOY_CONTAINER_REGISTRY` | **Yes** | | `.env` | Registry URL (e.g., `docker.io`, `ghcr.io`) | +| `VORTEX_DEPLOY_CONTAINER_REGISTRY_USER` | **Yes** | | CI | Registry username | +| `VORTEX_DEPLOY_CONTAINER_REGISTRY_PASS` | **Yes** | | CI | Registry password or token | +| `VORTEX_DEPLOY_CONTAINER_REGISTRY_IMAGE` | No | Project name | `.env` | Base image name | + +### Setup + +1. Add `docker` to the `VORTEX_DEPLOY_TYPES` variable in your `.env` file: + + ```shell title=".env" + VORTEX_DEPLOY_TYPES=docker + ``` + +2. Configure your container registry: + + ```shell title=".env" + VORTEX_DEPLOY_CONTAINER_REGISTRY=ghcr.io + VORTEX_DEPLOY_CONTAINER_REGISTRY_IMAGE=your-org/your-project + ``` + +3. Add registry credentials to your CI provider's environment variables: + + ```shell + VORTEX_DEPLOY_CONTAINER_REGISTRY_USER=your-username + VORTEX_DEPLOY_CONTAINER_REGISTRY_PASS=your-token + ``` + +## Image tagging + +Images are tagged based on the deployment context: + +| Context | Tag format | Example | +|---------|-----------|---------| +| Branch | Branch name (sanitized) | `develop`, `feature-auth` | +| Tag | Tag name | `1.0.0`, `v2.1.0` | +| PR | `pr-{number}` | `pr-123` | +| Commit | Short SHA | `abc1234` | + +## Supported registries + +- **Docker Hub** (`docker.io`) +- **GitHub Container Registry** (`ghcr.io`) +- **AWS ECR** (`*.dkr.ecr.*.amazonaws.com`) +- **Google Container Registry** (`gcr.io`) +- **Azure Container Registry** (`*.azurecr.io`) +- Any OCI-compliant registry + +## Use cases + +- **Kubernetes deployments** - Pull images from registry to deploy +- **Container orchestration platforms** - AWS ECS, Google Cloud Run, etc. +- **Custom infrastructure** - Any system that can pull and run Docker images + +## See also + +- [Docker tool](/docs/tools/docker) - Docker configuration in Vortex diff --git a/.vortex/docs/content/deployment/lagoon.mdx b/.vortex/docs/content/deployment/lagoon.mdx new file mode 100644 index 000000000..e57c4ecc2 --- /dev/null +++ b/.vortex/docs/content/deployment/lagoon.mdx @@ -0,0 +1,75 @@ +--- +sidebar_label: Lagoon +sidebar_position: 4 +--- + +# Lagoon deployment + +Lagoon deployment triggers a deployment on the [Lagoon](https://lagoon.sh/) +hosting platform by calling its webhook URL. + +## How it works + +When `lagoon` is included in `$VORTEX_DEPLOY_TYPES`, the deployment script +calls the Lagoon webhook URL to trigger a deployment. Lagoon then: + +1. Pulls the latest code from your repository +2. Builds container images using your `docker-compose.yml` +3. Deploys containers to Kubernetes +4. Runs post-rollout tasks defined in `.lagoon.yml` + +## Configuration + +### Environment variables + +| Variable | Required | Default | Location | Description | +|----------|----------|---------|----------|-------------| +| `LAGOON_PROJECT` | **Yes** | | `.env` | Your Lagoon project name | +| `VORTEX_DEPLOY_LAGOON_INSTANCE` | No | `amazeeio` | `.env` | Lagoon instance name | +| `VORTEX_DEPLOY_LAGOON_INSTANCE_GRAPHQL` | No | Auto-generated | `.env` | Lagoon GraphQL endpoint | +| `VORTEX_DEPLOY_LAGOON_INSTANCE_HOSTNAME` | No | Auto-generated | `.env` | Lagoon SSH hostname | +| `VORTEX_DEPLOY_LAGOON_INSTANCE_PORT` | No | Auto-generated | `.env` | Lagoon SSH port | +| `VORTEX_DEPLOY_LAGOON_BRANCH` | No | Current branch | CI | Branch to deploy | + +### Setup + +1. Add `lagoon` to the `VORTEX_DEPLOY_TYPES` variable in your `.env` file: + + ```shell title=".env" + VORTEX_DEPLOY_TYPES=lagoon + ``` + +2. Configure your Lagoon project name: + + ```shell title=".env" + LAGOON_PROJECT=your-project-name + ``` + +3. Ensure your CI has the Lagoon SSH key configured for authentication. + +## Post-deployment automation + +When code is deployed, Vortex automatically: + +1. **Provisions the site** - Runs database updates, imports configuration, clears caches +2. **Sends notifications** - Notifies configured channels about the deployment + +This is implemented using post-rollout tasks defined in the +[`.lagoon.yml`](https://github.com/drevops/vortex/blob/main/.lagoon.yml) +configuration file. + +## Environment types + +Lagoon creates different environment types based on your branch: + +| Branch pattern | Environment type | +|---------------|------------------| +| `main`, `master` | Production | +| `develop` | Development | +| `release/*`, `hotfix/*` | Staging | +| Pull requests | Development (ephemeral) | + +## See also + +- [Lagoon hosting](/docs/hosting/lagoon) - Detailed Lagoon hosting configuration +- [Lagoon documentation](https://docs.lagoon.sh/) - Official Lagoon docs diff --git a/.vortex/docs/content/deployment/notifications.mdx b/.vortex/docs/content/deployment/notifications.mdx new file mode 100644 index 000000000..9721d63b2 --- /dev/null +++ b/.vortex/docs/content/deployment/notifications.mdx @@ -0,0 +1,258 @@ +--- +sidebar_label: Notifications +sidebar_position: 6 +--- + +# Notifications + +**Vortex** provides a flexible notification system that sends updates +across multiple channels when deployments occur. + +Notifications are triggered automatically during deployment to a +hosting environment. + +## Channels + +Configure notification channels in your `.env` file: + +```shell title=".env" +# Enable notification channels (comma-separated list) +VORTEX_NOTIFY_CHANNELS=email,slack,github +``` + +Available channels: `email`, `github`, `jira`, `newrelic`, `slack`, `webhook` + +## Global environment variables + +These variables apply to all notification channels unless overridden by +channel-specific settings. + +| Variable | Required | Default | Location | Description | +|----------|----------|---------|----------|-------------| +| `VORTEX_NOTIFY_CHANNELS` | No | `email` | `.env` | Notification channels (comma-separated) | +| `VORTEX_NOTIFY_PROJECT` | No | `VORTEX_PROJECT` | `.env` | Notification project name | +| `VORTEX_NOTIFY_SKIP` | No | | Hosting | Set to `1` to skip notifications | + +## Deployment context variables + +These variables provide deployment context information used by notification +channels. They must be set by the hosting environment before calling the +notification script. + +| Variable | Required | Description | +|----------|----------|-------------| +| `VORTEX_NOTIFY_BRANCH` | **Yes** | Git branch name | +| `VORTEX_NOTIFY_SHA` | **Yes** | Git commit SHA | +| `VORTEX_NOTIFY_PR_NUMBER` | No | Pull request number (empty for branch deployments) | +| `VORTEX_NOTIFY_LABEL` | **Yes** | Human-readable deployment label | + +## Message templates and tokens + +Most notification channels support customizable message templates using replacement tokens: + +| Token | Description | Example | +|-------|-------------|---------| +| `%project%` | Project name | `My Project` | +| `%label%` | Deployment label | `main` or `PR-123` | +| `%timestamp%` | Current timestamp | `15/11/2025 14:30:45 UTC` | +| `%environment_url%` | Environment URL | `https://example.com` | +| `%login_url%` | Login URL | `https://example.com/user/login` | + +**Default message template:** + +```text +## This is an automated message ## + +Site %project% %label% has been deployed at %timestamp% and is available at %environment_url%. + +Login at: %login_url% +``` + +--- + +## Email + +Send deployment notification via email. + +### Setup + +1. Add `VORTEX_NOTIFY_EMAIL_FROM` variable to `.env` file with the sender email address. +2. Add `VORTEX_NOTIFY_EMAIL_RECIPIENTS` variable to `.env` file with recipients + in format `email|name` (comma-separated for multiple). + +### Environment variables + +| Variable | Required | Default | Location | Description | +|----------|----------|---------|----------|-------------| +| `VORTEX_NOTIFY_EMAIL_FROM` | **Yes** | | `.env` | Sender email address | +| `VORTEX_NOTIFY_EMAIL_RECIPIENTS` | **Yes** | | `.env` | Recipients (format: `email\|name`) | +| `VORTEX_NOTIFY_EMAIL_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | `.env` | Project name for email | +| `VORTEX_NOTIFY_EMAIL_MESSAGE` | No | Default template | `.env` | Custom message template | + +--- + +## GitHub + +Post deployment status to GitHub pull requests. + +### Setup + +1. [Create a GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). +2. Add `VORTEX_NOTIFY_GITHUB_TOKEN` to your hosting provider's environment variables. +3. Add `VORTEX_NOTIFY_GITHUB_REPOSITORY` to your hosting provider's environment variables. + +### Environment variables + +| Variable | Required | Default | Location | Description | +|----------|----------|---------|----------|-------------| +| `VORTEX_NOTIFY_GITHUB_TOKEN` | **Yes** | | Hosting | GitHub personal access token | +| `VORTEX_NOTIFY_GITHUB_REPOSITORY` | **Yes** | | Hosting | Repository in `owner/repo` format | +| `VORTEX_NOTIFY_GITHUB_ENVIRONMENT_TYPE` | No | `PR` | `.env` | Environment type | + +### Example + +The pull request page shows deployment status with a **View deployment** button +to quickly access the deployed environment. + +![notification-github-after.png](/img/notification-github-after.png) + +--- + +## JIRA + +Post a deployment comment and optionally update issue status and assignee. + +### Setup + +1. [Create a JIRA API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/). +2. Add `VORTEX_NOTIFY_JIRA_TOKEN` to your hosting provider's environment variables. +3. Add `VORTEX_NOTIFY_JIRA_USER_EMAIL` to your `.env` file. + +### Environment variables + +| Variable | Required | Default | Location | Description | +|----------|----------|---------|----------|-------------| +| `VORTEX_NOTIFY_JIRA_TOKEN` | **Yes** | | Hosting | JIRA API token | +| `VORTEX_NOTIFY_JIRA_USER_EMAIL` | **Yes** | | `.env` | JIRA user email | +| `VORTEX_NOTIFY_JIRA_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | `.env` | Project name | +| `VORTEX_NOTIFY_JIRA_MESSAGE` | No | Default template | `.env` | Custom message template | +| `VORTEX_NOTIFY_JIRA_ASSIGNEE_EMAIL` | No | | `.env` | Assignee email after deployment | +| `VORTEX_NOTIFY_JIRA_TRANSITION` | No | | `.env` | Transition name (e.g., "In Review") | +| `VORTEX_NOTIFY_JIRA_ENDPOINT` | No | `https://jira.atlassian.com` | `.env` | JIRA API endpoint | + +### Issue key extraction + +The notification system automatically extracts JIRA issue keys from the +deployment label using the pattern `[A-Za-z0-9]+-[0-9]+`: + +- `feature/PROJ-123-add-feature` → `PROJ-123` +- `feature/PRJ-456-fix-auth` → `PRJ-456` + +--- + +## New Relic + +Create [deployment markers](https://docs.newrelic.com/docs/apm/apm-ui-pages/events/record-deployments/) +in New Relic APM to track code changes alongside performance data. + +### Setup + +1. [Create a New Relic User API Key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#user-key) + (format: `NRAK-XXXXXXXXXXXXXXXXXXXXXX`). +2. Add `NEWRELIC_ENABLED` (or `VORTEX_NOTIFY_NEWRELIC_ENABLED`) to hosting environment + variables for environments where New Relic is configured. +3. Add `VORTEX_NOTIFY_NEWRELIC_USER_KEY` to your hosting provider's environment variables. + +:::tip Enable only where needed + +Set `NEWRELIC_ENABLED=true` only in environments where New Relic APM is configured +(typically production and staging). This avoids API calls and potential errors +in development or feature branch environments. + +::: + +### Environment variables + +| Variable | Required | Default | Location | Description | +|----------|----------|---------|----------|-------------| +| `VORTEX_NOTIFY_NEWRELIC_ENABLED` | **Yes** | `NEWRELIC_ENABLED` | Hosting | Enable New Relic notifications | +| `VORTEX_NOTIFY_NEWRELIC_USER_KEY` | **Yes** | | Hosting | New Relic User API Key | +| `VORTEX_NOTIFY_NEWRELIC_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | `.env` | Project name | +| `VORTEX_NOTIFY_NEWRELIC_APP_NAME` | No | Auto-generated | `.env` | Application name | +| `VORTEX_NOTIFY_NEWRELIC_DESCRIPTION` | No | Default template | `.env` | Deployment description | +| `VORTEX_NOTIFY_NEWRELIC_CHANGELOG` | No | Description | `.env` | Deployment changelog | +| `VORTEX_NOTIFY_NEWRELIC_USER` | No | `Deployment robot` | `.env` | User performing deployment | +| `VORTEX_NOTIFY_NEWRELIC_ENDPOINT` | No | `https://api.newrelic.com/v2` | `.env` | API endpoint | + +### Example + +New Relic deployment marker + +--- + +## Slack + +Post deployment notifications to a Slack channel. + +### Setup + +1. [Create a Slack app and Incoming Webhook](https://api.slack.com/messaging/webhooks). +2. Add `VORTEX_NOTIFY_SLACK_WEBHOOK` to your hosting provider's environment variables. + +### Environment variables + +| Variable | Required | Default | Location | Description | +|----------|----------|---------|----------|-------------| +| `VORTEX_NOTIFY_SLACK_WEBHOOK` | **Yes** | | Hosting | Slack webhook URL | +| `VORTEX_NOTIFY_SLACK_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | `.env` | Project name | +| `VORTEX_NOTIFY_SLACK_MESSAGE` | No | Default template | `.env` | Fallback text template | +| `VORTEX_NOTIFY_SLACK_CHANNEL` | No | | `.env` | Target channel (overrides webhook default) | +| `VORTEX_NOTIFY_SLACK_USERNAME` | No | `Deployment Bot` | `.env` | Bot display name | +| `VORTEX_NOTIFY_SLACK_ICON_EMOJI` | No | `:rocket:` | `.env` | Bot icon emoji | + +### Event behavior + +Slack notifications are sent for both `pre_deployment` and `post_deployment` events: + +- **Pre-deployment:** Gray color with "Deployment Starting" status +- **Post-deployment:** Green color with "Deployment Complete" status + +### Example + +Slack notification - Deployment Complete + +--- + +## Webhook + +Send HTTP requests to arbitrary webhook URLs. + +### Setup + +1. Add `VORTEX_NOTIFY_WEBHOOK_URL` to your `.env` file or hosting environment variables. + +### Environment variables + +| Variable | Required | Default | Location | Description | +|----------|----------|---------|----------|-------------| +| `VORTEX_NOTIFY_WEBHOOK_URL` | **Yes** | | `.env` or Hosting | Webhook endpoint URL | +| `VORTEX_NOTIFY_WEBHOOK_METHOD` | No | `POST` | `.env` | HTTP method | +| `VORTEX_NOTIFY_WEBHOOK_HEADERS` | No | `Content-Type: application/json` | `.env` | Pipe-separated headers | +| `VORTEX_NOTIFY_WEBHOOK_PAYLOAD` | No | Default template | `.env` | JSON payload | +| `VORTEX_NOTIFY_WEBHOOK_RESPONSE_STATUS` | No | `200` | `.env` | Expected HTTP status | + +### Default payload template + +```json +{ + "channel": "Channel 1", + "message": "%message%", + "project": "%project%", + "label": "%label%", + "timestamp": "%timestamp%", + "environment_url": "%environment_url%", + "login_url": "%login_url%" +} +``` + +The `%message%` token expands to the full deployment message with all other tokens replaced. diff --git a/.vortex/docs/content/deployment/webhook.mdx b/.vortex/docs/content/deployment/webhook.mdx new file mode 100644 index 000000000..29077c1e0 --- /dev/null +++ b/.vortex/docs/content/deployment/webhook.mdx @@ -0,0 +1,44 @@ +--- +sidebar_label: Webhook +sidebar_position: 2 +--- + +# Webhook deployment + +Webhook deployment triggers a remote deployment by calling an HTTP endpoint. + +This is useful for integrating with external systems or custom deployment +pipelines that expose webhook URLs. + +## How it works + +When `webhook` is included in `$VORTEX_DEPLOY_TYPES`, the deployment script +calls the configured webhook URL using CURL, passing deployment information +as parameters. + +## Configuration + +### Environment variables + +| Variable | Required | Default | Location | Description | +|----------|----------|---------|----------|-------------| +| `VORTEX_DEPLOY_WEBHOOK_URL` | **Yes** | | Hosting/CI | The webhook URL to call | +| `VORTEX_DEPLOY_WEBHOOK_METHOD` | No | `GET` | `.env` | HTTP method (GET, POST) | +| `VORTEX_DEPLOY_WEBHOOK_RESPONSE_STATUS` | No | `200` | `.env` | Expected HTTP response status code | + +### Setup + +1. Add `webhook` to the `VORTEX_DEPLOY_TYPES` variable in your `.env` file: + + ```shell title=".env" + VORTEX_DEPLOY_TYPES=webhook + ``` + +2. Add `VORTEX_DEPLOY_WEBHOOK_URL` to your CI provider's environment variables + (this should be kept secret). + +## Use cases + +- Triggering deployments on platforms that provide webhook endpoints +- Integrating with custom deployment orchestration systems +- Notifying external services when code is ready for deployment diff --git a/.vortex/docs/content/development/README.mdx b/.vortex/docs/content/development/README.mdx new file mode 100644 index 000000000..8ed357721 --- /dev/null +++ b/.vortex/docs/content/development/README.mdx @@ -0,0 +1,283 @@ +--- +sidebar_label: Overview +sidebar_position: 1 +--- + +# Development + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Typical development process + +1. Pull the latest changes from the remote repository. +2. Fetch the latest database dump from the production environment. +3. Build the project. +4. Start a new feature or bugfix branch: + - Create a new branch from `develop`. + - Implement the feature or fix the bug. +5. Run tests: + - Run automated tests locally. + - Fix any failing tests. +6. Run code quality checks: + - Run static code analysis locally. + - Fix any issues reported. +7. Commit changes to the branch and push it to the remote repository. +8. Create a pull request: + - Create a pull request from the branch to `develop`. + - Assign reviewers. + - Wait for the continuous integration pipeline to pass. + +## Running CLI commands + +You can run CLI commands inside the project containers. + + + + ```shell + # Run a command in the CLI container + ahoy cli echo "Hello, World!" + # SSH into the CLI container + ahoy cli + ``` + + + ```shell + # Run a command in the CLI container + docker compose exec cli echo "Hello, World!" + # SSH into the CLI container + docker compose exec cli bash + ``` + + + +You can also use shortcuts for common commands: + + + + ```shell + # Run Drush command + ahoy drush status + # Run Composer command + ahoy composer install + ``` + + + ```shell + # Run Drush command + docker compose exec cli drush status + # Run Composer command + docker compose exec cli composer install + ``` + + + +## Switching branches + +When switching to a new branch, there is no need to rebuild the entire project +as it may take a long time. Instead, you can run these commands as needed based +on what changed: + + + + ```shell + # Update Composer dependencies (only if composer.json/composer.lock changed) + ahoy composer install + # Rebuild frontend assets (only if theme files changed) + ahoy fe + # Provision site (only if database or configuration changes expected) + ahoy provision + ``` + + + ```shell + # Update Composer dependencies (only if composer.json/composer.lock changed) + docker compose exec cli composer install + # Rebuild frontend assets (only if theme files changed) + docker compose exec cli bash -c "cd \${WEBROOT}/themes/custom/\${DRUPAL_THEME} && yarn run build" + # Provision site (only if database or configuration changes expected) + docker compose exec cli ./scripts/vortex/provision.sh + ``` + + + +## Resetting the codebase + +To reset the local environment, use the reset command. This will stop and remove +all containers and downloaded dependency packages (`vendor`, `node_modules` etc.). + + + + ```shell + # Reset local environment + ahoy reset + # Fully reset repository to a state as if it was just cloned + ahoy reset hard + ``` + + + ```shell + # Reset local environment + docker compose down + ./scripts/vortex/reset.sh + # Fully reset repository to a state as if it was just cloned + docker compose down + ./scripts/vortex/reset.sh hard + ``` + + + +## Environment variables + +To update environment variables in your local development environment: + +1. Edit variables in `.env.local` file +2. Apply changes by restarting containers: + + + + ```shell + ahoy restart + ``` + + + ```shell + docker compose up -d + ``` + + + +➡️ See [Variables](./variables.mdx) for comprehensive variable reference. + +## Performance optimization + + + + ```shell + # Enable CSS/JS aggregation + ahoy drush config:set system.performance css.preprocess 1 + ahoy drush config:set system.performance js.preprocess 1 + # Clear render cache + ahoy drush cache:rebuild-external + # Check database updates needed + ahoy drush updatedb:status + ``` + + + ```shell + # Enable CSS/JS aggregation + docker compose exec cli drush config:set system.performance css.preprocess 1 + docker compose exec cli drush config:set system.performance js.preprocess 1 + # Clear render cache + docker compose exec cli drush cache:rebuild-external + # Check database updates needed + docker compose exec cli drush updatedb:status + ``` + + + +## Common issues & solutions + +### Site not loading + + + + ```shell + ahoy doctor # Check for common issues + ahoy down && ahoy up # Restart containers + ahoy info # Verify URLs and ports + ``` + + + ```shell + ./scripts/vortex/doctor.sh # Check for common issues + docker compose down && docker compose up -d # Restart containers + docker compose exec cli ./scripts/vortex/info.sh # Verify URLs and ports + ``` + + + +### Database connection errors + + + + ```shell + docker compose ps # Check if database container is running + ahoy reset # Nuclear option: rebuild everything + ``` + + + ```shell + docker compose ps # Check if database container is running + docker compose down --volumes && docker compose up -d # Nuclear option + ``` + + + +### Permission issues + +```shell +# Fix file permissions (Linux/Mac) +sudo chown -R $USER:$USER . +``` + +### Memory issues during composer install + + + + ```shell + # Increase PHP memory temporarily + ahoy composer install --no-dev --optimize-autoloader + ``` + + + ```shell + # Increase PHP memory temporarily + docker compose exec cli composer install --no-dev --optimize-autoloader + ``` + + + +## Log files + + + + ```shell + # View ahoy logs + ahoy logs + # Check container logs + docker compose logs --tail=50 cli + # View Drupal watchdog logs + ahoy drush watchdog:show --count=20 + ``` + + + ```shell + # Check container logs + docker compose logs --tail=50 cli + # View Drupal watchdog logs + docker compose exec cli drush watchdog:show --count=20 + ``` + + + +## Beyond local development + +
+Expand to see the complete code lifecycle + +import CodeLifecycle from '../_code-lifecycle.mdx'; + + + +
+ +## See also + +| Topic | Description | +|-------|-------------| +| [Database](database) | Fetching, refreshing, and exporting databases | +| [Composer](composer) | Managing packages, patching, security auditing | +| [Debugging](debugging) | Xdebug, curl testing, container access | +| [PHPUnit](phpunit) | Unit, Kernel, and Functional testing | +| [Behat](behat) | Behavior-Driven Development (BDD) testing | diff --git a/.vortex/docs/content/workflows/testing.mdx b/.vortex/docs/content/development/behat.mdx similarity index 56% rename from .vortex/docs/content/workflows/testing.mdx rename to .vortex/docs/content/development/behat.mdx index ab1d0bb5a..6be4da8a4 100644 --- a/.vortex/docs/content/workflows/testing.mdx +++ b/.vortex/docs/content/development/behat.mdx @@ -1,13 +1,28 @@ --- -sidebar_position: 2 +sidebar_label: Behat +sidebar_position: 6 --- -# Testing +# Behat -**Vortex** supports running Unit, Kernel, Functional, and BDD tests. +**Vortex** uses [Behat](https://behat.org) for Behavior-Driven Development (BDD) +testing. Behat allows to write human-readable stories that describe the behavior +of the application. Behat tests primarily focus on critical user journeys, +serving as comprehensive end-to-end validations. + +**Vortex** provides full Behat support, including configuration in [`behat.yml`](https://github.com/drevops/vortex/blob/main/behat.yml) +and a [browser container](https://github.com/drevops/vortex/blob/main/docker-compose.yml) to run tests interactively in a real browser with +a VNC viewer. + +Additional features include: + +1. [Behat Drupal Extension](https://github.com/drupalprojects/drupalextension) - an extension to work with Drupal. +2. [Behat Steps](https://github.com/drevops/behat-steps) - a library of re-usable Behat steps. +3. [Behat Screenshot](https://github.com/drevops/behat-screenshot) - extension to capture screenshots on-demand and on failure. +4. [Behat Progress formatter](https://github.com/drevops/behat-format-progress-fail) - extension to show progress as TAP and failures inline. +5. Parallel profiles - configuration to allow running tests in parallel. -For local development, the tests can be run directly or using handy Ahoy -commands: +## Running tests import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -15,97 +30,51 @@ import TabItem from '@theme/TabItem'; ```shell - ahoy test # Run Unit, Kernel and Functional tests - ahoy test-unit # Run Unit tests - ahoy test-kernel # Run Kernel tests - ahoy test-functional # Run Functional tests - ahoy test-bdd # Run BDD tests + # Run all Behat tests + ahoy test-bdd + # Run specific feature file + ahoy test-bdd tests/behat/features/homepage.feature + # Run scenarios with specific tag + ahoy test-bdd -- --tags=@smoke ``` ```shell - docker compose exec cli vendor/bin/phpunit # Run Unit, Kernel and Functional tests - docker compose exec cli vendor/bin/phpunit --testsuite=unit # Run Unit tests - docker compose exec cli vendor/bin/phpunit --testsuite=kernel # Run Kernel tests - docker compose exec cli vendor/bin/phpunit --testsuite=functional # Run Functional tests - docker compose exec cli vendor/bin/behat # Run BDD tests + # Run all Behat tests + docker compose exec cli vendor/bin/behat + # Run specific feature file + docker compose exec cli vendor/bin/behat tests/behat/features/homepage.feature + # Run scenarios with specific tag + docker compose exec cli vendor/bin/behat -- --tags=@smoke ``` -In continuous integration pipelines, tests are run by calling the test binaries -directly. - -## Unit testing - -**Vortex** uses PHPUnit as a framework for Unit testing. - -It is configured to use a copy of Drupal core's `core/phpunit.xml.dist` -configuration file to allow customizing the test suite per project. - -### Reporting - -Test reports are stored in `.logs/phpunit` directory -separated into multiple files and named after the suite name. -These reports are usually used in continuous integration to track tests performance and stability. - -### Boilerplate - -**Vortex** provides Unit, Kernel and Functional tests boilerplate for custom [modules](https://github.com/drevops/vortex/blob/main/web/modules/custom/ys_base/tests/src), -[themes](https://github.com/drevops/vortex/blob/main/web/themes/custom/your_site_theme/tests/src) and -[scripts](https://github.com/drevops/vortex/blob/main/tests/phpunit). - -These boilerplate tests run in continuous integration pipeline when you install -**Vortex** and can be used as a starting point for writing your own. - -#### Drupal settings tests - -**Vortex** provides [Drupal settings tests](https://github.com/drevops/vortex/blob/main/tests/phpunit/Drupal/DrupalSettingsTest.php) -to check that Drupal settings are correct based on the environment type the site -is running: with the number of custom modules multiplied by the number of -environment types, it is easy to miss certain settings which may lead to -unexpected issues when deploying a project to a different environment. - -It is intended to be used in your site and kept up-to-date with the -changes made to the `settings.php` file. - -#### Continuous integration pipeline configuration tests - -**Vortex** provides a [continuous integration pipeline configuration tests](https://github.com/drevops/vortex/blob/main/tests/phpunit/CircleCiConfigTest.php) -to check that the continuous integration configuration is correct. It is -intended to be used in your site and kept up-to-date with the continuous -integration configurations. +### Discovering available step definitions -For example, there are tests for regular expressions used to filter the branches -and tags before they are deployed to the hosting environment. - -## BDD testing - -**Vortex** uses [Behat](https://behat.org) for Behavior-Driven Development (BDD) -testing. Behat allows to write human-readable stories that describe the behavior -of the application. Behat tests primarily focus on critical user journeys, -serving as comprehensive end-to-end validations. - -**Vortex** provides full Behat support, including configuration in [`behat.yml`](https://github.com/drevops/vortex/blob/main/behat.yml) -and a [browser container](https://github.com/drevops/vortex/blob/main/docker-compose.yml) to run tests interactively in a real browser with -a VNC viewer. - -Additional features include: - -1. [Behat Drupal Extension](https://github.com/drupalprojects/drupalextension) - an extension to work with Drupal. -2. [Behat Steps](https://github.com/drevops/behat-steps) - a library of re-usable Behat steps. -3. [Behat Screenshot](https://github.com/drevops/behat-screenshot) - extension to capture screenshots on-demand and on failure. -4. [Behat Progress formatter](https://github.com/drevops/behat-format-progress-fail) - extension to show progress as TAP and failures inline. -5. Parallel profiles - configuration to allow running tests in parallel. + + + ```shell + # Generate step definitions reference + ahoy test-bdd -- --definitions=l + ``` + + + ```shell + # Generate step definitions reference + docker compose exec cli vendor/bin/behat -- --definitions=l + ``` + + -### FeatureContext +## FeatureContext The [`FeatureContext.php`](https://github.com/drevops/vortex/blob/main/tests/behat/bootstrap/FeatureContext.php) file comes with included steps from [Behat steps](https://github.com/drevops/behat-steps) package. You can add your custom steps into this file. -### Profiles +## Profiles Behat's `default` profile configured with sensible defaults to allow running it with provided extensions. @@ -113,7 +82,7 @@ with provided extensions. In continuous integration environment, the profile can be overridden using \ `$VORTEX_CI_BEHAT_PROFILE` environment variable. -### Parallel runs +## Parallel runs In continuous integration pipeline, Behat tests can run within multiple runners to increase the speed of the test suite. To achieve this, Behat tags are used to @@ -133,11 +102,11 @@ even if you forget to tag the feature, it will still be allocated to a runner. If CI pipeline has only one runner - a `default` profile will be used and all tests (except for those that tagged with `@skipped`) will be run. -### Skipping tests +## Skipping tests Add `@skipped` tag to a feature or scenario to exclude it from the test run. -### Screenshots +## Screenshots Test screenshots are stored into `.logs/screenshots` location by default, which can be overwritten using `$BEHAT_SCREENSHOT_DIR` variable (courtesy of @@ -147,20 +116,20 @@ In continuous integration pipeline, screenshots are stored as build artifacts. In GitHub Actions, they can be downloaded from the `Summary` tab. In CircleCI they are accessible in the `Artifacts` tab. -### Format +## Format Out of the box, **Vortex** comes with [Behat Progress formatter](https://github.com/drevops/behat-format-progress-fail) output formatter to show progress as TAP and failures inline. This allows to continue test runs after a failure while maintaining a minimal output. -### Reporting +## Reporting Test reports are stored in `.logs/behat` directory. Continuous integration pipeline usually uses them to track test performance and stability. -### Boilerplate test features +## Boilerplate test features **Vortex** provides BDD [tests boilerplate](https://github.com/drevops/vortex/blob/main/tests/behat/features) for [homepage](https://github.com/drevops/vortex/blob/main/tests/behat/features/homepage.feature) and [login](https://github.com/drevops/vortex/blob/main/tests/behat/features/login.feature) @@ -168,3 +137,11 @@ user journeys. These boilerplate tests run in continuous integration pipeline when you install **Vortex** and can be used as a starting point for writing your own. + +## Writing tests + +For project-specific test writing conventions (user story format, standard user +types, test data conventions), see your project's `docs/testing.md` file. + +The `docs/testing.md` file is scaffolded when you install **Vortex** and should +be maintained by your project team to document agreed-upon testing practices. diff --git a/.vortex/docs/content/workflows/development.mdx b/.vortex/docs/content/development/composer.mdx similarity index 56% rename from .vortex/docs/content/workflows/development.mdx rename to .vortex/docs/content/development/composer.mdx index 53cf29edd..1043c1a38 100644 --- a/.vortex/docs/content/workflows/development.mdx +++ b/.vortex/docs/content/development/composer.mdx @@ -1,152 +1,44 @@ --- -sidebar_position: 1 +sidebar_label: Composer +sidebar_position: 3 --- -# Development - -## Typical development workflow - -1. Pull the latest changes from the remote repository. -2. Fetch the latest database dump from the production environment with `ahoy fetch-db`. -3. Build the project with `ahoy build`. -4. Start a new feature or bugfix branch: - - Create a new branch from `develop`. - - Implement the feature or fix the bug. -5. Run tests: - - Run automated tests locally. - - Fix any failing tests. -6. Run code quality checks: - - Run static code analysis locally. - - Fix any issues reported. -7. Commit changes to the branch and push it to the remote repository. -8. Create a pull request: - - Create a pull request from the branch to `develop`. - - Assign reviewers. - - Wait for the continuous integration pipeline to pass. - -## Running CLI commands - -You can run CLI commands inside the project containers using `ahoy` command -wrapper. - -```bash -# Run a command in the CLI container -ahoy cli echo "Hello, World!" -``` - -To SSH into the CLI container: - -```bash -ahoy cli -``` - -You can also use shortcuts for common commands: - -```bash -# Run Drush command -ahoy drush status - -# Run Composer command -ahoy composer install -``` - -## Switching branches - -When switching to a new branch, there is no need to run `ahoy build` again as -it may take a long time to rebuild the entire project. Instead, you can -run these commands as needed based on what changed: - -```bash -# Update Composer dependencies (only if composer.json/composer.lock changed) -ahoy composer install - -# Rebuild frontend assets (only if theme files changed) -ahoy fe - -# Provision site (only if database or configuration changes expected) -ahoy provision -``` - -## Fetching database - -To fetch the database with the latest data from the production environment, -use the `ahoy fetch-db` command, which will download the latest database -dump from the production environment into a `.data` directory. - -If there was a download attempt on the same day (locally or from CI), it will -download the cached database dump. - -Use `ahoy fetch-db --fresh` to create a new database dump regardless of the cache. - -:::note - -The database dump is stored in the `.data` directory instead of being directly -imported into the local environment to allow for caching and reusing the -database dump without needing to download it every time you need to refresh -the local environment. - -You can manually download the database dump from the production environment, -name it `db.sql`, and place it in the `.data` directory. +# Composer packages -::: - -## Refreshing database - -Use `ahoy provision` to import the database dump into the local environment -and run all the necessary updates. Run this command any time you need to -reset the local environment to use the fresh database dump stored in `.data`. - -Alternatively, you could use the `ahoy import-db` command (instead of -`ahoy provision`) to import the database dump without running any updates. This -is useful if you want to quickly reset the database without applying any updates -or changes. - -You can also export timestamped database dumps from the local environment into -`.data` directory using the `ahoy export-db` command. You can then use these -dumps to restore the local environment to a specific state: rename the dump -file to `.data/db.sql` and run `ahoy import-db`. - -➡️ See [Drupal > Provision](../drupal/provision) - -## Environment variable updates - -To update environment variables in your local development environment: - -1. Edit variables in `.env.local` file -2. Apply changes by restarting containers: - - ```bash - ahoy restart - ``` +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; -For more comprehensive variable reference, see [Variables](variables.mdx). - -## Debugging with Xdebug - -To enable Xdebug for debugging browser and CLI requests: - -```bash -ahoy debug # Enable Xdebug -ahoy up # Disable Xdebug -``` - -For complete Xdebug setup and IDE configuration, see [Tools > Xdebug](../tools/xdebug.mdx). - -## Working with Composer packages - -### Installing +## Installing To install packages, use `composer require` to include the package and resolve dependencies. -```bash -composer require drupal/devel -``` + + + ```shell + ahoy composer require drupal/devel + ``` + + + ```shell + docker compose exec cli composer require drupal/devel + ``` + + By default, stable releases are installed. If you need a non-stable version (e.g., `alpha`, `beta`, `RC`), specify the version constraint explicitly: -```bash -composer require drupal/devel:^1.0.0@beta -``` + + + ```shell + ahoy composer require drupal/devel:^1.0.0@beta + ``` + + + ```shell + docker compose exec cli composer require drupal/devel:^1.0.0@beta + ``` + + Make sure that the `minimum-stability` setting in `composer.json` is set to the version constraint you need. For example, to allow `alpha`, `beta`, and `RC` versions: @@ -157,7 +49,7 @@ the version constraint you need. For example, to allow `alpha`, `beta`, and `RC` } ``` -### Adding JavaScript/CSS libraries (npm packages) +## Adding JavaScript/CSS libraries (npm packages) To install JavaScript or CSS libraries as Drupal libraries with Composer, they must be defined as [inline Composer packages](https://getcomposer.org/doc/04-schema.md#repositories). @@ -186,17 +78,35 @@ they must be defined as [inline Composer packages](https://getcomposer.org/doc/0 2. Require the package using Composer: -```bash -composer require gdsmith/jquery.easing -``` + + + ```shell + ahoy composer require gdsmith/jquery.easing + ``` + + + ```shell + docker compose exec cli composer require gdsmith/jquery.easing + ``` + + -### Updating +## Updating To update all dependencies: -```bash -composer update -``` + + + ```shell + ahoy composer update + ``` + + + ```shell + docker compose exec cli composer update + ``` + + :::tip Updates and patches @@ -210,19 +120,37 @@ reapply the patches one by one. To update a specific package and its dependencies: -```bash -composer update vendor/package-name --with-dependencies -``` + + + ```shell + ahoy composer update vendor/package-name --with-dependencies + ``` + + + ```shell + docker compose exec cli composer update vendor/package-name --with-dependencies + ``` + + For updating Drupal core, use: -```bash -composer update "drupal/core-*" --with-dependencies -``` + + + ```shell + ahoy composer update "drupal/core-*" --with-dependencies + ``` + + + ```shell + docker compose exec cli composer update "drupal/core-*" --with-dependencies + ``` + + After updating core, review changes with `git diff`, especially modified scaffolding files like `.htaccess`, and commit them in a single commit. -### Overriding paths +## Overriding paths To override package installation paths, modify `composer.json`: @@ -243,7 +171,7 @@ To override package installation paths, modify `composer.json`: } ``` -### Patching +## Patching **Vortex** uses [`cweagans/composer-patches`](https://github.com/cweagans/composer-patches) v2.x for applying patches to Composer dependencies. Version 2.x uses git-based patching with `git apply` for better cross-platform consistency. @@ -253,7 +181,7 @@ For official documentation, visit: [Composer Patches Recommended Workflows](http ::: -#### Understanding `patches.lock.json` +### Understanding `patches.lock.json` Composer Patches v2.x automatically generates a `patches.lock.json` file that contains: @@ -269,7 +197,9 @@ Composer Patches v2.x automatically generates a `patches.lock.json` file that co - Prevents "works on my machine" issues with patches - Makes the patch state explicit and trackable -#### Adding a new patch +### Adding a new patch + + 1. Define the patch in `composer.json` under `extra.patches`: @@ -285,59 +215,128 @@ Composer Patches v2.x automatically generates a `patches.lock.json` file that co 2. Regenerate `patches.lock.json`: - ```bash - composer patches-relock + + + ```shell + ahoy composer patches-relock ``` + + + ```shell + docker compose exec cli composer patches-relock + ``` + + 3. Remove and reinstall patched packages: - ```bash - composer patches-repatch + + + ```shell + ahoy composer patches-repatch + ``` + + + ```shell + docker compose exec cli composer patches-repatch ``` + + - :::warning - `composer patches-repatch` removes patched dependencies from `vendor/` and reinstalls them. Ensure you have no unsaved changes in those directories. - ::: +:::warning +`composer patches-repatch` removes patched dependencies from `vendor/` and reinstalls them. Ensure you have no unsaved changes in those directories. +::: 4. Update `composer.lock`: - ```bash - composer update --lock + + + ```shell + ahoy composer update --lock ``` + + + ```shell + docker compose exec cli composer update --lock + ``` + + + + -#### Removing a patch +### Removing a patch + + 1. Delete the patch definition from `composer.json` 2. Regenerate `patches.lock.json`: - ```bash - composer patches-relock + + + ```shell + ahoy composer patches-relock + ``` + + + ```shell + docker compose exec cli composer patches-relock ``` + + 3. Manually delete the affected dependency: - ```bash - rm -rf vendor/drupal/foobar + + + ```shell + ahoy cli rm -rf vendor/drupal/foobar + ``` + + + ```shell + docker compose exec cli rm -rf vendor/drupal/foobar ``` + + 4. Reinstall without the patch: - ```bash - composer patches-repatch + + + ```shell + ahoy composer patches-repatch ``` + + + ```shell + docker compose exec cli composer patches-repatch + ``` + + 5. Update `composer.lock`: - ```bash - composer update --lock + + + ```shell + ahoy composer update --lock + ``` + + + ```shell + docker compose exec cli composer update --lock ``` + + -### Composer security auditing + + +## Security auditing Composer 2.9.0 introduced automatic security auditing that checks your dependencies for known security vulnerabilities and abandoned packages. This feature helps you maintain a secure codebase by alerting you to potential issues during package installation and updates. -#### Configuration Options +### Configuration options Configure audit behavior in your `composer.json` under the `config` section: @@ -367,7 +366,7 @@ Configure audit behavior in your `composer.json` under the `config` section: - `ignore`: Skips abandoned packages in audit reports - **`ignore`**: Ignores specific security advisories by CVE or GHSA identifier (empty by default) -#### When to Use `block-insecure: false` +### When to Use `block-insecure: false` **Vortex** sets `block-insecure` to `true` by default to enforce security best practices. However, you may want to set it to `false` when: @@ -393,7 +392,7 @@ This approach ensures security issues are explicitly acknowledged and reviewed b ::: -#### Ignoring Specific Advisories +### Ignoring specific advisories When you've assessed a vulnerability and determined it doesn't affect your project, you can ignore it: @@ -416,26 +415,40 @@ Always include reasons when ignoring advisories into your Git commit messages. T ::: -#### Running Audit Command +### Running audit command Check your dependencies for security issues manually: -```bash -# Audit all installed packages -composer audit - -# Audit only production dependencies (exclude dev) -composer audit --no-dev - -# Audit packages from lock file (faster) -composer audit --locked - -# Control abandoned package behavior -composer audit --abandoned=ignore # Skip abandoned packages -composer audit --abandoned=report # Show but don't fail -``` + + + ```shell + # Audit all installed packages + ahoy composer audit + # Audit only production dependencies (exclude dev) + ahoy composer audit --no-dev + # Audit packages from lock file (faster) + ahoy composer audit --locked + # Control abandoned package behavior + ahoy composer audit --abandoned=ignore # Skip abandoned packages + ahoy composer audit --abandoned=report # Show but don't fail + ``` + + + ```shell + # Audit all installed packages + docker compose exec cli composer audit + # Audit only production dependencies (exclude dev) + docker compose exec cli composer audit --no-dev + # Audit packages from lock file (faster) + docker compose exec cli composer audit --locked + # Control abandoned package behavior + docker compose exec cli composer audit --abandoned=ignore # Skip abandoned packages + docker compose exec cli composer audit --abandoned=report # Show but don't fail + ``` + + -##### CI/CD Integration +### CI/CD integration **Vortex** automatically runs `composer audit` as part of the CI/CD pipeline to check for security vulnerabilities during builds. @@ -444,23 +457,3 @@ By default, audit failures will cause the CI build to fail. You can control this behavior using a repository variable `VORTEX_CI_COMPOSER_AUDIT_IGNORE_FAILURE` set to `1`. When this variable is set to `1`, the audit step will run but won't fail the build if vulnerabilities are found. - -## Resetting the codebase - -To reset the local environment, use the `ahoy reset` command. This command will -stop and remove all containers and downloaded dependency packages (`vendor`, -`node_modules` etc.). - -To fully reset the repository to a state as if it was just cloned, -use the `ahoy reset hard` command. - -## Beyond local development - -
-Expand to see the complete code lifecycle - -import CodeLifecycle from './_code-lifecycle.mdx'; - - - -
diff --git a/.vortex/docs/content/development/database.mdx b/.vortex/docs/content/development/database.mdx new file mode 100644 index 000000000..7f947341e --- /dev/null +++ b/.vortex/docs/content/development/database.mdx @@ -0,0 +1,98 @@ +--- +sidebar_label: Database +sidebar_position: 2 +--- + +# Database + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Fetching database + +To fetch the database with the latest data from the production environment, +download the latest database dump into the `.data` directory. + + + + ```shell + # Download latest database dump (uses cache if downloaded today) + ahoy fetch-db + # Force a fresh download regardless of cache + ahoy fetch-db --fresh + ``` + + + ```shell + # Download latest database dump (uses cache if downloaded today) + docker compose exec cli ./scripts/vortex/download-db.sh + # Force a fresh download regardless of cache + VORTEX_DB_DOWNLOAD_REFRESH=1 docker compose exec cli ./scripts/vortex/download-db.sh + ``` + + + +:::note + +The database dump is stored in the `.data` directory instead of being directly +imported into the local environment to allow for caching and reusing the +database dump without needing to download it every time you need to refresh +the local environment. + +You can manually download the database dump from the production environment, +name it `db.sql`, and place it in the `.data` directory. + +::: + +## Refreshing database + +Import the database dump into the local environment and run all necessary updates. + + + + ```shell + # Import database and run updates + ahoy provision + # Import database without running updates + ahoy import-db + ``` + + + ```shell + # Import database and run updates + docker compose exec cli ./scripts/vortex/provision.sh + # Import database without running updates + docker compose exec cli ./scripts/vortex/import-db.sh + ``` + + + +Run the provision command any time you need to reset the local environment to +use the fresh database dump stored in `.data`. + +The import-db command is useful if you want to quickly reset the database +without applying any updates or changes. + +## Exporting database + +Export timestamped database dumps from the local environment. + + + + ```shell + # Export current database to .data directory + ahoy export-db + ``` + + + ```shell + # Export current database to .data directory + docker compose exec cli ./scripts/vortex/export-db.sh + ``` + + + +You can use these dumps to restore the local environment to a specific state: +rename the dump file to `.data/db.sql` and run the import command. + +➡️ See [Drupal > Provision](../drupal/provision) diff --git a/.vortex/docs/content/tools/xdebug.mdx b/.vortex/docs/content/development/debugging.mdx similarity index 54% rename from .vortex/docs/content/tools/xdebug.mdx rename to .vortex/docs/content/development/debugging.mdx index 70ba91144..c1d81f363 100644 --- a/.vortex/docs/content/tools/xdebug.mdx +++ b/.vortex/docs/content/development/debugging.mdx @@ -1,8 +1,11 @@ --- -sidebar_label: Xdebug +sidebar_label: Debugging +sidebar_position: 4 --- -# Xdebug - Debugger tool for PHP +# Debugging + +## Xdebug https://xdebug.org/ @@ -15,9 +18,9 @@ thanks to [Lagoon images](https://github.com/uselagoon/lagoon-images). Xdebug is also configured to work in coverage mode, allowing to run tests with code coverage enabled. -➡️ See [Tools > PHPUnit > Coverage](phpunit.mdx#coverage) +➡️ See [PHPUnit](phpunit) -## Usage +### Usage Xdebug is disabled by default. Run the following command to enable it: @@ -63,9 +66,9 @@ performance reasons. You may need to explicitly enable it by providing `--xdebug` flag to `drush` command. Check the documentation of the command you are trying to run for more details. -## IDE configuration +### IDE configuration -### PhpStorm +#### PhpStorm By default, PhpStorm is configured to automatically interrupt on incoming unmapped debug connections when `Start listening for PHP Debug Connections` @@ -115,3 +118,90 @@ configurations in the PhpStorm IDE to make your life easier: - Increase the number in `Max. simultaneous connections` to `5` or more. This will prevent hidden debug session being "stuck" without being visible in the IDE. + +## Testing authenticated pages with curl + +Use `curl` with session cookies to simulate manual testing of pages that require +authentication (admin pages, protected routes) without opening a browser. This +is for ad-hoc debugging only - automated testing should use Behat or PHPUnit. + +### When to use + +- Quick ad-hoc debugging of admin page errors (500 errors, permission issues) +- Investigating issues without spinning up a browser +- Verifying page content during troubleshooting +- One-off checks that don't warrant a formal test + +### Step-by-step process + + + + ```shell + # Step 1: Get the site URL from project info + ahoy info + # Note the URL (e.g., http://your-project.docker.amazee.io) + # Step 2: Get a one-time login URL + ahoy login + # Output example: http://your-project.docker.amazee.io/user/reset/1/1234567890/abc123/login + # Step 3: Authenticate and save session cookies + # Replace LOGIN_URL with the full URL from Step 2 + curl -k -c .data/cookies.txt -L "LOGIN_URL" + # Step 4: Access any authenticated page using saved cookies + # Replace SITE_URL with your site URL from Step 1 + curl -k -b .data/cookies.txt "SITE_URL/admin/content" + # Step 5: Check for specific errors in page output + curl -k -b .data/cookies.txt "SITE_URL/admin/content" | grep -iE "(error|exception|warning|notice)" + ``` + + + ```shell + # Step 1: Get the site URL from project info + docker compose exec cli ./scripts/vortex/info.sh + # Note the URL (e.g., http://your-project.docker.amazee.io) + # Step 2: Get a one-time login URL + docker compose exec cli drush uli + # Output example: http://your-project.docker.amazee.io/user/reset/1/1234567890/abc123/login + # Step 3: Authenticate and save session cookies + # Replace LOGIN_URL with the full URL from Step 2 + curl -k -c .data/cookies.txt -L "LOGIN_URL" + # Step 4: Access any authenticated page using saved cookies + # Replace SITE_URL with your site URL from Step 1 + curl -k -b .data/cookies.txt "SITE_URL/admin/content" + # Step 5: Check for specific errors in page output + curl -k -b .data/cookies.txt "SITE_URL/admin/content" | grep -iE "(error|exception|warning|notice)" + ``` + + + +### Curl flags reference + +| Flag | Purpose | +|------|---------| +| `-k` | Ignore SSL certificate errors (required for self-signed local certs) | +| `-c FILE` | Save cookies to FILE after request | +| `-b FILE` | Send cookies from FILE with request | +| `-L` | Follow redirects (required for login flow) | + +### Important notes + +- **Cookie storage**: Always use `.data/` directory - it is gitignored +- **Session expiry**: Cookies expire after session timeout; regenerate as needed +- **Login URL format**: `http://SITE/user/reset/UID/TIMESTAMP/HASH/login` +- **One-time use**: Login URLs from `ahoy login` can only be used once + +## Container debugging + +```shell +# Check container status +docker compose ps + +# View container logs +docker compose logs [service_name] +# Examples: +docker compose logs cli +docker compose logs mariadb + +# Access container shell +docker compose exec cli bash +docker compose exec mariadb mysql -u drupal -p drupal +``` diff --git a/.vortex/docs/content/development/faqs.mdx b/.vortex/docs/content/development/faqs.mdx new file mode 100644 index 000000000..249b1a0b3 --- /dev/null +++ b/.vortex/docs/content/development/faqs.mdx @@ -0,0 +1,300 @@ +--- +sidebar_label: FAQs +sidebar_position: 10 +--- + +# FAQs + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## How to know which `ahoy` commands are available? + +```shell +ahoy help +``` + +## How to pass CLI arguments to commands? + +```shell +ahoy mycommand -- myarg1 myarg2 --myoption1 --myoption2=myvalue +``` + +## How to clear Drupal cache? + + + + ```shell + ahoy drush cr + ``` + + + ```shell + docker compose exec cli drush cr + ``` + + + +## How to login to a Drupal site? + + + + ```shell + ahoy login + ``` + + + ```shell + docker compose exec cli drush uli + ``` + + + +## How to connect to the database? + + + + + If you have [Sequel Ace](https://sequel-ace.com/): + + ```shell + ahoy db + ``` + + Otherwise: + + 1. Run `ahoy info` and grab the DB host port number. + 2. Use the connection details below. + + + 1. Run `docker compose ps` and find the database port mapping. + 2. Use the connection details below. + + + + + +Connection details: + +- Host: `127.0.0.1` +- Username: `drupal` +- Password: `drupal` +- Database: `drupal` +- Port: the port from the step above + +## How to use Xdebug? + + + + + + 1. Run `ahoy debug`. + 2. Enable listening for incoming debug connections in your IDE. + 3. If required, provide server URL to your IDE as it appears in the browser. + 4. Enable Xdebug flag in the request coming from your web browser (use one of + the extensions or add `?XDEBUG_SESSION_START=1` to your URL). + 5. Set a breakpoint in your IDE and perform a request in the web browser. + + Use the same commands to debug CLI scripts. + + To disable, run `ahoy up`. + + + 1. Run `XDEBUG_ENABLE=true docker compose up -d cli php nginx`. + 2. Enable listening for incoming debug connections in your IDE. + 3. If required, provide server URL to your IDE as it appears in the browser. + 4. Enable Xdebug flag in the request coming from your web browser (use one of + the extensions or add `?XDEBUG_SESSION_START=1` to your URL). + 5. Set a breakpoint in your IDE and perform a request in the web browser. + + Use the same commands to debug CLI scripts. + + To disable, run `docker compose up -d cli php nginx`. + + + + + +➡️ See [Debugging](debugging.mdx) + +## How to use Xdebug with Behat? + + + + + + 1. Enable debugging: `ahoy debug` + 2. Enter CLI container: `ahoy cli` + 3. Run Behat tests: + + ```shell + vendor/bin/behat --xdebug path/to/test.feature + ``` + + + 1. Enable debugging: `XDEBUG_ENABLE=true docker compose up -d cli php nginx` + 2. Enter CLI container: `docker compose exec cli bash` + 3. Run Behat tests: + + ```shell + vendor/bin/behat --xdebug path/to/test.feature + ``` + + + + + +## What should I do to switch to a "clean" branch environment? + +Provided that your stack is already running: + + + + + + 1. Switch to your branch + 2. `composer install` + 3. `ahoy provision` + + You do not need to rebuild the full stack using `ahoy build` every + time you switch branches. `ahoy provision` will update the environment + to match the current branch. + + However, sometimes you would want to have an absolutely clean environment - in + that case, use `ahoy build`. + + + 1. Switch to your branch + 2. `docker compose exec cli composer install` + 3. `docker compose exec cli ./scripts/vortex/provision.sh` + + You do not need to rebuild the full stack every time you switch branches. + The provision script will update the environment to match the current branch. + + However, sometimes you would want to have an absolutely clean environment - in + that case, run: + + ```shell + docker compose down + ./scripts/vortex/reset.sh + docker compose up -d --build --force-recreate + docker compose exec cli ./scripts/vortex/provision.sh + ``` + + + + + +## How to just import a database? + +Provided that your stack is already running: + + + + + + ```shell + ahoy import-db + ahoy import-db .data/db_custom.sql + ``` + + + ```shell + docker compose exec cli ./scripts/vortex/import-db.sh + docker compose exec cli ./scripts/vortex/import-db.sh .data/db_custom.sql + ``` + + + + + +## How to add Drupal modules + + + + ```shell + ahoy composer require drupal/module_name + ``` + + + ```shell + docker compose exec cli composer require drupal/module_name + ``` + + + +## How to add patches for Drupal modules + +1. Add `title` to patch on https://drupal.org to the `patches` array in `extra` + section in `composer.json`. + + ```json + "extra": { + "patches": { + "drupal/somepackage": { + "Remote patch description": "https://www.drupal.org/files/issues/issue.patch" + "Local patch description": "patches/package-description.patch" + } + } + } + ``` + +2. Run + + + + ```shell + ahoy composer require drupal/somepackage + ``` + + + ```shell + docker compose exec cli composer require drupal/somepackage + ``` + + + +➡️ See [Composer > Patching](composer.mdx#patching) + +## What should I do when Composer blocks package installation due to security vulnerabilities? + +Starting with Composer 2.9.0, Composer can automatically block the installation +or update of packages with known security vulnerabilities. If you encounter this +issue, you have several options: + +1. **Update the affected packages**: Try updating to newer versions that don't + have known vulnerabilities: `composer update vendor/package-name` +2. **Review the vulnerability**: Run `composer audit` to see details about the + security issues and determine if they affect your project. +3. **Adjust security settings**: If you need to proceed with installation despite + warnings (for example, if no secure version is available or the vulnerability + doesn't affect your use case), you can configure the `audit.block-insecure` + setting in your `composer.json`. + +➡️ See [Composer > Security auditing](composer.mdx#security-auditing) for detailed +information about the `audit` configuration option and guidance on choosing the +right security settings for your project. + +## How to set a custom maintenance theme? + +To set a custom theme for Drupal's maintenance mode (when the site is offline +for updates), set the `DRUPAL_MAINTENANCE_THEME` environment variable: + +```shell +# In .env file +DRUPAL_MAINTENANCE_THEME=my_custom_theme +``` + +This theme will be used when Drupal is in maintenance mode. If +`DRUPAL_MAINTENANCE_THEME` is not set, the system will fall back to using the +value of `DRUPAL_THEME`. + +The maintenance theme should be a valid Drupal theme that is already installed +and enabled on your site. + +## Behat tests with `@javascript` tag sometimes get stuck + +Behat tests with `@javascript` tag sometimes get stuck for about 10min then +fail. The Chrome container randomly gets stuck for an unknown reason. + +Restart the Chrome container: `docker compose restart chrome` diff --git a/.vortex/docs/content/development/phpunit.mdx b/.vortex/docs/content/development/phpunit.mdx new file mode 100644 index 000000000..e00d68a00 --- /dev/null +++ b/.vortex/docs/content/development/phpunit.mdx @@ -0,0 +1,134 @@ +--- +sidebar_label: PHPUnit +sidebar_position: 5 +--- + +# PHPUnit + +**Vortex** uses [PHPUnit](https://phpunit.de/) as a framework for Unit, Kernel, +and Functional testing. PHPUnit tests verify that individual components work +correctly in isolation and when integrated with Drupal's systems. + +**Vortex** provides full PHPUnit support, including configuration in [`phpunit.xml`](https://github.com/drevops/vortex/blob/main/phpunit.xml) +based on Drupal core's `core/phpunit.xml.dist` to allow customizing the test +suite per project. + +Test types supported: + +1. **Unit tests** - Test isolated PHP classes without Drupal bootstrap +2. **Kernel tests** - Test with partial Drupal bootstrap (database, services) +3. **Functional tests** - Test with full Drupal bootstrap including browser simulation + +## Running tests + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + ```shell + # Run all PHPUnit tests (Unit, Kernel, Functional) + ahoy test + # Run only Unit tests + ahoy test-unit + # Run only Kernel tests + ahoy test-kernel + # Run only Functional tests + ahoy test-functional + # Run specific test file + ahoy test tests/phpunit/ExampleTest.php + # Run tests with filter + ahoy test -- --filter=testMethodName + ``` + + + ```shell + # Run all PHPUnit tests (Unit, Kernel, Functional) + docker compose exec cli vendor/bin/phpunit + # Run only Unit tests + docker compose exec cli vendor/bin/phpunit --testsuite=unit + # Run only Kernel tests + docker compose exec cli vendor/bin/phpunit --testsuite=kernel + # Run only Functional tests + docker compose exec cli vendor/bin/phpunit --testsuite=functional + # Run specific test file + docker compose exec cli vendor/bin/phpunit tests/phpunit/ExampleTest.php + # Run tests with filter + docker compose exec cli vendor/bin/phpunit --filter=testMethodName + ``` + + + +## Test suites + +PHPUnit tests are organized into test suites defined in `phpunit.xml`: + +- **unit** - Fast tests that don't require Drupal bootstrap +- **kernel** - Tests that need database and core services +- **functional** - Full browser simulation tests + +## Configuration + +The `phpunit.xml` file in the project root configures: + +- Test suite directories and naming patterns +- Bootstrap file for Drupal integration +- Environment variables for test execution +- Code coverage settings + +## Skipping tests + +Add `@group skip` annotation to a test class or method to exclude it from the test run: + +```php +/** + * @group skip + */ +public function testSomethingToSkip(): void { + // This test will be skipped +} +``` + +## Reporting + +Test reports are stored in `.logs/phpunit` directory, separated into multiple +files and named after the suite name. These reports are usually used in +continuous integration to track test performance and stability. + +## Boilerplate + +**Vortex** provides Unit, Kernel and Functional tests boilerplate for custom [modules](https://github.com/drevops/vortex/blob/main/web/modules/custom/ys_base/tests/src), +[themes](https://github.com/drevops/vortex/blob/main/web/themes/custom/your_site_theme/tests/src) and +[scripts](https://github.com/drevops/vortex/blob/main/tests/phpunit). + +These boilerplate tests run in continuous integration pipeline when you install +**Vortex** and can be used as a starting point for writing your own. + +### Drupal settings tests + +**Vortex** provides [Drupal settings tests](https://github.com/drevops/vortex/blob/main/tests/phpunit/Drupal/DrupalSettingsTest.php) +to check that Drupal settings are correct based on the environment type the site +is running: with the number of custom modules multiplied by the number of +environment types, it is easy to miss certain settings which may lead to +unexpected issues when deploying a project to a different environment. + +It is intended to be used in your site and kept up-to-date with the +changes made to the `settings.php` file. + +### Continuous integration pipeline configuration tests + +**Vortex** provides [continuous integration pipeline configuration tests](https://github.com/drevops/vortex/blob/main/tests/phpunit/CircleCiConfigTest.php) +to check that the continuous integration configuration is correct. It is +intended to be used in your site and kept up-to-date with the continuous +integration configurations. + +For example, there are tests for regular expressions used to filter the branches +and tags before they are deployed to the hosting environment. + +## Writing tests + +For project-specific test writing conventions (test class structure, base classes, +data providers, test data conventions), see your project's `docs/testing.md` file. + +The `docs/testing.md` file is scaffolded when you install **Vortex** and should +be maintained by your project team to document agreed-upon testing practices. diff --git a/.vortex/docs/content/workflows/variables.mdx b/.vortex/docs/content/development/variables.mdx similarity index 99% rename from .vortex/docs/content/workflows/variables.mdx rename to .vortex/docs/content/development/variables.mdx index 50d9b9c00..d7c16d36c 100644 --- a/.vortex/docs/content/workflows/variables.mdx +++ b/.vortex/docs/content/development/variables.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 8 +sidebar_position: 100 hide_table_of_contents: true --- @@ -7,7 +7,7 @@ hide_table_of_contents: true -**Vortex** uses environment variables to configure workflows without the need to +**Vortex** uses environment variables to configure scripts without the need to change the code to alter behavior. There are two main types of variables: @@ -17,8 +17,8 @@ remain constant throughout the project lifecycle. These are typically configured in the `.env` file, or within the CI or hosting provider environments. -**Workflow Control Variables** can be changed during the project lifecycle -to alter workflow behavior. For example, changing how deployment behaves +**Runtime Variables** can be changed during the project lifecycle +to alter script behavior. For example, changing how deployment behaves or skipping a certain code branch deployment within CI. ## `.env` and `.env.local` files @@ -44,7 +44,7 @@ separate from the main `.env` file. ### Naming conventions -All variables used by **Vortex** workflows start with the `VORTEX_` prefix to +All variables used by **Vortex** scripts start with the `VORTEX_` prefix to differentiate them from other environment variables. All Drupal-specific environment variables start with the `DRUPAL_` prefix. @@ -54,11 +54,11 @@ are used as-is. ### Default values -All _required_ variables used by **Vortex** workflows have checks in place to +All _required_ variables used by **Vortex** scripts have checks in place to ensure they are set before proceeding. If a required variable is missing, the script will fail with a clear error message. -All _optional_ variables used by **Vortex** workflows have default values +All _optional_ variables used by **Vortex** scripts have default values defined within the scripts. This ensures that scripts can run out-of-the-box without requiring extensive configuration. @@ -233,7 +233,7 @@ The list below is automatically generated with [Shellvar](https://github.com/ale | `VORTEX_DEPLOY_SKIP` | Skip all deployments. | `UNDEFINED` | `CI config` | | `VORTEX_DEPLOY_SSH_FILE` | Default SSH file used if custom fingerprint is not provided. | `${HOME}/.ssh/id_rsa` | `scripts/vortex/deploy-artifact.sh`, `scripts/vortex/deploy-lagoon.sh` | | `VORTEX_DEPLOY_SSH_FINGERPRINT` | SSH key fingerprint used to connect to remote. | `UNDEFINED` | `scripts/vortex/deploy-artifact.sh`, `scripts/vortex/deploy-lagoon.sh` | -| `VORTEX_DEPLOY_TYPES` | Deployment occurs when tests pass in the CI environment. @see https://www.vortextemplate.com/docs/workflows/deployment | `artifact` | `.env`, `scripts/vortex/deploy.sh` | +| `VORTEX_DEPLOY_TYPES` | Deployment occurs when tests pass in the CI environment. @see https://www.vortextemplate.com/docs/deployment | `artifact` | `.env`, `scripts/vortex/deploy.sh` | | `VORTEX_DEPLOY_WEBHOOK_METHOD` | Webhook call method. | `GET` | `scripts/vortex/deploy-webhook.sh` | | `VORTEX_DEPLOY_WEBHOOK_RESPONSE_STATUS` | The status code of the expected response. | `200` | `scripts/vortex/deploy-webhook.sh` | | `VORTEX_DEPLOY_WEBHOOK_URL` | The URL of the webhook to call. | `UNDEFINED` | `scripts/vortex/deploy-webhook.sh` | @@ -286,12 +286,12 @@ The list below is automatically generated with [Shellvar](https://github.com/ale | `VORTEX_NOTIFY_JIRA_LOGIN_URL` | JIRA notification login URL. | `${VORTEX_NOTIFY_LOGIN_URL}` | `scripts/vortex/notify-jira.sh` | | `VORTEX_NOTIFY_JIRA_MESSAGE` | JIRA notification message template (will be converted to ADF format). Available tokens: %project%, %label%, %timestamp%, %environment_url%, %login_url% | `UNDEFINED` | `scripts/vortex/notify-jira.sh` | | `VORTEX_NOTIFY_JIRA_PROJECT` | JIRA notification project name. | `${VORTEX_NOTIFY_PROJECT}` | `scripts/vortex/notify-jira.sh` | -| `VORTEX_NOTIFY_JIRA_TOKEN` | JIRA notification API token.

@see https://www.vortextemplate.com/docs/workflows/notifications#jira | `UNDEFINED` | `scripts/vortex/notify-jira.sh`, `ACQUIA ENVIRONMENT`, `LAGOON ENVIRONMENT` | +| `VORTEX_NOTIFY_JIRA_TOKEN` | JIRA notification API token.

@see https://www.vortextemplate.com/docs/deployment/notifications#jira | `UNDEFINED` | `scripts/vortex/notify-jira.sh`, `ACQUIA ENVIRONMENT`, `LAGOON ENVIRONMENT` | | `VORTEX_NOTIFY_JIRA_TRANSITION` | JIRA notification state to transition to.

If left empty - no transition will be performed. | `UNDEFINED` | `scripts/vortex/notify-jira.sh` | | `VORTEX_NOTIFY_JIRA_USER_EMAIL` | JIRA user email address. | `user@example.com` | `.env`, `scripts/vortex/notify-jira.sh` | | `VORTEX_NOTIFY_LABEL` | Notification deployment label (human-readable identifier for display). | `UNDEFINED` | `scripts/vortex/notify.sh` | | `VORTEX_NOTIFY_LOGIN_URL` | Notification login URL (defaults to ENVIRONMENT_URL/user/login if not provided). | `UNDEFINED` | `scripts/vortex/notify.sh` | -| `VORTEX_NOTIFY_NEWRELIC_APIKEY` | NewRelic API key, usually of type 'USER'.

@see https://www.vortextemplate.com/docs/workflows/notifications#new-relic | `UNDEFINED` | `ACQUIA ENVIRONMENT`, `LAGOON ENVIRONMENT` | +| `VORTEX_NOTIFY_NEWRELIC_APIKEY` | NewRelic API key, usually of type 'USER'.

@see https://www.vortextemplate.com/docs/deployment/notifications#new-relic | `UNDEFINED` | `ACQUIA ENVIRONMENT`, `LAGOON ENVIRONMENT` | | `VORTEX_NOTIFY_NEWRELIC_APPID` | New Relic notification application ID (auto-discovered if not provided).

Will be discovered automatically from application name if not provided. | `UNDEFINED` | `scripts/vortex/notify-newrelic.sh` | | `VORTEX_NOTIFY_NEWRELIC_APP_NAME` | New Relic notification application name as it appears in the dashboard. | `${VORTEX_NOTIFY_NEWRELIC_PROJECT}-${VORTEX_NOTIFY_NEWRELIC_LABEL}` | `scripts/vortex/notify-newrelic.sh` | | `VORTEX_NOTIFY_NEWRELIC_CHANGELOG` | New Relic notification deployment changelog. Defaults to the description. | `UNDEFINED` | `scripts/vortex/notify-newrelic.sh` | @@ -306,7 +306,7 @@ The list below is automatically generated with [Shellvar](https://github.com/ale | `VORTEX_NOTIFY_NEWRELIC_REVISION` | New Relic notification deployment revision. If not provided, will use SHA if available, otherwise auto-generated. | `UNDEFINED` | `scripts/vortex/notify-newrelic.sh` | | `VORTEX_NOTIFY_NEWRELIC_SHA` | New Relic notification git commit SHA. | `${VORTEX_NOTIFY_SHA}` | `scripts/vortex/notify-newrelic.sh` | | `VORTEX_NOTIFY_NEWRELIC_USER` | New Relic notification user performing deployment. | `Deployment robot` | `scripts/vortex/notify-newrelic.sh` | -| `VORTEX_NOTIFY_NEWRELIC_USER_KEY` | New Relic notification User API Key.

To obtain your User API Key: `1`. Log in to New Relic `2`. Click on your profile icon (bottom left) `3`. Go to "API keys" `4`. Create or copy an existing "User key" `5`. The key format is: NRAK-XXXXXXXXXXXXXXXXXXXXXX

@see https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#user-key @see https://www.vortextemplate.com/docs/workflows/notifications#new-relic | `${NEWRELIC_USER_KEY}` | `scripts/vortex/notify-newrelic.sh` | +| `VORTEX_NOTIFY_NEWRELIC_USER_KEY` | New Relic notification User API Key.

To obtain your User API Key: `1`. Log in to New Relic `2`. Click on your profile icon (bottom left) `3`. Go to "API keys" `4`. Create or copy an existing "User key" `5`. The key format is: NRAK-XXXXXXXXXXXXXXXXXXXXXX

@see https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#user-key @see https://www.vortextemplate.com/docs/deployment/notifications#new-relic | `${NEWRELIC_USER_KEY}` | `scripts/vortex/notify-newrelic.sh` | | `VORTEX_NOTIFY_PROJECT` | Notification project name. | `${VORTEX_PROJECT}` | `scripts/vortex/notify.sh` | | `VORTEX_NOTIFY_PR_NUMBER` | Notification pull request number. | `UNDEFINED` | `scripts/vortex/notify.sh` | | `VORTEX_NOTIFY_SHA` | Notification git commit SHA. | `UNDEFINED` | `scripts/vortex/notify.sh` | @@ -320,7 +320,7 @@ The list below is automatically generated with [Shellvar](https://github.com/ale | `VORTEX_NOTIFY_SLACK_MESSAGE` | Slack notification message template (for fallback text). Available tokens: %project%, %label%, %timestamp%, %environment_url%, %login_url% | `UNDEFINED` | `scripts/vortex/notify-slack.sh` | | `VORTEX_NOTIFY_SLACK_PROJECT` | Slack notification project name. | `${VORTEX_NOTIFY_PROJECT}` | `scripts/vortex/notify-slack.sh` | | `VORTEX_NOTIFY_SLACK_USERNAME` | Slack notification bot display name (optional). | `Deployment Bot` | `scripts/vortex/notify-slack.sh` | -| `VORTEX_NOTIFY_SLACK_WEBHOOK` | Slack notification webhook URL. The incoming Webhook URL from your Slack app configuration. @see https://www.vortextemplate.com/docs/workflows/notifications#slack | `UNDEFINED` | `scripts/vortex/notify-slack.sh`, `ACQUIA ENVIRONMENT`, `LAGOON ENVIRONMENT` | +| `VORTEX_NOTIFY_SLACK_WEBHOOK` | Slack notification webhook URL. The incoming Webhook URL from your Slack app configuration. @see https://www.vortextemplate.com/docs/deployment/notifications#slack | `UNDEFINED` | `scripts/vortex/notify-slack.sh`, `ACQUIA ENVIRONMENT`, `LAGOON ENVIRONMENT` | | `VORTEX_NOTIFY_WEBHOOK_ENVIRONMENT_URL` | Webhook notification environment URL. | `${VORTEX_NOTIFY_ENVIRONMENT_URL}` | `scripts/vortex/notify-webhook.sh` | | `VORTEX_NOTIFY_WEBHOOK_EVENT` | Webhook notification event type. Can be 'pre_deployment' or 'post_deployment'. | `post_deployment` | `scripts/vortex/notify-webhook.sh` | | `VORTEX_NOTIFY_WEBHOOK_HEADERS` | Webhook notification pipe-separated headers. Separate multiple headers with a pipe `|`. Example: `Content-type: application/json|Authorization: Bearer API_KEY`. | `Content-type: application/json` | `scripts/vortex/notify-webhook.sh` | @@ -346,7 +346,7 @@ The list below is automatically generated with [Shellvar](https://github.com/ale | `VORTEX_PROVISION_TYPE` | Set to 'profile' to install a site from profile instead of the database dump. | `database` | `.env`, `scripts/vortex/provision.sh` | | `VORTEX_PROVISION_USE_MAINTENANCE_MODE` | Put the site into a maintenance mode during site provisioning. | `1` | `.env`, `scripts/vortex/provision.sh` | | `VORTEX_PURGE_CACHE_ACQUIA_SKIP` | Skip purging of edge cache in Acquia environment. | `UNDEFINED` | `ACQUIA ENVIRONMENT` | -| `VORTEX_RELEASE_VERSION_SCHEME` | Versioning scheme used for releases.

Can be one of: calver, semver, other @see https://www.vortextemplate.com/docs/workflows/releasing | `calver` | `.env` | +| `VORTEX_RELEASE_VERSION_SCHEME` | Versioning scheme used for releases.

Can be one of: calver, semver, other @see https://www.vortextemplate.com/docs/releasing | `calver` | `.env` | | `VORTEX_SHOW_LOGIN` | Show one-time login link. | `UNDEFINED` | `scripts/vortex/info.sh` | | `VORTEX_SSH_DISABLE_STRICT_HOST_KEY_CHECKING` | Disable strict host key checking in SSH. | `0` | `scripts/vortex/setup-ssh.sh` | | `VORTEX_SSH_FILE` | Default SSH key file. | `${HOME}/.ssh/id_rsa` | `scripts/vortex/doctor.sh` | diff --git a/.vortex/docs/content/drupal/composer.mdx b/.vortex/docs/content/drupal/composer-json.mdx similarity index 97% rename from .vortex/docs/content/drupal/composer.mdx rename to .vortex/docs/content/drupal/composer-json.mdx index 222311c2b..febedcd73 100644 --- a/.vortex/docs/content/drupal/composer.mdx +++ b/.vortex/docs/content/drupal/composer-json.mdx @@ -1,62 +1,19 @@ --- +sidebar_label: composer.json sidebar_position: 1 --- -# Composer +# composer.json [Composer](https://getcomposer.org/) is a dependency manager for PHP projects, including Drupal. It allows you to declare the libraries your project depends on and manages them for you. :::tip -See [Working with Composer packages](../workflows/development#working-with-composer-packages) for more information -on how to add and manage dependencies in your project. +➡️ See [Development > Composer](../development/composer) for information on how to add and manage dependencies. ::: -## Dependency bumping - -[Dependency bumping](https://getcomposer.org/doc/03-cli.md#bump) updates version -constraints in your `composer.json` to match currently installed versions. This -prevents accidental downgrades when adding new dependencies and improves -dependency resolution performance. - -**Vortex** enables this automatically via the `bump-after-update` configuration. -Every time you run `composer update`, your version constraints are updated to -reflect the installed versions. - -:::note - -**Vortex** enables automatic bumping because it's designed for **application -projects** (Drupal sites) where you control the entire dependency tree. This -keeps your version constraints synchronized with tested versions and prevents -accidental downgrades. - -This approach is **not recommended for libraries** (reusable packages). Libraries -should keep version constraints as broad as possible to avoid [dependency -hell](https://getcomposer.org/doc/articles/versions.md) for downstream users. If -you're building a library, use `bump-after-update: "dev"` to only bump -development dependencies, or disable automatic bumping and run `composer bump ---dev-only` manually. - -::: - -### Manual bumping - -```bash -# Bump all dependencies -composer bump - -# Bump specific package -composer bump drupal/core-recommended - -# Bump only development dependencies -composer bump --dev-only - -# Preview changes without modifying files -composer bump --dry-run -``` - ## `composer.json` **Vortex** comes with a pre-configured `composer.json` that lists essential @@ -131,8 +88,7 @@ specifies the essential packages and libraries your project needs. not yet in official releases. Version 2.x uses `git apply` for cross-platform consistency and generates a `patches.lock.json` file to ensure reproducible builds with SHA-256 checksums. - See [Patching](../workflows/development#patching) for more - information on how to work with patches. + ➡️ See [Development > Composer > Patching](../development/composer#patching) - `drupal/admin_toolbar`, `drupal/clamav`, `drupal/coffee`, etc. - Drupal modules that provide various site administration and development helping functionalities that is usually installed across all of your Drupal sites. @@ -289,7 +245,7 @@ specifies key configurations for Composer's behavior in the project. documented vulnerability exceptions. Use this to explicitly allow specific CVE/GHSA advisories that have been reviewed and accepted. - See - [Composer Security Auditing](../workflows/development#composer-security-auditing) + [Composer Security Auditing](../development/composer#security-auditing) for comprehensive guidance on configuration options, ignoring specific advisories, running audits, and best practices. - [`bump-after-update`](https://getcomposer.org/doc/06-config.md#bump-after-update): @@ -358,8 +314,7 @@ needs and structure of your Drupal project. patch file are interpreted relative to the current directory where the patch is being applied. - `patches`: Specifies the patches to be applied to specific packages. - See [Working with packages](../workflows/development#patching) for more - information on how to work with patches. + ➡️ See [Development > Composer > Patching](../development/composer#patching) ### `scripts` @@ -388,3 +343,46 @@ enhancing the automation and maintenance of your Drupal project. same `createRequiredFiles` method as in `post-install-cmd`, ensuring that necessary files and configurations are updated or re-established following an update of dependencies. + +## Dependency bumping + +[Dependency bumping](https://getcomposer.org/doc/03-cli.md#bump) updates version +constraints in your `composer.json` to match currently installed versions. This +prevents accidental downgrades when adding new dependencies and improves +dependency resolution performance. + +**Vortex** enables this automatically via the `bump-after-update` configuration. +Every time you run `composer update`, your version constraints are updated to +reflect the installed versions. + +:::note + +**Vortex** enables automatic bumping because it's designed for **application +projects** (Drupal sites) where you control the entire dependency tree. This +keeps your version constraints synchronized with tested versions and prevents +accidental downgrades. + +This approach is **not recommended for libraries** (reusable packages). Libraries +should keep version constraints as broad as possible to avoid [dependency +hell](https://getcomposer.org/doc/articles/versions.md) for downstream users. If +you're building a library, use `bump-after-update: "dev"` to only bump +development dependencies, or disable automatic bumping and run `composer bump +--dev-only` manually. + +::: + +### Manual bumping + +```shell +# Bump all dependencies +composer bump + +# Bump specific package +composer bump drupal/core-recommended + +# Bump only development dependencies +composer bump --dev-only + +# Preview changes without modifying files +composer bump --dry-run +``` diff --git a/.vortex/docs/content/drupal/module-scaffold.mdx b/.vortex/docs/content/drupal/module-scaffold.mdx index 6cf53a378..e05145747 100644 --- a/.vortex/docs/content/drupal/module-scaffold.mdx +++ b/.vortex/docs/content/drupal/module-scaffold.mdx @@ -38,5 +38,5 @@ tests. Simply remove them if you do not need them. --- -➡️ See [Workflows > Development](../workflows/development) for more details on how to work with +➡️ See [Development](../development) for more details on how to work with the custom modules. diff --git a/.vortex/docs/content/drupal/provision.mdx b/.vortex/docs/content/drupal/provision.mdx index 6903abada..c182c2e89 100644 --- a/.vortex/docs/content/drupal/provision.mdx +++ b/.vortex/docs/content/drupal/provision.mdx @@ -53,7 +53,7 @@ Runs the complete provisioning process including: Use this when you want a fully configured site ready for development or deployment. -```bash +```shell # Full provisioning (recommended for most cases) ahoy provision ``` @@ -67,7 +67,7 @@ Imports only the database dump without running deployment scripts: - Skips database updates - Skips post-provisioning scripts -```bash +```shell # Import database only from default dump in .data/db.sql ahoy import-db @@ -183,7 +183,7 @@ You may choose to only perform an action based on a specific environment (the value of `$settings['environment']` is populated by the [Drupal settings file](settings#environment-type-detection)): -```bash +```shell environment="$(drush php:eval "print \Drupal\core\Site\Settings::get('environment');")" if echo "${environment}" | grep -q -e dev -e stage -e ci -e local; then @@ -197,7 +197,7 @@ fi You may also conditionally perform an action based on whether the database is freshly imported or not: -```bash +```shell if [ "${VORTEX_PROVISION_OVERRIDE_DB:-0}" = "1" ]; then echo "> Fresh database detected." else @@ -219,5 +219,7 @@ import ProvisionScriptExample from '!!raw-loader!./provision-example.sh';
:::tip Related Documentation -For information about different types of Drupal hooks used during deployment and updates, see [Update Hooks](./update-hooks). +For information about different types of Drupal hooks used during deployment and updates. + +➡️ See [Update Hooks](./update-hooks) ::: diff --git a/.vortex/docs/content/drupal/settings.mdx b/.vortex/docs/content/drupal/settings.mdx index 5eddc512e..e5508d7bc 100644 --- a/.vortex/docs/content/drupal/settings.mdx +++ b/.vortex/docs/content/drupal/settings.mdx @@ -235,7 +235,7 @@ modules, each isolated in its own file for easy maintenance and removal. To add settings for a new module, create a file following the naming pattern: -```bash +```shell web/sites/default/includes/modules/settings.[module_name].php ``` @@ -292,7 +292,7 @@ and environment variables — behaves as expected. To run unit tests for settings: -```bash +```shell vendor/bin/phpunit --group=drupal_settings ``` diff --git a/.vortex/docs/content/drupal/theme-scaffold.mdx b/.vortex/docs/content/drupal/theme-scaffold.mdx index a648e2def..d88000a76 100644 --- a/.vortex/docs/content/drupal/theme-scaffold.mdx +++ b/.vortex/docs/content/drupal/theme-scaffold.mdx @@ -18,7 +18,7 @@ while modules use the abbreviated prefix (`ys_` for `your_site`). We understand that front-end theming is often highly project-specific and subject to team preferences. The provided `your_site_theme` scaffold is not intended to dictate how your theme should be built — it simply demonstrates how -custom themes can _integrate_ with the **Vortex** tooling and workflows. +custom themes can _integrate_ with the **Vortex** tooling and automations. Feel free to adapt or replace it with your preferred theme. @@ -32,11 +32,11 @@ The theme includes a complete Node.js-based build system using [Grunt](https://g - **JavaScript concatenation and minification** - **CSS auto-prefixing** for browser compatibility - **Linting** for both CSS ([Stylelint](https://stylelint.io/)) and JavaScript ([ESLint](https://eslint.org/)) -- **Watch mode** for development workflow +- **Watch mode** for development ### Build commands -```bash +```shell cd web/themes/custom/your_site_theme # Install dependencies @@ -61,7 +61,7 @@ yarn run watch Ahoy commands are configured to call the appropriate Yarn scripts from the theme directory: -```bash +```shell # Install front-end dependencies ahoy fei @@ -86,7 +86,7 @@ and tools installed there, ensuring consistency across development environments. When adding your own theme with a custom build system, it's a good idea to follow the same command structure and naming conventions. This keeps things consistent across projects and makes it easier for other developers to work with -the build system without learning a new workflow. +the build system without learning a new process. ::: @@ -132,5 +132,5 @@ tests. Simply remove them if you do not need them. --- -➡️ See [Workflows > Development](../workflows/development) for more details on how to work with +➡️ See [Development](../development) for more details on how to work with the theme. diff --git a/.vortex/docs/content/drupal/update-hooks.mdx b/.vortex/docs/content/drupal/update-hooks.mdx index 8ae4ba1cf..2964cea18 100644 --- a/.vortex/docs/content/drupal/update-hooks.mdx +++ b/.vortex/docs/content/drupal/update-hooks.mdx @@ -64,7 +64,7 @@ function ys_base_deploy_create_about_page(): string { ### Debugging commands -```bash +```shell # List available deploy hooks drush deploy:hook --list diff --git a/.vortex/docs/content/faqs.mdx b/.vortex/docs/content/faqs.mdx index aba18a46b..abc30971e 100644 --- a/.vortex/docs/content/faqs.mdx +++ b/.vortex/docs/content/faqs.mdx @@ -3,7 +3,7 @@ ## Why use Vortex instead of the Drupal Composer template? The Drupal Composer template gives you a starting point, but you still need to -add everything else: CI pipelines, tooling, workflows, deployment scripts, +add everything else: CI pipelines, tooling, automations, deployment scripts, hosting configurations, and documentation. Then you need to test that everything works together correctly. @@ -23,7 +23,7 @@ Yes, you can install **Vortex** into your existing project. See ## Can I keep my existing CI provider? -Yes, but you'll need to update your CI configuration to use **Vortex** workflow +Yes, but you'll need to update your CI configuration to use **Vortex** automation scripts. ## Can I keep my existing hosting? diff --git a/.vortex/docs/content/features.mdx b/.vortex/docs/content/features.mdx index 7ede08e89..d810eb652 100644 --- a/.vortex/docs/content/features.mdx +++ b/.vortex/docs/content/features.mdx @@ -58,7 +58,7 @@ import { > A Drupal-optimized hosting platform built to empower your team. - Database and file syncing - - Centralized deployment workflow management via cloud hooks + - Centralized deployment management via cloud hooks - Code artifact deployments ### Lagoon @@ -67,7 +67,7 @@ import { - Production-ready containerized stack - Database and file syncing - - Centralized deployment workflow management + - Centralized deployment management - Preview environment support :::note @@ -169,13 +169,13 @@ import { - ⚙️ Workflows | Useful workflows and automation + ⚙️ Automations | Useful automations and scripts - ### Identical workflows across environments + ### Identical operations across environments - - Scripted workflows for common tasks configured to run in the same way in all environments - - Support for workflow customization via hooks + - Scripted automation for common tasks configured to run in the same way in all environments + - Support for customization via environment variables - Database sourcing from hosting provider or intermediate storage (URL, FTP, container image, etc.) ### Deployment Notifications @@ -238,8 +238,8 @@ import { - Test coverage for containerized stack for guaranteed readiness - Test coverage for tooling configuration for guaranteed compatibility - - Unit tests for workflow scripts and coverage reporting for reliable and consistent execution - - Functional test coverage for workflows: run all workflow commands as a developer would + - Unit tests for automation scripts and coverage reporting for reliable and consistent execution + - Functional test coverage for scripts: run all commands as a developer would - Automated documentation site generation and validation for up-to-date and accurate documentation ### Vortex installation and updates diff --git a/.vortex/docs/content/hosting/README.mdx b/.vortex/docs/content/hosting/README.mdx index 8abd3b4aa..07183c7ef 100644 --- a/.vortex/docs/content/hosting/README.mdx +++ b/.vortex/docs/content/hosting/README.mdx @@ -16,7 +16,7 @@ sidebar_position: 1 ::: -The deployment workflows to all environments of these providers are streamlined +The deployment pipelines to all environments of these providers are streamlined and automated to ensure that the deployment process is consistent and reliable. ## Hosting providers vs environments diff --git a/.vortex/docs/content/hosting/acquia.mdx b/.vortex/docs/content/hosting/acquia.mdx index ab659b508..81997e188 100644 --- a/.vortex/docs/content/hosting/acquia.mdx +++ b/.vortex/docs/content/hosting/acquia.mdx @@ -85,6 +85,6 @@ for detailed instructions. Download a database backup from your Acquia environment for local development or CI builds: -```bash +```shell ahoy download-db ``` diff --git a/.vortex/docs/content/hosting/lagoon.mdx b/.vortex/docs/content/hosting/lagoon.mdx index 6bb89aeaf..9e762234a 100644 --- a/.vortex/docs/content/hosting/lagoon.mdx +++ b/.vortex/docs/content/hosting/lagoon.mdx @@ -78,6 +78,6 @@ For CI environments, configure these secrets in your CI provider ([GitHub Action Download a database backup from your Lagoon environment for local development or CI builds: -```bash +```shell ahoy download-db ``` diff --git a/.vortex/docs/content/installation.mdx b/.vortex/docs/content/installation.mdx index 7286d98a7..c8bcca777 100644 --- a/.vortex/docs/content/installation.mdx +++ b/.vortex/docs/content/installation.mdx @@ -119,5 +119,5 @@ See onboarding guides for [Acquia](./hosting/acquia#onboarding) or ## Updating Vortex -Head to [Updating Vortex](./workflows/updating-vortex) for detailed +Head to [Updating Vortex](./updating-vortex) for detailed instructions on how to update your project to the latest version of **Vortex**. diff --git a/.vortex/docs/content/releasing/README.mdx b/.vortex/docs/content/releasing/README.mdx new file mode 100644 index 000000000..5a675e2bd --- /dev/null +++ b/.vortex/docs/content/releasing/README.mdx @@ -0,0 +1,132 @@ +--- +sidebar_label: Overview +sidebar_position: 1 +--- + +# Releasing + +Software releases are a critical part of the development lifecycle. A well-structured release process ensures code quality, minimizes deployment risks, and maintains clear communication across teams. + +A typical release process consists of several key components: + +1. **Release Manager** - A person or team responsible for coordinating and executing releases +2. **Release Flow** - The sequence of environments and steps code goes through from development to production +3. **Versioning Workflow** - The branching strategy that governs how code moves through environments (GitFlow being the most common) +4. **Version Scheme** - The numbering system used to identify releases (CalVer, SemVer, or custom) +5. **Release Documentation** - Runsheets, checklists, and procedures stored in accessible locations +6. **Automated Deployment** - CI/CD pipelines that handle the technical deployment process + +**Vortex** provides comprehensive support for all these components, with sensible defaults and integration points for popular hosting platforms. + +## Release flow + +Projects typically follow a three-tier environment strategy with clear directional flows: + +```mermaid +graph LR + Dev[Development] -->|code| Stage[Stage] + Stage -->|code| Prod[Production] + Prod -.->|database| Stage + Stage -.->|database| Dev + + style Dev fill:#e1f5ff + style Stage fill:#fff4e1 + style Prod fill:#e8f5e9 +``` + +- **Development** - Latest development code, not yet released. May be unstable, but CI tests should pass. +- **Stage** - Pre-production environment. Mirrors production as closely as possible. Used for final release testing. +- **Production** - Live customer-facing application. Stable and reliable. Source of truth for data. + +:::info Environment Agreement +The specific environment setup (dev/stage/production) should be agreed upon within your team and documented in your project. Some teams may use additional environments (e.g., UAT, pre-prod) or different naming conventions. +::: + +Code goes "up" (from lower to higher environments) while database goes "down" (from higher to lower environments). + +This means that the production database is the primary source of truth - it's what code is applied to. When performing a release, you are applying a new version of code to a database within a specific environment. + +To ensure that code changes work correctly with real data structures, the following process is followed in lower environments: + +1. Database is copied from a higher environment to a lower one (e.g., production → stage → development) +2. Code is deployed to that environment to be tested against the copied database +3. Testing is performed to ensure everything works correctly + +:::tip +CI pipelines also use a copy of the production database (refreshed daily) to run all tests, ensuring code changes work with real data structures. +::: + +You would use a Versioning Workflow (like GitFlow) to manage how code moves +across releases using the Version Scheme (like CalVer or SemVer). + +You would document your release procedures in Release Documentation (like +`docs/releasing.md`) and create a release runsheet to guide release managers +through the release process. + +Finally, the actual deployment to production is handled via Automated Deployment +where, based on your hosting provider, the deployment process is fully automated. + +## Production deployment process + +Once code is finalized and pushed, the deployment process to production is technically identical to deploying to other environments and is **fully automated**. + +For Acquia and Lagoon hosting, **Vortex** integrates directly with their deployment systems to ensure smooth releases. + +For other hosting providers, you can integrate the provision steps into your hosting deployment configuration if it supports post-deployment hooks or custom scripts. + +➡️ See [Drupal > Provision](/docs/drupal/provision#provisioning-flow) to learn more about what provisioning steps are performed during deployments. + +## Documentation + +### `docs/releasing.md` + +Your project includes a `docs/releasing.md` file that serves as the canonical release documentation for your team. This file contains: + +- **Version scheme summary** - Which versioning system your project uses (CalVer, SemVer, or Other) +- **GitFlow instructions** - Step-by-step guide for your specific git-flow setup +- **Release procedures** - Custom procedures specific to your project + +You can extend this file with: + +- **Detailed release procedures** - A comprehensive outline of _what_ actions to take during releases: + - Steps to create and finish releases + - Steps to deploy to production + - Steps to rollback + - Steps to verify releases +- **Release run template** - A detailed checklist of _who_ does _what_ and _when_ during releases. This would be cloned into a separate runsheet for each release. + +## Monitoring + +### New Relic integration + +**Vortex** provides integration with New Relic for release tracking and monitoring. + +**Deployment Markers**: When configured, **Vortex** automatically creates deployment markers in New Relic when releases are deployed to your environments. These markers help correlate performance changes, errors, and other metrics with specific releases. + +**Benefits**: + +- Visualize before/after release performance +- Correlate errors with specific deployments +- Track deployment frequency +- Monitor release impact in real-time + +➡️ See [Deployment > Notifications](/docs/deployment/notifications) + +## Best practices + +1. **Always use release branches** - Never release directly from `develop` or feature branches +2. **Backup before release** - Ensure you have recent backups of code and data +3. **Document your process** - Keep `docs/releasing.md` updated with team conventions +4. **Automate everything possible** - Leverage **Vortex**'s automation capabilities +5. **Test in Stage first** - Always validate releases in a production-like environment +6. **Communicate releases** - Notify stakeholders before, during, and after releases +7. **Monitor post-release** - Watch metrics and logs for issues after deployment +8. **Have a rollback plan** - Document and test your rollback procedures +9. **Use consistent versioning** - Stick to your chosen version scheme + +## See also + +| Topic | Description | +|-------|-------------| +| [GitFlow](gitflow) | Branch structure and release operations | +| [Versioning](versioning) | CalVer, SemVer, and custom version schemes | diff --git a/.vortex/docs/content/releasing/gitflow.mdx b/.vortex/docs/content/releasing/gitflow.mdx new file mode 100644 index 000000000..acb2bca76 --- /dev/null +++ b/.vortex/docs/content/releasing/gitflow.mdx @@ -0,0 +1,121 @@ +--- +sidebar_label: GitFlow +sidebar_position: 2 +--- + +# GitFlow versioning workflow + +[git-flow](https://nvie.com/posts/a-successful-git-branching-model/) is a +versioning workflow that allows you to maintain clean separation between development +and production code. + +It allows you to have a stable development branch (`develop`) and a production-ready +branch (`main`), while providing dedicated branches for feature development, +release preparation, and hotfixes. + +```mermaid +gitGraph + commit id: "Initial" + branch develop + checkout develop + commit id: "Feature work" + branch feature/new-feature + checkout feature/new-feature + commit id: "Feature commits" + checkout develop + merge feature/new-feature + commit id: "More work" + branch release/1.0.0 + checkout release/1.0.0 + commit id: "Version bump" + commit id: "Bug fixes" + checkout main + merge release/1.0.0 tag: "v1.0.0" + checkout develop + merge release/1.0.0 + checkout develop + commit id: "Continue dev" + checkout main + branch hotfix/1.0.1 + checkout hotfix/1.0.1 + commit id: "Critical fix" + checkout main + merge hotfix/1.0.1 tag: "v1.0.1" + checkout develop + merge hotfix/1.0.1 +``` + +## Branch structure + +- **`develop`** - Development branch where features are integrated +- **`main`** - Production-ready code, always stable and tagged with releases +- **`feature/*`** - Individual feature development branches +- **`release/*`** - Release preparation branches (e.g., `release/25.1.0`) +- **`hotfix/*`** - Emergency fixes for production (e.g., `hotfix/25.1.1`) + +
+ `production` branch + + Most hosting providers support deploying specific git tags directly. In this + case, no separate `production` branch is needed - you simply tag releases on + `main` and deploy those tags. + + Some hosting providers (like **Lagoon**) require a git branch to deploy from, + so tag-based deployments are not supported. In this case, you must create a + `production` branch and sync code from `main` to `production` after each + release. + + While it's possible to automate copying `main` to `production` on tag creation + via CI/CD, this automation was conceptually avoided to prevent accidental + deployments to production without human oversight. + +
+ +## Release operations + +Below are the typical steps to perform a release using git-flow. See [cheat sheet](https://danielkummer.github.io/git-flow-cheatsheet/) for a quick reference on git-flow commands. + +1. **Start Release** + + ```shell + git flow release start X.Y.Z + ``` + + Creates a `release/X.Y.Z` branch from `develop`. It is recommended to push + the branch to remote. + +2. **Release Preparation** + - Final bug fixes + - Documentation updates + - Release notes preparation + +3. **Finish Release** + + ```shell + git flow release finish X.Y.Z + ``` + + - Merges release branch to `main` + - Tags the release + - Merges back to `develop` + - Deletes the release branch + +4. **Deploy to Production** + - **Tag-based hosting:** Deploy the tag directly + - **Branch-based hosting (e.g., Lagoon):** Manually sync to `production` branch + + ```shell + git push origin main:production + ``` + +## Expected release outcome + +A successful release should meet these criteria: + +1. Release branch exists as `release/X.Y.Z` in GitHub repository +2. Release tag exists as `X.Y.Z` in GitHub repository +3. The `HEAD` of the `main` branch has `X.Y.Z` tag +4. The hash of the `HEAD` of the `main` branch exists in the `develop` branch + - This ensures everything pushed to `main` exists in `develop` + - Important if `main` had any hotfixes not yet merged to `develop` +5. There are no open PRs in GitHub related to the release diff --git a/.vortex/docs/content/releasing/versioning.mdx b/.vortex/docs/content/releasing/versioning.mdx new file mode 100644 index 000000000..fc3a38eed --- /dev/null +++ b/.vortex/docs/content/releasing/versioning.mdx @@ -0,0 +1,75 @@ +--- +sidebar_label: Versioning +sidebar_position: 3 +--- + +# Version scheme + +**Vortex** supports [CalVer](https://calver.org/) and [SemVer](https://semver.org/) version numbering schemes to fit different project needs. + +During installation, you can choose between Calendar Versioning (CalVer), Semantic Versioning (SemVer), or a custom scheme. + +## Calendar versioning (CalVer) + +**Format:** `YY.M.Z` (e.g., `25.1.0`, `25.11.1`) + +- `YY` = Short year (no leading zeroes) +- `M` = Short month (no leading zeroes) +- `Z` = Hotfix/patch version (no leading zeroes) + +### Why CalVer + +- **Release frequency transparency**: When you have multiple releases per month, dates make it easy to identify when a release happened +- **Intuitive tracking**: Stakeholders can immediately understand "this is from January 2025" vs memorizing version numbers +- **Natural progression**: No ambiguity about major vs minor changes - just the chronological order +- **Marketing alignment**: Easier to communicate to non-technical audiences ("our Q1 2025 release") + +### Examples + +- ✅ Correct: `25.1.0`, `25.11.1`, `25.1.10`, `25.10.1`, `9.12.0` +- ❌ Incorrect: `25.0.0` (no month 0), `2025.1.1` (full year), `25.01.0` (leading zero), `01.1.0` (leading zero in year) + +Learn more: [CalVer.org](https://calver.org/) + +## Semantic versioning (SemVer) + +**Format:** `X.Y.Z` (e.g., `1.0.0`, `2.3.5`) + +- `X` = Major release version (no leading zeroes) +- `Y` = Minor release version (no leading zeroes) +- `Z` = Hotfix/patch version (no leading zeroes) + +### Why SemVer + +- **Breaking change communication**: Major version bump signals incompatible API changes +- **Dependency management**: Package managers can enforce compatible version ranges +- **Developer expectations**: Well-understood convention in the development community +- **Predictable upgrades**: Minor versions add functionality, patches fix bugs + +### Examples + +- ✅ Correct: `0.1.0`, `1.0.0`, `1.0.1`, `1.0.10` +- ❌ Incorrect: `0.1` (missing patch), `1` (missing minor and patch), `1.0.01` (leading zero) + +Learn more: [SemVer.org](https://semver.org/) + +## Other + +Choose "Other" if you have a custom versioning scheme or don't want to commit to CalVer or SemVer. This option removes both versioning templates from your documentation, allowing you to define your own approach. + +## Configuration + +Your project's version scheme is configured once during installation and stored in `.env`: + +```shell +VORTEX_RELEASE_VERSION_SCHEME=calver # or semver, or other +``` + +### Release notes publishing + +For CalVer and SemVer projects, **Vortex** provides a GitHub Actions workflow to automate release notes drafting: + +- **Draft release notes** are automatically updated when commits are pushed to the `develop` branch +- Next version is calculated based on your version scheme +- Release notes accumulate changes until the release is finalized +- On release finish, you can use the draft to publish the final release notes diff --git a/.vortex/docs/content/support.mdx b/.vortex/docs/content/support.mdx index 9d26bc80e..5f8b7034c 100644 --- a/.vortex/docs/content/support.mdx +++ b/.vortex/docs/content/support.mdx @@ -18,7 +18,7 @@ New to **Vortex**? Start with our [Installation Guide](/docs/installation) and t Start with these resources to solve common issues quickly: -- 📖 **[Documentation](/docs)** - Comprehensive guides and workflows +- 📖 **[Documentation](/docs)** - Comprehensive guides and references - ❓ **[FAQs](/docs/faqs)** - Frequently asked questions - 🩺 **Doctor Tool** - Run `ahoy doctor` to diagnose common issues diff --git a/.vortex/docs/content/tools/README.mdx b/.vortex/docs/content/tools/README.mdx index 786187b6e..d441fd2b2 100644 --- a/.vortex/docs/content/tools/README.mdx +++ b/.vortex/docs/content/tools/README.mdx @@ -36,4 +36,3 @@ Head over to the tool-specific documentation to learn more. | [Rector](rector.mdx) | Instant Upgrades and Automated Refactoring | | [Renovate](renovate.mdx) | A bot for automated dependency updates | | [Twig CS Fixer](twig-cs-fixer.mdx) | Checkstyle for Twig | -| [Xdebug](xdebug.mdx) | Debugger and Profiler Tool for PHP | diff --git a/.vortex/docs/content/tools/ahoy.mdx b/.vortex/docs/content/tools/ahoy.mdx index 11a04d8ca..ab7f268f3 100644 --- a/.vortex/docs/content/tools/ahoy.mdx +++ b/.vortex/docs/content/tools/ahoy.mdx @@ -7,7 +7,7 @@ https://github.com/ahoy-cli/ahoy > Ahoy is command line tool that gives each of your projects their own CLI app with zero code and dependencies. -Usually, Ahoy is used to wrap the commands to make the development workflow +Usually, Ahoy is used to wrap the commands to make the development process consistent and easy to use. **Vortex** comes with [pre-configured `.ahoy.yml`](https://github.com/drevops/vortex/blob/main/.ahoy.yml) that has @@ -68,4 +68,4 @@ The configuration is set up to load environment variables from `.env` and `.env.local` files, giving the precedence to the values in the existing environment. -➡️ See [Workflows > Variables](../workflows/variables.mdx) +➡️ See [Variables](../development/variables.mdx) diff --git a/.vortex/docs/content/tools/docker.mdx b/.vortex/docs/content/tools/docker.mdx index b09fe901f..547fa8e05 100644 --- a/.vortex/docs/content/tools/docker.mdx +++ b/.vortex/docs/content/tools/docker.mdx @@ -80,8 +80,8 @@ and in the continuous integration pipeline. Some of the commands are wrapped in the Ahoy script as a shorthand. But all the commands can be run directly using `docker compose` command. -Specific commands are described in the relevant [workflows](/docs/workflows) -sections. +Specific commands are described in the relevant [Development](/docs/development) +documentation. ## Understanding `docker-compose.yml` diff --git a/.vortex/docs/content/tools/drush.mdx b/.vortex/docs/content/tools/drush.mdx index 62dcd5015..07e626757 100644 --- a/.vortex/docs/content/tools/drush.mdx +++ b/.vortex/docs/content/tools/drush.mdx @@ -7,7 +7,7 @@ https://www.drush.org/ > update.php, executes SQL queries, runs content migrations, and misc utilities > like cron or cache rebuild. Drush can be extended by 3rd party commandfiles. -Drush is used throughout **Vortex** to interact with Drupal from the workflow +Drush is used throughout **Vortex** to interact with Drupal from the automation scripts and Behat tests. It also allows a developer to interact with the site via CLI during development. @@ -19,7 +19,7 @@ shorthand commands to abstract some of the common tasks: - importing the database dump into the local environment - running database updates and clearing caches -➡️ See [Workflows](/docs/workflows) +➡️ See [Development](/docs/development) ## Usage diff --git a/.vortex/docs/content/tools/rector.mdx b/.vortex/docs/content/tools/rector.mdx index 7455775fb..b49b3047a 100644 --- a/.vortex/docs/content/tools/rector.mdx +++ b/.vortex/docs/content/tools/rector.mdx @@ -153,7 +153,7 @@ Clear Rector cache in these situations: 2. **After updating Rector or Drupal Rector packages** - ```bash + ```shell composer update rector/rector palantirnet/drupal-rector ``` diff --git a/.vortex/docs/content/workflows/updating-vortex.mdx b/.vortex/docs/content/updating-vortex.mdx similarity index 95% rename from .vortex/docs/content/workflows/updating-vortex.mdx rename to .vortex/docs/content/updating-vortex.mdx index d938baa78..34847ea18 100644 --- a/.vortex/docs/content/workflows/updating-vortex.mdx +++ b/.vortex/docs/content/updating-vortex.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 9 +sidebar_position: 8 --- # Updating Vortex @@ -12,7 +12,7 @@ update it to get the latest features and bug fixes without losing your project c Updating **Vortex** allows existing projects to benefit from: - Security patches and bug fixes -- New features and workflow improvements +- New features and improvements - Updated dependencies and tooling - Enhanced deployment capabilities @@ -97,4 +97,6 @@ Specifically check if any environment variables were added or changed. ## Getting help -If you encounter issues during updates, see [Support](/docs/support) page. +If you encounter issues during updates: + +➡️ See [Support](/docs/support) diff --git a/.vortex/docs/content/workflows/README.mdx b/.vortex/docs/content/workflows/README.mdx deleted file mode 100644 index 405ad96ca..000000000 --- a/.vortex/docs/content/workflows/README.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -sidebar_label: Overview -sidebar_position: 1 -hide_table_of_contents: true ---- - -# Workflows - -> _A workflow is a sequence of steps to achieve a goal_ - -This section provides an overview of the key workflows involved in website -development, testing, deployment, and maintenance. Each subsection contains -detailed documentation on specific workflows. - -## Available workflows - -- [Development](development) -- [Testing](testing) -- [Deployment](deployment) -- [Notifications](notifications) -- [Releasing](releasing) -- [Configuration Variables](variables) -- [Updating Vortex](updating-vortex) - -Refer to the linked sections for detailed instructions. - -## Complete code lifecycle - -The diagram below shows how all workflows connect together - from local development -through continuous integration, to deployment and hosting: - -import CodeLifecycle from './_code-lifecycle.mdx'; - - diff --git a/.vortex/docs/content/workflows/notifications.mdx b/.vortex/docs/content/workflows/notifications.mdx deleted file mode 100644 index 106e5e6c3..000000000 --- a/.vortex/docs/content/workflows/notifications.mdx +++ /dev/null @@ -1,365 +0,0 @@ ---- -sidebar_label: Notifications -sidebar_position: 4 ---- - -# Notifications - -**Vortex** provides a flexible notification system that sends updates -across multiple channels. - -Notifications are triggered automatically during deployment to a -hosting environment, and can be configured to suit your team's -communication needs. - -## Channels - -Configure notification channels in your `.env` file: - -```bash title=".env" -# Enable notification channels (comma-separated list) -VORTEX_NOTIFY_CHANNELS=email,slack,github -``` - -Available channels: [`email`](#email), [`github`](#github), -[`jira`](#jira), [`newrelic`](#new-relic), [`slack`](#slack), -[`webhook`](#webhook) - -## Global environment variables - -These variables apply to all notification channels unless overridden by -channel-specific settings. - -| Variable | Required | Default | Location | Description | -|----------------------------------|----------|-----------------------------------------------|----------|-----------------------------------------------------------------------------------| -| `VORTEX_NOTIFY_CHANNELS` | No | `email` | `.env` | Notification channels (comma-separated: email,slack,newrelic,github,jira,webhook) | -| `VORTEX_NOTIFY_PROJECT` | No | `VORTEX_PROJECT` | `.env` | Notification project name | -| `VORTEX_NOTIFY_SKIP` | No | | Hosting | Notification skip flag (set to `1` to skip notifications) | - -## Deployment context variables - -These variables provide deployment context information used by notification -channels. They must be set by the hosting environment (e.g., Lagoon, Acquia) -before calling the notification script. - -| Variable | Required | Description | -|---------------------------|----------|-----------------------------------------------------------------| -| `VORTEX_NOTIFY_BRANCH` | **Yes** | Git branch name (used for GitHub API and JIRA issue extraction) | -| `VORTEX_NOTIFY_SHA` | **Yes** | Git commit SHA (used for New Relic revision tracking) | -| `VORTEX_NOTIFY_PR_NUMBER` | No | Pull request number (empty for branch deployments) | -| `VORTEX_NOTIFY_LABEL` | **Yes** | Human-readable deployment label for display | - -### Branch vs PR deployment examples - -The following table shows how these variables differ between branch and PR deployments: - -| Variable | Branch deployment | PR deployment | -|----------------------------|-----------------------------|-----------------------------------| -| `VORTEX_NOTIFY_BRANCH` | `main` | `feature/PROJ-123-add-feature` | -| `VORTEX_NOTIFY_SHA` | `abc123def456` | `def789abc012` | -| `VORTEX_NOTIFY_PR_NUMBER` | *(empty)* | `123` | -| `VORTEX_NOTIFY_LABEL` | `main` | `PR-123` | - -## Message templates and tokens - -Most notification channels support customizable message templates using replacement tokens: - -| Token | Description | Example | -|--------------------|--------------------------------------------------|-----------------------------------| -| `%project%` | Project name | `My Project` | -| `%label%` | Deployment label (branch, PR, or custom ID) | `main` or `PR-123` | -| `%timestamp%` | Current timestamp | `15/11/2025 14:30:45 UTC` | -| `%environment_url%`| Environment URL | `https://example.com` | -| `%login_url%` | Login URL | `https://example.com/user/login` | - -These tokens are replaced with actual values when the notification is sent. - -**Default message template:** - -```text -## This is an automated message ## - -Site %project% %label% has been deployed at %timestamp% and is available at %environment_url%. - -Login at: %login_url% -``` - -This default template is used for Email and JIRA notifications when no custom message is specified. - -## Email - -Send deployment notification via email. - -### Setup - -1. Add `VORTEX_NOTIFY_EMAIL_FROM` variable to `.env` file with the - value of the email address that is allowed to be sent from your - hosting. -2. Add `VORTEX_NOTIFY_EMAIL_RECIPIENTS` variable to `.env` file with a - list of recipients in format - `webmaster@your-site-domain.example|Webmaster` (comma-separated for - multiple recipients). - -### Environment variables - -| Variable | Required | Default | Location | Description | -|---------------------------------------|----------|--------------------------------------|----------|-------------------------------------------------------| -| `VORTEX_NOTIFY_EMAIL_FROM` | **Yes** | | `.env` | Email notification sender address | -| `VORTEX_NOTIFY_EMAIL_RECIPIENTS` | **Yes** | | `.env` | Email notification recipients (format: `email\|name`) | -| `VORTEX_NOTIFY_EMAIL_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | `.env` | Email notification project name | -| `VORTEX_NOTIFY_EMAIL_MESSAGE` | No | (template using tokens) | `.env` | Email notification message template | - -### Example - -**Subject:** - -```text -My Project deployment notification of main -``` - -**Body:** - -```text -## This is an automated message ## - -Site My Project main has been deployed at 15/01/2025 14:30:45 UTC and is available at https://example.com. - -Login at: https://example.com/user/login -``` - -## GitHub - -GitHub supports deployment statuses and environment links. **Vortex** can -automatically post deployment status to GitHub pull requests. - -### Setup - -1. [Create a GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). -2. Add `VORTEX_NOTIFY_GITHUB_TOKEN` variable to your hosting - provider's global environment variables. -3. Add `VORTEX_NOTIFY_GITHUB_REPOSITORY` variable to your hosting - provider's global environment variables. - -### Environment variables - -| Variable | Required | Default | Location | Description | -|----------------------------------------|----------|---------------------------------|----------|-----------------------------------------------------------| -| `VORTEX_NOTIFY_GITHUB_TOKEN` | **Yes** | | Hosting | GitHub notification personal access token | -| `VORTEX_NOTIFY_GITHUB_REPOSITORY` | **Yes** | | Hosting | GitHub notification repository in `owner/repo` format | -| `VORTEX_NOTIFY_GITHUB_ENVIRONMENT_TYPE`| No | `PR` | `.env` | GitHub notification environment type (production/staging/uat/dev/pr) | - -### Example - -The pull request page in GitHub has information about the deployment -status. - -![notification-github-before.png](/img/notification-github-before.png) - -When deployment starts, a notification is posted to GitHub with -`Deployment Starting` status. - -![notification-github-during.png](/img/notification-github-during.png) - -After deployment succeeds, a notification is posted to GitHub. You can use a -`View deployment` button to quickly access the deployed environment. - -![notification-github-after.png](/img/notification-github-after.png) - -## JIRA - -Post a deployment comment and, optionally, update issue status and -assignee in JIRA. - -### Setup - -1. [Create a JIRA API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/). -2. Add `VORTEX_NOTIFY_JIRA_TOKEN` variable to your hosting provider's - global environment variables. -3. Add `VORTEX_NOTIFY_JIRA_USER_EMAIL` variable to `.env` file. - Example: - - ```bash - VORTEX_NOTIFY_JIRA_USER_EMAIL="your.email@example.com" - ``` - -4. Optionally, add `VORTEX_NOTIFY_JIRA_ASSIGNEE_EMAIL` variable to `.env` file if you - would like the issue to be assigned to this user once the deployment - is complete. - Example: - - ```bash - VORTEX_NOTIFY_JIRA_ASSIGNEE_EMAIL="assignee@example.com" - ``` - -5. Optionally, add `VORTEX_NOTIFY_JIRA_TRANSITION` variable to `.env` file with a - transition name if you would like the issue to be transitioned to - once the deployment is complete. - Example: - - ```bash - VORTEX_NOTIFY_JIRA_TRANSITION="In Review" - ``` - -### Environment variables - -| Variable | Required | Default | Location | Description | -|----------------------------------|----------|------------------------------|----------|--------------------------------------------------------------------| -| `VORTEX_NOTIFY_JIRA_TOKEN` | **Yes** | | Hosting | JIRA notification API token | -| `VORTEX_NOTIFY_JIRA_USER_EMAIL` | **Yes** | | `.env` | JIRA notification user email address | -| `VORTEX_NOTIFY_JIRA_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | `.env` | JIRA notification project name | -| `VORTEX_NOTIFY_JIRA_MESSAGE` | No | (template using tokens) | `.env` | JIRA notification message template | -| `VORTEX_NOTIFY_JIRA_ASSIGNEE_EMAIL` | No | | `.env` | JIRA notification assignee email address | -| `VORTEX_NOTIFY_JIRA_TRANSITION` | No | | `.env` | JIRA notification state to transition to | -| `VORTEX_NOTIFY_JIRA_ENDPOINT` | No | `https://jira.atlassian.com` | `.env` | JIRA notification API endpoint | - -### Example - -The notification system automatically extracts the JIRA issue key from the deployment label using the pattern `[A-Za-z0-9]+-[0-9]+`. The extraction is **case-insensitive** and will accept mixed-case input, but typical JIRA project keys are uppercase letters followed by a number (so you may see `PROJ-123` or `proj-123`). For example: - -- Label: `feature/PROJ-123-add-feature` → Issue key: `PROJ-123` -- Label: `feature/proj-123-add-feature` → Issue key: `proj-123` -- Label: `feature/PRJ-456-fix-auth` → Issue key: `PRJ-456` - -**Comment posted to JIRA issue:** - -```text -## This is an automated message ## - -Site My Project main has been deployed at 15/11/2025 14:30:45 UTC and is available at https://example.com. - -Login at: https://example.com/user/login -``` - -The environment URL and login URL are displayed as inline links in JIRA's Atlassian Document Format (ADF). - -## New Relic - -[Deployment markers](https://docs.newrelic.com/docs/apm/apm-ui-pages/events/record-deployments/) -help you track code changes in New Relic APM by associating them with -application performance data. **Vortex** can automatically create deployment -markers in New Relic APM when a deployment is performed. - -### Setup - -1. [Create a New Relic User API Key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#user-key): - - Log in to New Relic - - Click on your profile icon (bottom left) - - Go to "API keys" - - Create or copy an existing "User key" - - The key format is: `NRAK-XXXXXXXXXXXXXXXXXXXXXX` -2. Add `NEWRELIC_ENABLED` (or `VORTEX_NOTIFY_NEWRELIC_ENABLED`) variable - to your hosting provider's environment variables for environments where - New Relic is configured. This prevents unnecessary API calls in environments - without New Relic. -3. Add `VORTEX_NOTIFY_NEWRELIC_USER_KEY` variable to your hosting - provider's global environment variables. -4. Optionally, add other New Relic-related variables to your `.env` - file to customize the notification. - -:::tip Enable only where needed - -Set `NEWRELIC_ENABLED=true` only in environments where New Relic APM is configured -(typically production and staging). This avoids API calls and potential errors -in development or feature branch environments that don't have New Relic set up. - -::: - -### Environment variables - -| Variable | Required | Default | Location | Description | -|-----------------------------------------|----------|-----------------------------------------------|----------|-------------------------------------------------------------------| -| `VORTEX_NOTIFY_NEWRELIC_ENABLED` | **Yes** | `NEWRELIC_ENABLED` | Hosting | Enable New Relic notifications (set to `1` or `true`) | -| `VORTEX_NOTIFY_NEWRELIC_USER_KEY` | **Yes** | | Hosting | New Relic User API Key (format: `NRAK-XXXXXXXXXXXXXXXXXXXXXX`) | -| `VORTEX_NOTIFY_NEWRELIC_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | `.env` | New Relic notification project name | -| `VORTEX_NOTIFY_NEWRELIC_APP_NAME` | No | `${PROJECT}-${LABEL}` (auto-generated) | `.env` | New Relic notification application name | -| `VORTEX_NOTIFY_NEWRELIC_DESCRIPTION` | No | (template using tokens) | `.env` | New Relic notification deployment description | -| `VORTEX_NOTIFY_NEWRELIC_CHANGELOG` | No | `VORTEX_NOTIFY_NEWRELIC_DESCRIPTION` | `.env` | New Relic notification deployment changelog | -| `VORTEX_NOTIFY_NEWRELIC_USER` | No | `Deployment robot` | `.env` | New Relic notification user performing deployment | -| `VORTEX_NOTIFY_NEWRELIC_ENDPOINT` | No | `https://api.newrelic.com/v2` | `.env` | New Relic notification API endpoint | - -### Example - -Deployment marker created in New Relic APM: - -New Relic deployment marker - -## Slack - -Post deployment notification to Slack a channel. - -### Setup - -1. [Create a Slack app and Incoming Webhook](https://api.slack.com/messaging/webhooks). -2. Add `VORTEX_NOTIFY_SLACK_WEBHOOK` variable to your hosting - provider's global environment variables. -3. Optionally, add other Slack-related variables to your `.env` file to - customize the notification. - -### Environment variables - -| Variable | Required | Default | Location | Description | -|---------------------------------------|----------|---------------------------------|----------|---------------------------------------------------------------| -| `VORTEX_NOTIFY_SLACK_WEBHOOK` | **Yes** | | Hosting | Slack notification webhook URL | -| `VORTEX_NOTIFY_SLACK_PROJECT` | No | `VORTEX_NOTIFY_PROJECT` | `.env` | Slack notification project name | -| `VORTEX_NOTIFY_SLACK_MESSAGE` | No | (template using tokens) | `.env` | Slack notification fallback text template | -| `VORTEX_NOTIFY_SLACK_CHANNEL` | No | | `.env` | Slack notification target channel (overrides webhook default) | -| `VORTEX_NOTIFY_SLACK_USERNAME` | No | `Deployment Bot` | `.env` | Slack notification bot display name | -| `VORTEX_NOTIFY_SLACK_ICON_EMOJI` | No | `:rocket:` | `.env` | Slack notification bot icon emoji | - -### Event behavior - -Slack notifications are sent for both `pre_deployment` and `post_deployment` events: - -- **Pre-deployment:** Gray color with "Deployment Starting" status -- **Post-deployment:** Green color with "Deployment Complete" status - -### Example - -When deployment starts, a notification is posted to Slack by the "VortexBot" -Slack app with `Deployment Starting` status: - -Slack notification - Deployment Starting - -After deployment succeeds, a notification is posted to Slack by the "VortexBot" -Slack app with `Deployment Complete` status: - -Slack notification - Deployment Complete - -## Webhook - -Send HTTP request to an arbitrary webhook URL. - -### Setup - -1. Add `VORTEX_NOTIFY_WEBHOOK_URL` variable to your `.env` file or - hosting provider's global environment variables. -2. Optionally, add other webhook-related variables to your `.env` file - to customize the notification. - -### Environment variables - -| Variable | Required | Default | Location | Description | -|-----------------------------------------|----------|----------------------------------|-------------------|---------------------------------------------| -| `VORTEX_NOTIFY_WEBHOOK_URL` | **Yes** | | `.env` or Hosting | Webhook notification endpoint URL | -| `VORTEX_NOTIFY_WEBHOOK_METHOD` | No | `POST` | `.env` | Webhook notification HTTP method | -| `VORTEX_NOTIFY_WEBHOOK_HEADERS` | No | `Content-Type: application/json` | `.env` | Webhook notification pipe-separated headers | -| `VORTEX_NOTIFY_WEBHOOK_PAYLOAD` | No | (template using tokens) | `.env` | Webhook notification JSON payload | -| `VORTEX_NOTIFY_WEBHOOK_RESPONSE_STATUS` | No | `200` | `.env` | Webhook notification expected HTTP status | - -### Default payload template - -Webhook payloads support all standard tokens plus an additional `%message%` token that expands to the full deployment message with all other tokens replaced. - -```json -{ - "channel": "Channel 1", - "message": "%message%", - "project": "%project%", - "label": "%label%", - "timestamp": "%timestamp%", - "environment_url": "%environment_url%", - "login_url": "%login_url%" -} -``` - -The `%message%` token expands to the deployment message with all other tokens replaced. diff --git a/.vortex/docs/content/workflows/releasing.mdx b/.vortex/docs/content/workflows/releasing.mdx deleted file mode 100644 index a11482e5e..000000000 --- a/.vortex/docs/content/workflows/releasing.mdx +++ /dev/null @@ -1,313 +0,0 @@ ---- -sidebar_label: Releasing -sidebar_position: 5 ---- - -# Releasing - -Software releases are a critical part of the development lifecycle. A well-structured release process ensures code quality, minimizes deployment risks, and maintains clear communication across teams. - -A typical release process consists of several key components: - -1. **Release Manager** - A person or team responsible for coordinating and executing releases -2. **Release Flow** - The sequence of environments and steps code goes through from development to production -3. **Versioning Workflow** - The branching strategy that governs how code moves through environments (GitFlow being the most common) -4. **Version Scheme** - The numbering system used to identify releases (CalVer, SemVer, or custom) -5. **Release Documentation** - Runsheets, checklists, and procedures stored in accessible locations -6. **Automated Deployment** - CI/CD pipelines that handle the technical deployment process - -**Vortex** provides comprehensive support for all these components, with sensible defaults and integration points for popular hosting platforms. - -## Release flow - -Projects typically follow a three-tier environment strategy with clear directional flows: - -```mermaid -graph LR - Dev[Development] -->|code| Stage[Stage] - Stage -->|code| Prod[Production] - Prod -.->|database| Stage - Stage -.->|database| Dev - - style Dev fill:#e1f5ff - style Stage fill:#fff4e1 - style Prod fill:#e8f5e9 -``` - -- **Development** - Latest development code, not yet released. May be unstable, but CI tests should pass. -- **Stage** - Pre-production environment. Mirrors production as closely as possible. Used for final release testing. -- **Production** - Live customer-facing application. Stable and reliable. Source of truth for data. - -:::info Environment Agreement -The specific environment setup (dev/stage/production) should be agreed upon within your team and documented in your project. Some teams may use additional environments (e.g., UAT, pre-prod) or different naming conventions. -::: - -Code goes "up" (from lower to higher environments) while database goes "down" (from higher to lower environments). - -This means that the production database is the primary source of truth - it's what code is applied to. When performing a release, you are applying a new version of code to a database within a specific environment. - -To ensure that code changes work correctly with real data structures, the following process is followed in lower environments: - -1. Database is copied from a higher environment to a lower one (e.g., production → stage → development) -2. Code is deployed to that environment to be tested against the copied database -3. Testing is performed to ensure everything works correctly - -:::tip -CI pipelines also use a copy of the production database (refreshed daily) to run all tests, ensuring code changes work with real data structures. -::: - -You would use a Versioning Workflow (like GitFlow) to manage how code moves -across releases using the Version Scheme (like CalVer or SemVer). - -You would document your release procedures in Release Documentation (like -`docs/releasing.md`) and create a release runsheet to guide release managers -through the release process. - -Finally, the actual deployment to production is handled via Automated Deployment -where, based on your hosting provider, the deployment process is fully automated. - -## GitFlow versioning workflow - -[git-flow](https://nvie.com/posts/a-successful-git-branching-model/) is a -versioning workflow that allows you to maintain clean separation between development -and production code. - -It allows you to have a stable development branch (`develop`) and a production-ready -branch (`main`), while providing dedicated branches for feature development, -release preparation, and hotfixes. - -```mermaid -gitGraph - commit id: "Initial" - branch develop - checkout develop - commit id: "Feature work" - branch feature/new-feature - checkout feature/new-feature - commit id: "Feature commits" - checkout develop - merge feature/new-feature - commit id: "More work" - branch release/1.0.0 - checkout release/1.0.0 - commit id: "Version bump" - commit id: "Bug fixes" - checkout main - merge release/1.0.0 tag: "v1.0.0" - checkout develop - merge release/1.0.0 - checkout develop - commit id: "Continue dev" - checkout main - branch hotfix/1.0.1 - checkout hotfix/1.0.1 - commit id: "Critical fix" - checkout main - merge hotfix/1.0.1 tag: "v1.0.1" - checkout develop - merge hotfix/1.0.1 -``` - -### Branch structure - -- **`develop`** - Development branch where features are integrated -- **`main`** - Production-ready code, always stable and tagged with releases -- **`feature/*`** - Individual feature development branches -- **`release/*`** - Release preparation branches (e.g., `release/25.1.0`) -- **`hotfix/*`** - Emergency fixes for production (e.g., `hotfix/25.1.1`) - -
- `production` branch - - Most hosting providers support deploying specific git tags directly. In this - case, no separate `production` branch is needed - you simply tag releases on - `main` and deploy those tags. - - Some hosting providers (like **Lagoon**) require a git branch to deploy from, - so tag-based deployments are not supported. In this case, you must create a - `production` branch and sync code from `main` to `production` after each - release. - - While it's possible to automate copying `main` to `production` on tag creation - via CI/CD, this automation was conceptually avoided to prevent accidental - deployments to production without human oversight. - -
- -### Release operations - -Below are the typical steps to perform a release using git-flow. See [cheat sheet](https://danielkummer.github.io/git-flow-cheatsheet/) for a quick reference on git-flow commands. - -1. **Start Release** - - ```bash - git flow release start X.Y.Z - ``` - - Creates a `release/X.Y.Z` branch from `develop`. It is recommended to push - the branch to remote. - -2. **Release Preparation** - - Final bug fixes - - Documentation updates - - Release notes preparation - -3. **Finish Release** - - ```bash - git flow release finish X.Y.Z - ``` - - - Merges release branch to `main` - - Tags the release - - Merges back to `develop` - - Deletes the release branch - -4. **Deploy to Production** - - **Tag-based hosting:** Deploy the tag directly - - **Branch-based hosting (e.g., Lagoon):** Manually sync to `production` branch - - ```bash - git push origin main:production - ``` - -#### Expected release outcome - -A successful release should meet these criteria: - -1. Release branch exists as `release/X.Y.Z` in GitHub repository -2. Release tag exists as `X.Y.Z` in GitHub repository -3. The `HEAD` of the `main` branch has `X.Y.Z` tag -4. The hash of the `HEAD` of the `main` branch exists in the `develop` branch - - This ensures everything pushed to `main` exists in `develop` - - Important if `main` had any hotfixes not yet merged to `develop` -5. There are no open PRs in GitHub related to the release - -## Version scheme - -**Vortex** supports [CalVer](https://calver.org/) and [SemVer](https://semver.org/) version numbering schemes to fit different project needs. - -During installation, you can choose between Calendar Versioning (CalVer), Semantic Versioning (SemVer), or a custom scheme. - -### Calendar versioning (CalVer) - -**Format:** `YY.M.Z` (e.g., `25.1.0`, `25.11.1`) - -- `YY` = Short year (no leading zeroes) -- `M` = Short month (no leading zeroes) -- `Z` = Hotfix/patch version (no leading zeroes) - -#### Why CalVer - -- **Release frequency transparency**: When you have multiple releases per month, dates make it easy to identify when a release happened -- **Intuitive tracking**: Stakeholders can immediately understand "this is from January 2025" vs memorizing version numbers -- **Natural progression**: No ambiguity about major vs minor changes - just the chronological order -- **Marketing alignment**: Easier to communicate to non-technical audiences ("our Q1 2025 release") - -#### Examples - -- ✅ Correct: `25.1.0`, `25.11.1`, `25.1.10`, `25.10.1`, `9.12.0` -- ❌ Incorrect: `25.0.0` (no month 0), `2025.1.1` (full year), `25.01.0` (leading zero), `01.1.0` (leading zero in year) - -Learn more: [CalVer.org](https://calver.org/) - -### Semantic versioning (SemVer) - -**Format:** `X.Y.Z` (e.g., `1.0.0`, `2.3.5`) - -- `X` = Major release version (no leading zeroes) -- `Y` = Minor release version (no leading zeroes) -- `Z` = Hotfix/patch version (no leading zeroes) - -#### Why SemVer - -- **Breaking change communication**: Major version bump signals incompatible API changes -- **Dependency management**: Package managers can enforce compatible version ranges -- **Developer expectations**: Well-understood convention in the development community -- **Predictable upgrades**: Minor versions add functionality, patches fix bugs - -#### Examples - -- ✅ Correct: `0.1.0`, `1.0.0`, `1.0.1`, `1.0.10` -- ❌ Incorrect: `0.1` (missing patch), `1` (missing minor and patch), `1.0.01` (leading zero) - -Learn more: [SemVer.org](https://semver.org/) - -### Other - -Choose "Other" if you have a custom versioning scheme or don't want to commit to CalVer or SemVer. This option removes both versioning templates from your documentation, allowing you to define your own approach. - -### Configuration - -Your project's version scheme is configured once during installation and stored in `.env`: - -```bash -VORTEX_RELEASE_VERSION_SCHEME=calver # or semver, or other -``` - -#### Release notes publishing - -For CalVer and SemVer projects, **Vortex** provides a GitHub Actions workflow to automate release notes drafting: - -- **Draft release notes** are automatically updated when commits are pushed to the `develop` branch -- Next version is calculated based on your version scheme -- Release notes accumulate changes until the release is finalized -- On release finish, you can use the draft to publish the final release notes - -## Production deployment process - -Once code is finalized and pushed, the deployment process to production is technically identical to deploying to other environments and is **fully automated**. - -For Acquia and Lagoon hosting, **Vortex** integrates directly with their deployment systems to ensure smooth releases. - -For other hosting providers, you can integrate the provision steps into your hosting deployment configuration if it supports post-deployment hooks or custom scripts. - -See [Provisioning documentation](/docs/drupal/provision#provisioning-flow) to learn more about what provisioning steps are performed during deployments. - -## Documentation - -### `docs/releasing.md` - -Your project includes a `docs/releasing.md` file that serves as the canonical release documentation for your team. This file contains: - -- **Version scheme summary** - Which versioning system your project uses (CalVer, SemVer, or Other) -- **GitFlow instructions** - Step-by-step guide for your specific git-flow setup -- **Release procedures** - Custom workflows specific to your project - -You can extend this file with: - -- **Detailed release procedures** - A comprehensive outline of _what_ actions to take during releases: - - Steps to create and finish releases - - Steps to deploy to production - - Steps to rollback - - Steps to verify releases -- **Release run template** - A detailed checklist of _who_ does _what_ and _when_ during releases. This would be cloned into a separate runsheet for each release. - -## Monitoring - -### New relic integration - -**Vortex** provides integration with New Relic for release tracking and monitoring. - -**Deployment Markers**: When configured, **Vortex** automatically creates deployment markers in New Relic when releases are deployed to your environments. These markers help correlate performance changes, errors, and other metrics with specific releases. - -**Benefits**: - -- Visualize before/after release performance -- Correlate errors with specific deployments -- Track deployment frequency -- Monitor release impact in real-time - -➡️ See [Workflows > Notifications > New Relic](notifications#new-relic) - -## Best practices - -1. **Always use release branches** - Never release directly from `develop` or feature branches -2. **Backup before release** - Ensure you have recent backups of code and data -3. **Document your process** - Keep `docs/releasing.md` updated with team conventions -4. **Automate everything possible** - Leverage **Vortex**'s automation capabilities -5. **Test in Stage first** - Always validate releases in a production-like environment -6. **Communicate releases** - Notify stakeholders before, during, and after releases -7. **Monitor post-release** - Watch metrics and logs for issues after deployment -8. **Have a rollback plan** - Document and test your rollback procedures -9. **Use consistent versioning** - Stick to your chosen version scheme diff --git a/.vortex/docs/cspell.json b/.vortex/docs/cspell.json index b5d976643..901818fa4 100644 --- a/.vortex/docs/cspell.json +++ b/.vortex/docs/cspell.json @@ -19,6 +19,7 @@ "acquia", "amazee", "amazeeio", + "automations", "apikey", "behat", "bootstrappable", diff --git a/.vortex/docs/docusaurus.config.js b/.vortex/docs/docusaurus.config.js index 33a46bc52..ad1f8d618 100644 --- a/.vortex/docs/docusaurus.config.js +++ b/.vortex/docs/docusaurus.config.js @@ -105,6 +105,10 @@ const config = { label: 'Installation', href: '/docs/installation', }, + { + label: 'Docs', + href: '/docs/development', + }, { label: 'Support', href: '/docs/support', @@ -254,6 +258,110 @@ const config = { from: '/features', to: '/docs/features', }, + { + from: '/docs/workflows/testing', + to: '/docs/development', + }, + { + from: '/docs/workflows/testing/phpunit', + to: '/docs/development/phpunit', + }, + { + from: '/docs/workflows/testing/behat', + to: '/docs/development/behat', + }, + { + from: '/docs/workflows/development', + to: '/docs/development', + }, + { + from: '/docs/workflows/development/phpunit', + to: '/docs/development/phpunit', + }, + { + from: '/docs/workflows/development/behat', + to: '/docs/development/behat', + }, + { + from: '/docs/workflows/development/database', + to: '/docs/development/database', + }, + { + from: '/docs/workflows/development/debugging', + to: '/docs/development/debugging', + }, + { + from: '/docs/workflows/development/composer', + to: '/docs/development/composer', + }, + { + from: '/docs/workflows/development/faqs', + to: '/docs/development/faqs', + }, + { + from: '/docs/workflows/deployment', + to: '/docs/deployment', + }, + { + from: '/docs/workflows/notifications', + to: '/docs/deployment/notifications', + }, + { + from: '/docs/workflows/notifications/email', + to: '/docs/deployment/notifications', + }, + { + from: '/docs/workflows/notifications/github', + to: '/docs/deployment/notifications', + }, + { + from: '/docs/workflows/notifications/jira', + to: '/docs/deployment/notifications', + }, + { + from: '/docs/workflows/notifications/newrelic', + to: '/docs/deployment/notifications', + }, + { + from: '/docs/workflows/notifications/slack', + to: '/docs/deployment/notifications', + }, + { + from: '/docs/workflows/notifications/webhook', + to: '/docs/deployment/notifications', + }, + { + from: '/docs/workflows/releasing', + to: '/docs/releasing', + }, + { + from: '/docs/workflows/releasing/gitflow', + to: '/docs/releasing/gitflow', + }, + { + from: '/docs/workflows/releasing/versioning', + to: '/docs/releasing/versioning', + }, + { + from: '/docs/workflows', + to: '/docs/architecture', + }, + { + from: '/docs/workflows/variables', + to: '/docs/development/variables', + }, + { + from: '/docs/variables', + to: '/docs/development/variables', + }, + { + from: '/docs/workflows/updating-vortex', + to: '/docs/updating-vortex', + }, + { + from: '/docs/drupal/composer', + to: '/docs/drupal/composer-json', + }, ], }, ], diff --git a/.vortex/docs/sidebars.js b/.vortex/docs/sidebars.js index 08448fcbc..f98a624f4 100644 --- a/.vortex/docs/sidebars.js +++ b/.vortex/docs/sidebars.js @@ -6,6 +6,7 @@ const sidebars = { 'README', 'features', 'installation', + 'architecture', 'faqs', 'support', { @@ -18,29 +19,44 @@ const sidebars = { type: 'html', value: '
', }, - 'architecture', { + Development: [{ + type: 'autogenerated', + dirName: 'development', + }], Drupal: [{ type: 'autogenerated', dirName: 'drupal', }], + "Continuous Integration": [{ + type: 'autogenerated', + dirName: 'continuous-integration', + }], Hosting: [{ type: 'autogenerated', dirName: 'hosting', }], - "Continuous Integration": [{ + Deployment: [{ type: 'autogenerated', - dirName: 'continuous-integration', + dirName: 'deployment', }], - Tools: [{ + Releasing: [{ type: 'autogenerated', - dirName: 'tools', + dirName: 'releasing', }], - Workflows: [{ + }, + { + Tools: [{ type: 'autogenerated', - dirName: 'workflows', + dirName: 'tools', }], - }], + }, + { + type: 'html', + value: '
', + }, + 'updating-vortex', + ], }; export default sidebars; diff --git a/.vortex/installer/CLAUDE.md b/.vortex/installer/CLAUDE.md new file mode 100644 index 000000000..ccec9ad9a --- /dev/null +++ b/.vortex/installer/CLAUDE.md @@ -0,0 +1,121 @@ +# Installer System Guide + +## Overview + +Symfony Console application that customizes the Vortex template based on user +selections. + +**Technology**: PHP, Symfony Console, PHPUnit + +## Commands + +```bash +cd .vortex/installer + +composer install # Install dependencies +composer lint # Run phpcs, phpstan, rector --dry-run +composer lint-fix # Run rector, phpcbf +composer test # Run tests (no coverage) +composer test-coverage # Run tests with coverage + +# Specific test filters +./vendor/bin/phpunit --filter "Handlers\\\\" # Handler tests only +./vendor/bin/phpunit --filter "HandlerNameTest" # Specific handler +``` + +## Fixture System + +### Architecture + +**Baseline + diff** system: + +``` +tests/Fixtures/install/ +├── _baseline/ # Complete template files +├── services_no_clamav/ # Diff: removes ClamAV +├── services_no_solr/ # Diff: removes Solr +├── hosting_acquia/ # Diff: Acquia modifications +└── [other scenarios]/ +``` + +### Updating Fixtures + +**CRITICAL**: Never modify fixture files directly. + +```bash +# From .vortex/ directory (recommended) +ahoy update-snapshots + +# Manual (for debugging specific scenarios) +cd .vortex/installer +UPDATE_SNAPSHOTS=1 ./vendor/bin/phpunit --filter "testHandlerProcess.*baseline" +``` + +## Conditional Token System + +### Patterns + +**Markdown**: + +```markdown +[//]: # (#;< TOKEN_NAME) +Content removed if feature not selected +[//]: # (#;> TOKEN_NAME) +``` + +**Shell/YAML**: + +```bash +#;< TOKEN_NAME +Content removed if feature not selected +#;> TOKEN_NAME +``` + +### Available Tokens + +| Category | Tokens | +|----------|------------------------------------------------------------------------------------| +| Theme | `DRUPAL_THEME` | +| Services | `SERVICE_CLAMAV`, `SERVICE_SOLR`, `SERVICE_REDIS` | +| CI | `CI_PROVIDER_GHA`, `CI_PROVIDER_CIRCLECI` | +| Hosting | `HOSTING_LAGOON`, `HOSTING_ACQUIA` | +| Deploy | `DEPLOY_TYPES_CONTAINER_REGISTRY`, `DEPLOY_TYPES_WEBHOOK`, `DEPLOY_TYPES_ARTIFACT` | + +### Handler Locations + +`.vortex/installer/src/Prompts/Handlers/`: + +- `CiProvider.php`, `HostingProvider.php`, `Services.php`, `Theme.php` + +## Handler Development + +### Key Pattern + +Handlers **queue** operations, PromptManager **executes**: + +```php +// In handlers - queue only +File::replaceContentAsync('old', 'new'); +File::replaceTokenAsync('TOKEN'); + +// In PromptManager - execute all +File::runTaskDirectory($this->config->get(Config::TMP)); +``` + +### Common Pitfalls + +1. Don't call `File::runTaskDirectory()` in handlers +2. Use `AlexSkrypnyk\File\Internal\ExtendedSplFileInfo` +3. Preserve complex logic in callbacks + +## Test Organization + +Each handler has dedicated test class extending +`AbstractHandlerProcessTestCase`: + +```bash +./vendor/bin/phpunit --filter "HandlerNameInstallTest" +./vendor/bin/phpunit --filter "HandlerNameInstallTest.*scenario" +``` + +Structure: Test methods → Data providers → Helper methods diff --git a/.vortex/installer/src/Prompts/Handlers/Tools.php b/.vortex/installer/src/Prompts/Handlers/Tools.php index d0cf846e8..559e0b0a0 100644 --- a/.vortex/installer/src/Prompts/Handlers/Tools.php +++ b/.vortex/installer/src/Prompts/Handlers/Tools.php @@ -151,6 +151,18 @@ function (string $content, ContentFile $file) use ($tool): string { } } } + + if (isset($tool['lines'])) { + $relative_file_path = str_replace($this->tmpDir . '/', '', $file->getPathname()); + foreach ($tool['lines'] as $relative_lines_file_name => $lines) { + if ($relative_file_path === $relative_lines_file_name) { + foreach ($lines as $line) { + $content = File::removeLine($content, $line); + } + } + } + } + return $content; } ); @@ -273,8 +285,20 @@ public static function getToolDefinitions(string $filter = 'all'): array { glob($this->tmpDir . '/' . $this->webroot . '/themes/custom/*/tests', GLOB_ONLYDIR), ], 'strings' => ['/^.*phpunit.*\n?/m'], + 'lines' => [ + 'CLAUDE.md' => [ + '# PHPUnit testing', + 'ahoy test # Run PHPUnit tests', + 'ahoy test-unit', + 'ahoy test-kernel', + 'ahoy test-functional', + 'ahoy test -- --filters=TestClassName', + ], + ], 'ahoy' => [ '/^.*phpunit.*\n?/m', + 'ahoy test', + '/^\h*test:\R\h*usage:\h*usage: Run all PHPUnit tests\.$/um', 'ahoy test-unit', '/^\h*test-unit:\R\h*usage:\h*Run PHPUnit unit tests\.$/um', 'ahoy test-kernel', @@ -309,6 +333,12 @@ public static function getToolDefinitions(string $filter = 'all'): array { '/^.*\bbehat\b.*\n?/m', '/^.*\bgherkinlint\b.*\n?/m', ], + 'lines' => [ + 'CLAUDE.md' => [ + '# Behat testing', + 'ahoy test-bdd', + ], + ], 'ahoy' => [ '/^.*behat.*\n?/m', 'ahoy test-bdd', diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/.env b/.vortex/installer/tests/Fixtures/handler_process/_baseline/.env index f0c92a032..87d149693 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/_baseline/.env +++ b/.vortex/installer/tests/Fixtures/handler_process/_baseline/.env @@ -15,7 +15,7 @@ # To customize variables locally, copy `.env.local.example` to `.env.local`, # and add your custom values there. # -# @see https://www.vortextemplate.com/docs/workflows/variables +# @see https://www.vortextemplate.com/docs/development/variables ################################################################################ # GENERAL # @@ -163,7 +163,7 @@ VORTEX_DB_DOWNLOAD_ENVIRONMENT=prod # Versioning scheme used for releases. # # Can be one of: calver, semver, other -# @see https://www.vortextemplate.com/docs/workflows/releasing +# @see https://www.vortextemplate.com/docs/releasing VORTEX_RELEASE_VERSION_SCHEME=calver ################################################################################ @@ -171,7 +171,7 @@ VORTEX_RELEASE_VERSION_SCHEME=calver ################################################################################ # Deployment occurs when tests pass in the CI environment. -# @see https://www.vortextemplate.com/docs/workflows/deployment +# @see https://www.vortextemplate.com/docs/deployment VORTEX_DEPLOY_TYPES=webhook ################################################################################ @@ -179,7 +179,7 @@ VORTEX_DEPLOY_TYPES=webhook ################################################################################ # Notificaions are sent accross multiple channels before and after deployment. -# @see https://www.vortextemplate.com/docs/workflows/notifications +# @see https://www.vortextemplate.com/docs/deployment/notifications # The channels of the notifications. # diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/.env.local b/.vortex/installer/tests/Fixtures/handler_process/_baseline/.env.local index e8969d0d8..6e86d68b0 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/_baseline/.env.local +++ b/.vortex/installer/tests/Fixtures/handler_process/_baseline/.env.local @@ -6,7 +6,7 @@ # # The .env.local file is excluded via .gitignore and will not be committed. # -# @see https://www.vortextemplate.com/docs/workflows/variables +# @see https://www.vortextemplate.com/docs/development/variables # Local development URL. # Override only if you need to use a different URL than the default. diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/.env.local.example b/.vortex/installer/tests/Fixtures/handler_process/_baseline/.env.local.example index e8969d0d8..6e86d68b0 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/_baseline/.env.local.example +++ b/.vortex/installer/tests/Fixtures/handler_process/_baseline/.env.local.example @@ -6,7 +6,7 @@ # # The .env.local file is excluded via .gitignore and will not be committed. # -# @see https://www.vortextemplate.com/docs/workflows/variables +# @see https://www.vortextemplate.com/docs/development/variables # Local development URL. # Override only if you need to use a different URL than the default. diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/_baseline/CLAUDE.md index d8d7916b4..788272cc6 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/_baseline/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/handler_process/_baseline/CLAUDE.md @@ -1,891 +1,90 @@ -# Vortex Drupal Project - Development Guide +# star wars - Development Guide - -CRITICAL UNDERSTANDING: -- This is a PRODUCTION-READY Drupal project template -- Uses Docker for local development -- Commands are executed via 'ahoy' (task runner) -- Configuration is exported/imported via Drupal's config management -- Testing includes PHPUnit -- Testing includes Behat (BDD) -- Deployment is automated via CI/CD pipelines - -KEY CONVENTIONS: -- All local commands use 'ahoy' prefix -- Test data must use [TEST] prefix -- Never use drush php:eval directly -- Always use scripts via drush php:script -- Configuration changes must be exported -- Database operations vary by project setup - -CLAUDE_CONTEXT_END --> - -## Project Overview - -This is a **production-ready Drupal project** built with **Vortex** - a -comprehensive Drupal project template by DrevOps that provides: - -- 🐳 **Docker-based development environment** -- 🔄 **Automated CI/CD deployment workflows** -- 🧪 **Comprehensive testing framework** -- ⚙️ **Configuration management** (exportable configs) -- 🚀 **Production hosting integration** - -## Quick Start Commands - -```bash -# STEP 1: Build the site locally (first time setup) -ahoy build - -# STEP 2: Start development environment -ahoy up - -# STEP 3: Get site information and URLs -ahoy info - -# STEP 4: Get admin login link -ahoy login -``` - -## Core Development Workflow - -### 1. Environment Management - -```bash -# Start Docker containers (daily workflow) -ahoy up - -# Stop Docker containers (end of day) -ahoy down - -# Restart all containers (troubleshooting) -ahoy restart - -# Show project URLs, container status, database info -ahoy info -``` - -### 2. Site Building & Database - -```bash -# Complete site rebuild (nuclear option) -ahoy build - -# Re-provision site (install/import fresh DB) -ahoy provision - -# Reset to clean state (removes local changes) -ahoy reset -``` +## Daily Development Tasks ```bash -# Download fresh database from remote source -ahoy download-db - -# Export current local database -ahoy export-db +# Environment +ahoy up # Start containers +ahoy down # Stop containers +ahoy info # Show URLs and status +ahoy login # Get admin login URL -# Import database from file -ahoy import-db [path/to/dump.sql] -``` +# Build & Database +ahoy download-db # Download fresh database from remote +ahoy build # Complete site rebuild +ahoy provision # Re-provision (import DB + apply config) +ahoy import-db # Import database from file without applying config +ahoy export-db # Export current local database -### 3. Daily Development Tasks - -```bash -# Run Drush commands (Drupal CLI) -ahoy drush [command] -# Examples: -ahoy drush status -ahoy drush cr # Clear cache -ahoy drush uli # Get login link +# Drush commands +ahoy drush cr # Clear cache +ahoy drush cex # Export configuration to code +ahoy drush cim # Import configuration from code +ahoy drush uli # Get one-time login link +ahoy drush status # Check site status -# Run Composer commands (PHP dependencies) -ahoy composer [command] -# Examples: +# Composer ahoy composer install -ahoy composer require drupal/webform -``` - -## Code Quality & Testing - -### Linting (Code Standards) - -```bash -# Check code style issues (PHP, JS, CSS) -ahoy lint - -# Automatically fix code style issues -ahoy lint-fix -``` - -### Testing Framework - -```bash -# Run PHPUnit tests (unit/integration tests) -ahoy test-unit -``` - -```bash -# Run Behat tests (behavioral/BDD tests) -ahoy test-bdd - -# Run specific Behat feature -ahoy test-bdd tests/behat/features/homepage.feature -``` - -## Configuration Management (Critical for Drupal) - -### Understanding Config Management - -- **Structure changes** (content types, fields, views) = Configuration (exported - to code) -- **Content data** (nodes, users, media) = Database (not exported) - -### Export Configuration (After making admin changes) - -```bash -# Export ALL configuration changes to code -ahoy drush config:export -# Short version: -ahoy drush cex - -# Export with diff preview -ahoy drush config:export --diff -``` - -### Import Configuration (Deploy config changes) - -```bash -# Import configuration from code -ahoy drush config:import -# Short version: -ahoy drush cim - -# Import from specific environment -ahoy drush config:import --source=../config/stage -``` - -### Typical Config Workflow - -1. Make changes in Drupal admin UI -2. Run `ahoy drush cex` to export to code -3. Commit the config files to git -4. Deploy code and run `ahoy drush cim` on target environment - -## Project Structure (Critical Understanding) - -```text -your-project/ -├── .ahoy.yml # Ahoy task definitions -├── .env # Environment variables (local) -├── docker-compose.yml # Local development containers -├── composer.json # PHP dependencies -│ -├── config/ # Drupal configuration (version controlled) -│ ├── default/ # Base configuration (all environments) -│ ├── dev/ # Development-specific overrides -│ ├── stage/ # Staging-specific overrides -│ └── ci/ # CI-specific overrides -│ -├── web/ # Drupal webroot (document root) -│ ├── modules/custom/ # Your custom modules -│ ├── themes/custom/ # Your custom themes -│ ├── sites/default/ # Drupal site settings -│ └── index.php # Drupal entry point -│ -├── tests/ -│ ├── behat/ # Behavioral tests (user scenarios) -│ │ ├── features/ # Test scenarios (.feature files) -│ │ └── behat.yml # Behat configuration -│ └── phpunit/ # Unit/integration tests -│ -└── scripts/ - ├── vortex/ # Core Vortex scripts (don't modify) - └── custom/ # Project-specific scripts -``` - -## Custom Code Development - -### Creating Custom Modules - -```bash -# Generate custom module scaffold -ahoy drush generate:module - -# Location: web/modules/custom/[module_name]/ -# Enable module: -ahoy drush pm:install [module_name] -``` - -### Theme Development - -```bash -# Navigate to custom theme -cd web/themes/custom/[theme_name] - -# Install theme dependencies -yarn install - -# Build theme assets (CSS/JS) -yarn run build - -# Watch for changes during development -yarn run watch - -# Build for production -yarn run build:prod -``` - -## PHP Script Execution (IMPORTANT) - -### ✅ Correct Way: Use PHP Scripts - -```bash -# Run PHP script with full Drupal bootstrap -ahoy drush php:script script_name - -# List available scripts -ahoy drush php:script - -# Run with custom script path -ahoy drush php:script script_name --script-path=scripts/custom - -# Pass arguments to script (note the -- separator) -ahoy drush php:script -- script_name --arg1=value1 --arg2=value2 -``` - -### ❌ NEVER Do This - -```bash -# DANGEROUS - Never evaluate PHP directly! -ahoy drush php:eval "dangerous_code_here" -``` - -### Creating PHP Scripts - -Create scripts in `scripts/custom/` directory: - -```php -getStorage('node') - ->loadByProperties(['type' => 'page']); - -foreach ($nodes as $node) { - print $node->getTitle(); -} -``` - -## Service Integrations - -### Solr Search Service - -```bash -# Check Solr search status -ahoy drush search-api:status - -# Index all content to Solr -ahoy drush search-api:index - -# Clear and rebuild Solr index -ahoy drush search-api:clear -ahoy drush search-api:index - -# Check Solr server connection -ahoy drush search-api:server-status -``` - -### Redis Caching Service - -```bash -# Clear all caches (includes Redis) -ahoy drush cache:rebuild - -# Check Redis connection status -ahoy drush php:script -- redis_status - -# Flush Redis cache specifically -ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" -``` - -### ClamAV Virus Scanning Service - -```bash -# Test virus scanning functionality -ahoy drush clamav:scan /path/to/test/file - -# Check ClamAV daemon status -ahoy drush clamav:status - -# Update virus definitions -ahoy drush clamav:update -``` - -## Dependency Management - -### Adding Drupal Modules - -```bash -# Add contributed modules -ahoy composer require drupal/webform - -# Enable added modules -ahoy drush pm:install webform -``` - -### Patching Contributed Modules - -When contributed modules need fixes or customizations, use the proper patching workflow with `cweagans/composer-patches`. - -Vortex uses **composer-patches v2.x** which provides git-based patching with improved reliability and reproducibility. - -#### Key Features of v2 - -- **Git-based patching**: Uses `git apply` exclusively for cross-platform consistency -- **patches.lock.json**: Automatically generated file with patch metadata and SHA-256 checksums -- **New commands**: - - `composer patches-relock` - Regenerate patches.lock.json after adding/removing patches - - `composer patches-repatch` - Remove and reinstall patched dependencies -- **Automatic failure on patch errors**: Patches must apply successfully or installation fails - -#### Understanding patches.lock.json - -This file is automatically generated and **must be committed to version control** (like composer.lock). - -**What it contains:** - -- Patch metadata (URLs, descriptions, target packages) -- SHA-256 checksums for patch verification - -**Why it matters:** - -- Ensures reproducible builds across teams and CI/CD -- Verifies patch integrity with checksums -- Prevents "works on my machine" issues -- Makes patch state explicit and trackable - -**Always commit this file** after adding or removing patches. - -#### Prerequisites for Patching - -- Project uses `cweagans/composer-patches` package (v2.x) -- Git is available for version control (required by v2) -- Access to Drupal.org git repositories - -#### Patch Storage and Configuration - -Patches are defined in `composer.json` under the `extra.patches` section: - -```json -{ - "extra": { - "patches": { - "drupal/module_name": { - "Description of fix": "patches/module-name-description.patch", - "Another fix": "https://www.drupal.org/files/issues/external-patch.patch" - } - } - } -} -``` - -- **Local patches**: Store in `patches/` directory in project root -- **External patches**: Reference URLs directly in composer.json -- **Naming convention**: Use descriptive names like `module-name-description.patch` - -#### Creating Module Patches - -Step 1: Identify Module Version - -Always work with the exact version and state used in your project: - -```bash -# Check installed version -ahoy composer show drupal/module_name - -# Verify version in composer.lock -grep -A 20 "drupal/module_name" composer.lock -``` - -Step 2: Clone Module from Git - -**CRITICAL**: Always use the official Drupal git repository, not tarball downloads: - -```bash -# Create working directory -cd /tmp && mkdir module_patch_work && cd module_patch_work - -# Clone the module -git clone https://git.drupalcode.org/project/module_name.git - -# Navigate to module directory -cd module_name - -# Checkout the exact version/tag used in project -git checkout __VERSION__ # Replace with actual version - -# Create working branch -git checkout -b fix-description -``` +ahoy composer require drupal/[module_name] -Step 3: Apply Existing Patches +# Code quality +ahoy lint # Check code style +ahoy lint-fix # Auto-fix code style -If your project already has patches for this module, apply them first to match the current state: +# PHPUnit testing +ahoy test # Run PHPUnit tests +ahoy test-unit # Run PHPUnit Unit tests +ahoy test-kernel # Run PHPUnit Kernel tests +ahoy test-functional # Run PHPUnit Functional tests +ahoy test -- --filters=TestClassName # Run specific PHPUnit test class -```bash -# Apply each existing patch in order -curl -s https://example.com/patch1.patch | patch -p1 -curl -s https://example.com/patch2.patch | patch -p1 - -# Commit the patches to establish baseline -git add . -git commit -m "Apply existing patches to match project state" -``` - -Step 4: Make Required Changes - -Edit the necessary files to implement your fix: - -```bash -# Make your changes using your preferred editor -vim path/to/file.php - -# Or use automated tools if applicable -sed -i 's/old_code/new_code/' path/to/file.php -``` - -Step 5: Generate Clean Patch - -Create a proper git-based patch: - -```bash -# Stage your changes -git add . - -# Generate patch from staged changes -git diff --cached > /path/to/project/patches/module-name-fix-description.patch -``` - -Step 6: Test Patch Application - -**ALWAYS test that your patch applies cleanly**: - -```bash -# Reset to test patch application -git reset --hard HEAD - -# Test patch applies without conflicts -git apply /path/to/project/patches/module-name-fix-description.patch - -# Verify changes were applied correctly -git status -git diff -``` - -Step 7: Integrate into Project - -Add the patch to your project's composer configuration and apply it using v2 commands: - -```bash -# Add patch definition to composer.json extra.patches section - -# Regenerate patches.lock.json -ahoy composer patches-relock - -# Remove and reinstall patched package -ahoy composer patches-repatch - -# Update composer.lock -ahoy composer update --lock - -# Verify no patch application errors -# Check that functionality works as expected - -# Commit all changes -git add composer.json composer.lock patches.lock.json patches/ -git commit -m "Added patch for drupal/module_name." -``` - -Step 8: Clean Up - -Remove temporary working directory: - -```bash -rm -rf /tmp/module_patch_work +# Behat testing +ahoy test-bdd # Run Behat tests +ahoy test-bdd -- --tags=@tagname # Run Behat tests with specific tag ``` -#### Patching Best Practices - -**✅ Do This:** - -- Use descriptive patch names that explain what they fix -- Keep patches focused - one fix per patch when possible -- Follow Drupal coding standards in your changes -- Test locally before committing patches -- Document the issue being fixed in composer.json description -- Include issue URLs when available from drupal.org - -**❌ Avoid These Mistakes:** - -- Working with tarball downloads instead of git repositories -- Creating patches from modified project files -- Skipping patch application testing -- Creating patches without applying existing patches first -- Assuming patches work across different module versions +## Critical Rules -#### Troubleshooting Patch Issues - -**Patch Won't Apply:** - -1. Check module version matches between patch creation and application -2. Verify existing patches are applied in correct order -3. Check for whitespace issues in patch file -4. Ensure patch paths are correct (usually relative to module root) - -**Patch Conflicts:** - -1. Identify conflicting patches by applying them individually -2. Update patch order in composer.json if needed -3. Recreate patches against the current patched state -4. Merge patches if they modify the same areas - -**Performance Issues:** - -1. Minimize external patch URLs to reduce download time -2. Store frequently used patches locally in patches directory -3. Keep patch files small and focused -4. Remove obsolete patches when updating modules - -### Adding JavaScript/CSS Libraries - -For npm packages that need to be Drupal libraries, define them as inline -Composer packages: - -1. **Add to composer.json repositories section:** - -```json -{ - "repositories": [ - { - "type": "package", - "package": { - "name": "vendor/library-name", - "type": "drupal-library", - "version": "__VERSION__", - "source": { - "type": "git", - "url": "https://github.com/vendor/library-name", - "reference": "__VERSION__" - } - } - } - ] -} -``` - -1. **Install via Composer:** - -```bash -ahoy composer require vendor/library-name -``` - -### Theme Dependencies - -```bash -# Navigate to theme directory -cd web/themes/custom/[theme_name] - -# Add frontend dependencies -yarn add [package-name] - -# Example: Add Bootstrap -yarn add bootstrap - -# Install dev dependencies -yarn add --dev sass webpack -``` - -## Testing Best Practices - -### Writing Behat Tests (BDD) - -#### User Story Format (Required) - -All Behat features MUST follow this format: - -```gherkin -Feature: [Feature name] - - As a [user type] - I want to [action/goal] - So that [benefit/outcome] -``` - -#### Standard User Types - -```gherkin -As a site visitor # Anonymous users -As a site administrator # Admin users -As a content editor # Content management users -As a authenticated user # Logged-in users -``` - -#### Test Data Conventions - -- **Always prefix test content**: `[TEST] Page Title` -- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` -- **Avoid real names**: Don't use "Workshop" or "Training" -- **Be descriptive**: `[TEST] Event with All Fields` - -#### Example Feature File - -```gherkin -Feature: Homepage - - As a site visitor - I want to access the homepage - So that I can view the main landing page and navigate the site - - Scenario: View homepage content - Given I am on the homepage - Then I should see "[TEST] Welcome Message" - And I should see "About Us" in the "navigation" region -``` +- **Never modify** `scripts/vortex/` - use `scripts/custom/` for your scripts +- **Never use** `ahoy drush php:eval` - use `ahoy drush php:script` instead +- **Always export config** after admin UI changes: `ahoy drush cex` -#### Discovering Available Step Definitions - -```bash -# Generate step definitions reference (run once) -ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt -``` - -Use the cached file for reference, don't regenerate unless asked. - -### Content Type Testing Process - -When creating comprehensive tests for content types: - -1. **Analyze Configuration First** - - - Check `config/default/field.field.node.[type].*.yml` - - Review `core.entity_view_display.node.[type].default.yml` - - Identify visible vs hidden fields - -1. **Create Supporting Entities** - -```gherkin -Background: - Given "tags" terms: - | name | - | [TEST] Topic 1 | - | [TEST] Topic 2 | - - And the following media "image" exist: - | name | - | [TEST] Featured Image 1 | -``` - -1. **Test All Visible Fields** - -```gherkin -Scenario: View complete content with all fields - Given "page" content: - | title | body | field_tags | - | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | - When I visit "[TEST] Complete Page Test" - Then I should see "[TEST] Complete Page Test" - And I should see "[TEST] This is the body text." - And I should see "[TEST] Topic 1" -``` - -## Debugging & Troubleshooting - -### Development Tools - -```bash -# Enable development modules -ahoy drush pm:install devel - -# Get admin login URL -ahoy login - -# View recent log entries -ahoy drush watchdog:show - -# Clear all caches -ahoy drush cache:rebuild - -# Check system status -ahoy drush status -``` - -### Performance Optimization - -```bash -# Enable CSS/JS aggregation -ahoy drush config:set system.performance css.preprocess 1 -ahoy drush config:set system.performance js.preprocess 1 - -# Clear render cache -ahoy drush cache:rebuild-external - -# Check database updates needed -ahoy drush updatedb:status -``` - -### Container Debugging - -```bash -# Check container status -docker-compose ps - -# View container logs -docker-compose logs [service_name] -# Examples: -docker-compose logs web -docker-compose logs db - -# Access container shell -docker-compose exec web bash -docker-compose exec db mysql -u drupal -p drupal -``` - -### Common Issues & Solutions - -**Site not loading:** - -```bash -ahoy down && ahoy up -ahoy info # Verify URLs and ports -``` - -**Database connection errors:** - -```bash -docker-compose ps # Check if database container is running -ahoy reset # Nuclear option: rebuild everything -``` - -**Permission issues:** - -```bash -# Fix file permissions (Linux/Mac) -sudo chown -R $USER:$USER . -``` - -**Memory issues during composer install:** - -```bash -# Increase PHP memory temporarily -ahoy composer install --no-dev --optimize-autoloader -``` - -## CI/CD & Deployment - -### Automated Deployment - -This project includes automated deployment via: - -- **GitHub Actions** - See `.github/workflows/` - -### Hosting Platforms - -- **Container Registry** - Docker-based deployments - -### Manual Deployment Commands - -```bash -# Export configuration before deployment -ahoy drush config:export - -# Run database updates -ahoy drush updatedb - -# Import configuration -ahoy drush config:import - -# Clear caches -ahoy drush cache:rebuild - -# Full deployment sequence -ahoy drush updatedb && ahoy drush config:import && ahoy drush cache:rebuild -``` - -## Getting Help & Resources - -### Command Help - -```bash -# List all available ahoy commands -ahoy --help -``` - -### Log Files & Debugging - -```bash -# View ahoy logs -ahoy logs - -# Check container logs -docker-compose logs --tail=50 web - -# View Drupal watchdog logs -ahoy drush watchdog:show --count=20 -``` +## Key Directories -### Documentation Resources +- `web/modules/custom/` - Custom modules +- `web/themes/custom/` - Custom themes +- `config/default/` - Drupal configuration +- `scripts/custom/` - Project scripts +- `patches/` - Module patches -- **Vortex Documentation**: https://www.vortextemplate.com -- **Drupal Documentation**: https://www.drupal.org/docs -- **Drush Documentation**: https://www.drush.org -- **Ahoy Documentation**: https://github.com/ahoy-cli/ahoy -- **Docker Compose**: https://docs.docker.com/compose/ +## Documentation -### Project-Specific Help +This project uses two documentation sources: -- Check `/docs` directory for additional project documentation -- Review `README.md` in project root -- Check `.ahoy.yml` for custom commands -- Review `composer.json` for installed packages and scripts +### Project-specific documentation (`docs/`) ---- +The `docs/` directory contains **what** applies to this project: - +Use the sitemap to discover available pages: +https://www.vortextemplate.com/sitemap.xml -*This guide covers the complete development workflow for your Vortex-powered -Drupal project. Keep this guide updated as your project grows and add -project-specific conventions below.* +**Caching:** Save fetched docs to `.claude/artifacts/docs-[topic].md` with header +``. +Re-fetch if user reports docs are outdated. diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/README.md b/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/README.md index 44c9ca7e5..fdb1862c0 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/README.md +++ b/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/README.md @@ -1,7 +1,11 @@ -# Project-specific documentation +# Project documentation -- [Testing](testing.md) -- [CI](ci.md) -- [Deployment](deployment.md) -- [Releasing](releasing.md) -- [FAQs](faqs.md) +This directory contains project-specific documentation that describes **what** +applies to this project. For **how** to perform operations, see +[Vortex Documentation](https://www.vortextemplate.com/docs/). + +- [Testing](testing.md) - Testing conventions and agreements +- [CI](ci.md) - Continuous integration configuration +- [Deployment](deployment.md) - Deployment configuration +- [Releasing](releasing.md) - Release process and versioning +- [FAQs](faqs.md) - Project-specific FAQs diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/ci.md b/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/ci.md index cbbca01c9..265078de8 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/ci.md +++ b/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/ci.md @@ -1,30 +1,15 @@ # Continuous Integration -In software engineering, continuous integration (CI) is the practice of merging -all developer working copies to a shared mainline several times a day. -Before feature changes can be merged into a shared mainline, a complete build -must run and pass all tests on CI server. +For information on how CI works, see +[Vortex CI Documentation](https://www.vortextemplate.com/docs/continuous-integration). -## GitHub Actions +## CI provider -This project uses [GitHub Actions](https://github.com/features/actions) as a -CI server: it imports production backups into fully built codebase and runs -code linting and tests. When tests pass, a deployment process is triggered for -nominated branches (usually, `main` and `develop`). +This project uses [GitHub Actions](https://github.com/features/actions). -Refer to https://www.vortextemplate.com/docs/continuous-integration for more -information. +See [GitHub Actions documentation](https://www.vortextemplate.com/docs/continuous-integration/github-actions) +for setup and configuration details. -### Skipping CI build +## Project-specific configuration -Add `[skip ci]` to the commit subject to skip CI build. Useful for documentation -changes. - -### SSH - -GitHub Actions does not supports shell access to the build, but there is an -action provided withing the `build` job that allows you to run a build with SSH -support. - -Use "Run workflow" button in GitHub Actions UI to start build with SSH support -that will be available for 120 minutes after the build is finished. + diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/deployment.md b/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/deployment.md index 40ed9723b..a0bab11d3 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/deployment.md +++ b/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/deployment.md @@ -1,18 +1,8 @@ -# Deployment process +# Deployment -Refer to https://www.vortextemplate.com/docs/workflows/deployment for more information. +For information on how deployment works, see +[Vortex Deployment Documentation](https://www.vortextemplate.com/docs/deployment). -## Workflow +## Project-specific configuration -1. Code is authored on a local machine by a developer. -2. Once the code is ready, it is pushed to GitHub. A pull request needs to be - opened for this code change. -3. The CI "listens" for code changes and will start an automated build. -4. At the end of the build, when all tests have passed, the CI will trigger a - deployment to Lagoon. -5. Once deployed, a PR environment will appear with a PR name. The database will - be taken from production environment. - All pending update hooks and other deployment operations will run during - deployment. - -Once PR is closed, the environment will be automatically removed. + diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/faqs.md b/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/faqs.md index 838a973bf..03f0de6c2 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/faqs.md +++ b/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/faqs.md @@ -1,168 +1,8 @@ # FAQs -## How to know which commands are available? +For common questions and answers, see +[Vortex FAQs](https://www.vortextemplate.com/docs/development/faqs). -```bash -ahoy help -``` +## Project-specific FAQs -## How to pass CLI arguments to commands? - -```bash -ahoy mycommand -- myarg1 myarg2 --myoption1 --myoption2=myvalue -``` - -## How to clear Drupal cache? - -```bash -ahoy drush cr -``` - -## How to login to a Drupal site? - -```bash -ahoy login -``` - -## How to connect to the database? - -If you have [Sequel Ace](https://sequel-ace.com/): - -```bash -ahoy db -``` - -Otherwise: - -1. Run `ahoy info` and grab the DB host port number. -2. Use these connection details: - -- Host: `127.0.0.1` -- Username: `drupal` -- Password: `drupal` -- Database: `drupal` -- Port: the port from step 1 - -## How to use Xdebug? - -1. Run `ahoy debug`. -2. Enable listening for incoming debug connections in your IDE. -3. If required, provide server URL to your IDE as it appears in the browser. -4. Enable Xdebug flag in the request coming from your web browser (use one of - the extensions or add `?XDEBUG_SESSION_START=1` to your URL). -5. Set a breakpoint in your IDE and perform a request in the web browser. - -Use the same commands to debug CLI scripts. - -To disable, run `ahoy up`. - -See https://www.vortextemplate.com/docs/tools/xdebug for more details. - -## How to use Xdebug on Behat scripts? - -1. Enable debugging: `ahoy debug` -2. Enter CLI container: `ahoy cli` -3. Run Behat tests: - -```bash -vendor/bin/behat --xdebug path/to/test.feature -``` - -## What should I do to switch to a "clean" branch environment? - -Provided that your stack is already running: - -1. Switch to your branch -2. `composer install` -3. `ahoy provision` - -You do not need to rebuild the full stack using `ahoy build` every -time you switch branches. `ahoy provision` will update the environment -to match the current branch. - -However, sometimes you would want to have an absolutely clean environment - in -that case, use `ahoy build`. - -## How to just import a database? - -Provided that your stack is already running: - -```bash -ahoy import-db - -ahoy import-db .data/db_custom.sql -``` - -## How to add Drupal modules - -```bash -composer require drupal/module_name -``` - -## How to add patches for Drupal modules - -1. Add `title` to patch on https://drupal.org to the `patches` array in `extra` - section in `composer.json`. - - ```json - "extra": { - "patches": { - "drupal/somepackage": { - "Remote patch description": "https://www.drupal.org/files/issues/issue.patch" - "Local patch description": "patches/package-description.patch" - } - } - } - ``` - -2. Run - - ```bash - composer require drupal/somepackage - ``` - -See https://www.vortextemplate.com/docs/workflows/development#working-with-composer-packages - -## What should I do when Composer blocks package installation due to security vulnerabilities? - -Starting with Composer __VERSION__, Composer can automatically block the installation -or update of packages with known security vulnerabilities. If you encounter this -issue, you have several options: - -1. **Update the affected packages**: Try updating to newer versions that don't - have known vulnerabilities: `composer update vendor/package-name` -2. **Review the vulnerability**: Run `composer audit` to see details about the - security issues and determine if they affect your project. -3. **Adjust security settings**: If you need to proceed with installation despite - warnings (for example, if no secure version is available or the vulnerability - doesn't affect your use case), you can configure the `audit.block-insecure` - setting in your `composer.json`. - -See the [Composer configuration documentation](https://www.vortextemplate.com/docs/drupal/composer#config) -for detailed information about the `audit` configuration option and guidance on -choosing the right security settings for your project. - -## How to set a custom maintenance theme? - -To set a custom theme for Drupal's maintenance mode (when the site is offline -for updates), set the `DRUPAL_MAINTENANCE_THEME` environment variable: - -```bash -# In .env file -DRUPAL_MAINTENANCE_THEME=my_custom_theme -``` - -This theme will be used when Drupal is in maintenance mode. If -`DRUPAL_MAINTENANCE_THEME` is not set, the system will fall back to using the -value of `DRUPAL_THEME`. - -The maintenance theme should be a valid Drupal theme that is already installed -and enabled on your site. - -## Behat tests with `@javascript` tag sometimes get stuck - -Behat tests with `@javascript` tag sometimes get stuck for about 10min then -fail. -The Chrome container randomly get stuck for an unknown reason. - -Restart the Chrome container: `docker compose restart chrome` + diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/releasing.md b/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/releasing.md index aae4b5b04..3db4308d4 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/releasing.md +++ b/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/releasing.md @@ -1,37 +1,30 @@ # Releasing -[git-flow](https://danielkummer.github.io/git-flow-cheatsheet/) is used to -manage releases. - -Note: after completing the release, commits must be manually pushed -from `main` to `production` branch. - -Refer to https://www.vortextemplate.com/docs/workflows/releasing for more information. +For information on how releasing works, see +[Vortex Releasing Documentation](https://www.vortextemplate.com/docs/releasing). ## Release outcome +After a successful release: + 1. Release branch exists as `release/X.Y.Z` in GitHub repository. 2. Release tag exists as `X.Y.Z` in GitHub repository. 3. The `HEAD` of the `main` branch has `X.Y.Z` tag. 4. The hash of the `HEAD` of the `main` branch exists in the `develop` branch. - This is to ensure that everything pushed to `main` exists in `develop` (in - case if `main` had any hot-fixes that not yet have been merged - to `develop`). 5. There are no PRs in GitHub related to the release. 6. The hash of the `HEAD` of the `production` branch matches the hash of the `HEAD` of `main` branch. -## Version Number - Calendar Versioning (CalVer) +## Version scheme -Release versions are numbered according to [CalVer Versioning](https://calver.org/). +This project uses [Calendar Versioning](https://calver.org/) (`YY.M.Z`): -Given a version number `YY.M.Z`: +- `YY` = Short year +- `M` = Short month +- `Z` = Hotfix/patch version -- `YY` = Short year. No leading zeroes. -- `M` = Short month. No leading zeroes. -- `Z` = Hotfix/patch version. No leading zeroes. +Examples: `__VERSION__`, `__VERSION__`, `__VERSION__`, `__VERSION__` -Examples: +## Project-specific configuration -- Correct: `__VERSION__`, `__VERSION__` , `__VERSION__`, `__VERSION__`, `__VERSION__` -- Incorrect: `__VERSION__`, `__VERSION__` , `25` , `__VERSION__` , `__VERSION__`, `__VERSION__`, `__VERSION__` + diff --git a/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/testing.md b/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/testing.md index 0ffbd16ad..38586256c 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/testing.md +++ b/.vortex/installer/tests/Fixtures/handler_process/_baseline/docs/testing.md @@ -1,3 +1,227 @@ # Testing -Refer to https://www.vortextemplate.com/docs/workflows/testing for more information. +This document describes **what** testing conventions and agreements apply to +this project. + +## PHPUnit conventions + +Unit, Kernel, Functional tests. + +See [documentation](https://www.vortextemplate.com/docs/development/phpunit) +on how to run tests, configure environment variables and code coverage, and use +test reports in continuous integration pipeline. + +### Test class structure + +All PHPUnit tests must follow this structure: + +```php +assertEquals('expected', $result); + } + +} +``` + +### Base test classes + +- **Unit** - `Drupal\Tests\UnitTestCase` - Testing isolated PHP classes +- **Kernel** - `Drupal\KernelTests\KernelTestBase` - Testing with database/services +- **Functional** - `Drupal\Tests\BrowserTestBase` - Testing with full browser + +### Test data conventions + +- **Always prefix test content**: `[TEST] Node Title` +- **Use data providers**: For testing multiple input/output combinations + - Must be a public static method + - Must follow naming convention `dataProvider` + - Must be placed after the test method it provides data for. +- **Use unique identifiers**: Include test class or method name in test data + +### Data providers + +Always use data providers for testing multiple input/output combinations: + +```php +/** + * Test my function with various inputs. + * + * @dataProvider dataProviderMyFunction + */ +public function testMyFunction(string $input, string $expected): void { + $this->assertEquals($expected, my_function($input)); +} + +/** + * Data provider for testMyFunction. + */ +public static function dataProviderMyFunction(): array { + return [ + 'empty string' => ['', ''], + 'simple string' => ['hello', 'HELLO'], + 'with numbers' => ['test123', 'TEST123'], + ]; +} +``` + +### Testing services (Kernel tests) + +For Kernel tests that need Drupal services: + +```php +installEntitySchema('node'); + $this->installEntitySchema('user'); + $this->myService = $this->container->get('my_module.my_service'); + } + + /** + * Test service method. + */ + public function testServiceMethod(): void { + $result = $this->myService->doSomething(); + $this->assertNotNull($result); + } + +} +``` + +## Behat conventions + +BDD end-to-end tests. + +See [documentation](https://www.vortextemplate.com/docs/development/behat) +on how to run Behat tests, configure environment variables, and use test reports +in continuous integration pipeline. + +### User story format + +All Behat features must follow this format: + +```gherkin +Feature: [Feature name] + + As a [user type] + I want to [action/goal] + So that [benefit/outcome] +``` + +### Standard user types + +Use these consistent user type descriptions: + +```gherkin +As a site visitor # Anonymous users +As a site administrator # Admin users +As a content editor # Content management users +As a authenticated user # Logged-in users +``` + +### Test data conventions + +- **Always prefix test content**: `[TEST] Page Title` +- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +- **Avoid real names**: Don't use "Workshop" or "Training" +- **Be descriptive**: `[TEST] Event with All Fields` + +### Example feature file + +```gherkin +Feature: Homepage + + As a site visitor + I want to access the homepage + So that I can view the main landing page and navigate the site + + Scenario: View homepage content + Given I am on the homepage + Then I should see "[TEST] Welcome Message" + And I should see "About Us" in the "navigation" region +``` + +### Content type testing process + +When creating comprehensive tests for content types: + +1. Analyze configuration first + + - Check `config/default/field.field.node.[type].*.yml` + - Review `core.entity_view_display.node.[type].default.yml` + - Identify visible vs hidden fields + +2. Create supporting entities + + ```gherkin + Background: + Given "tags" terms: + | name | + | [TEST] Topic 1 | + | [TEST] Topic 2 | + + And the following media "image" exist: + | name | + | [TEST] Featured Image 1 | + ``` + +3. Test all visible fields + + ```gherkin + Scenario: View complete content with all fields + Given "page" content: + | title | body | field_tags | + | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | + When I visit "[TEST] Complete Page Test" + Then I should see "[TEST] Complete Page Test" + And I should see "[TEST] This is the body text." + And I should see "[TEST] Topic 1" + ``` diff --git a/.vortex/installer/tests/Fixtures/handler_process/ciprovider_circleci/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/ciprovider_circleci/CLAUDE.md deleted file mode 100644 index 109f9b3b5..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/ciprovider_circleci/CLAUDE.md +++ /dev/null @@ -1,9 +0,0 @@ -@@ -796,7 +796,7 @@ - - This project includes automated deployment via: - --- **GitHub Actions** - See `.github/workflows/` -+- **CircleCI** - See `.circleci/config.yml` - - ### Hosting Platforms - diff --git a/.vortex/installer/tests/Fixtures/handler_process/ciprovider_circleci/docs/ci.md b/.vortex/installer/tests/Fixtures/handler_process/ciprovider_circleci/docs/ci.md index 419d99d2b..542f58060 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/ciprovider_circleci/docs/ci.md +++ b/.vortex/installer/tests/Fixtures/handler_process/ciprovider_circleci/docs/ci.md @@ -1,31 +1,12 @@ -@@ -5,12 +5,12 @@ - Before feature changes can be merged into a shared mainline, a complete build - must run and pass all tests on CI server. +@@ -5,9 +5,9 @@ --## GitHub Actions -+## Circle CI + ## CI provider --This project uses [GitHub Actions](https://github.com/features/actions) as a --CI server: it imports production backups into fully built codebase and runs --code linting and tests. When tests pass, a deployment process is triggered for --nominated branches (usually, `main` and `develop`). -+This project uses [Circle CI](https://circleci.com/) as a CI server: it imports -+production backups into fully built codebase and runs code linting and tests. -+When tests pass, a deployment process is triggered for nominated branches -+(usually, `main` and `develop`). +-This project uses [GitHub Actions](https://github.com/features/actions). ++This project uses [CircleCI](https://circleci.com/). - Refer to https://www.vortextemplate.com/docs/continuous-integration for more - information. -@@ -22,9 +22,6 @@ +-See [GitHub Actions documentation](https://www.vortextemplate.com/docs/continuous-integration/github-actions) ++See [CircleCI documentation](https://www.vortextemplate.com/docs/continuous-integration/circleci) + for setup and configuration details. - ### SSH - --GitHub Actions does not supports shell access to the build, but there is an --action provided withing the `build` job that allows you to run a build with SSH --support. -- --Use "Run workflow" button in GitHub Actions UI to start build with SSH support --that will be available for 120 minutes after the build is finished. -+Circle CI supports shell access to the build for 120 minutes after the build is -+finished when the build is started with SSH support. Use "Rerun job with SSH" -+button in Circle CI UI to start build with SSH support. + ## Project-specific configuration diff --git a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_all_circleci/.env b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_all_circleci/.env index 7ced3c763..43a0cb4ef 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_all_circleci/.env +++ b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_all_circleci/.env @@ -1,7 +1,7 @@ @@ -172,7 +172,7 @@ # Deployment occurs when tests pass in the CI environment. - # @see https://www.vortextemplate.com/docs/workflows/deployment + # @see https://www.vortextemplate.com/docs/deployment -VORTEX_DEPLOY_TYPES=webhook +VORTEX_DEPLOY_TYPES=webhook,container_image,lagoon,artifact diff --git a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_all_circleci/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_all_circleci/CLAUDE.md deleted file mode 100644 index 109f9b3b5..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_all_circleci/CLAUDE.md +++ /dev/null @@ -1,9 +0,0 @@ -@@ -796,7 +796,7 @@ - - This project includes automated deployment via: - --- **GitHub Actions** - See `.github/workflows/` -+- **CircleCI** - See `.circleci/config.yml` - - ### Hosting Platforms - diff --git a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_all_circleci/docs/ci.md b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_all_circleci/docs/ci.md index 419d99d2b..542f58060 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_all_circleci/docs/ci.md +++ b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_all_circleci/docs/ci.md @@ -1,31 +1,12 @@ -@@ -5,12 +5,12 @@ - Before feature changes can be merged into a shared mainline, a complete build - must run and pass all tests on CI server. +@@ -5,9 +5,9 @@ --## GitHub Actions -+## Circle CI + ## CI provider --This project uses [GitHub Actions](https://github.com/features/actions) as a --CI server: it imports production backups into fully built codebase and runs --code linting and tests. When tests pass, a deployment process is triggered for --nominated branches (usually, `main` and `develop`). -+This project uses [Circle CI](https://circleci.com/) as a CI server: it imports -+production backups into fully built codebase and runs code linting and tests. -+When tests pass, a deployment process is triggered for nominated branches -+(usually, `main` and `develop`). +-This project uses [GitHub Actions](https://github.com/features/actions). ++This project uses [CircleCI](https://circleci.com/). - Refer to https://www.vortextemplate.com/docs/continuous-integration for more - information. -@@ -22,9 +22,6 @@ +-See [GitHub Actions documentation](https://www.vortextemplate.com/docs/continuous-integration/github-actions) ++See [CircleCI documentation](https://www.vortextemplate.com/docs/continuous-integration/circleci) + for setup and configuration details. - ### SSH - --GitHub Actions does not supports shell access to the build, but there is an --action provided withing the `build` job that allows you to run a build with SSH --support. -- --Use "Run workflow" button in GitHub Actions UI to start build with SSH support --that will be available for 120 minutes after the build is finished. -+Circle CI supports shell access to the build for 120 minutes after the build is -+finished when the build is started with SSH support. Use "Rerun job with SSH" -+button in Circle CI UI to start build with SSH support. + ## Project-specific configuration diff --git a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_all_gha/.env b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_all_gha/.env index 7ced3c763..43a0cb4ef 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_all_gha/.env +++ b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_all_gha/.env @@ -1,7 +1,7 @@ @@ -172,7 +172,7 @@ # Deployment occurs when tests pass in the CI environment. - # @see https://www.vortextemplate.com/docs/workflows/deployment + # @see https://www.vortextemplate.com/docs/deployment -VORTEX_DEPLOY_TYPES=webhook +VORTEX_DEPLOY_TYPES=webhook,container_image,lagoon,artifact diff --git a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_artifact/.env b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_artifact/.env index ae1b74363..43e40213f 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_artifact/.env +++ b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_artifact/.env @@ -1,7 +1,7 @@ @@ -172,7 +172,7 @@ # Deployment occurs when tests pass in the CI environment. - # @see https://www.vortextemplate.com/docs/workflows/deployment + # @see https://www.vortextemplate.com/docs/deployment -VORTEX_DEPLOY_TYPES=webhook +VORTEX_DEPLOY_TYPES=artifact diff --git a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_container_image/.env b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_container_image/.env index 1db51ae4f..907c7a7ee 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_container_image/.env +++ b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_container_image/.env @@ -1,7 +1,7 @@ @@ -172,7 +172,7 @@ # Deployment occurs when tests pass in the CI environment. - # @see https://www.vortextemplate.com/docs/workflows/deployment + # @see https://www.vortextemplate.com/docs/deployment -VORTEX_DEPLOY_TYPES=webhook +VORTEX_DEPLOY_TYPES=container_image diff --git a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_lagoon/.env b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_lagoon/.env index 4ddf446a3..44ac598c2 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_lagoon/.env +++ b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_lagoon/.env @@ -1,7 +1,7 @@ @@ -172,7 +172,7 @@ # Deployment occurs when tests pass in the CI environment. - # @see https://www.vortextemplate.com/docs/workflows/deployment + # @see https://www.vortextemplate.com/docs/deployment -VORTEX_DEPLOY_TYPES=webhook +VORTEX_DEPLOY_TYPES=lagoon diff --git a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_none_circleci/.env b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_none_circleci/.env index bb8b4fd4d..ffcc670f1 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_none_circleci/.env +++ b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_none_circleci/.env @@ -6,7 +6,7 @@ -################################################################################ - -# Deployment occurs when tests pass in the CI environment. --# @see https://www.vortextemplate.com/docs/workflows/deployment +-# @see https://www.vortextemplate.com/docs/deployment -VORTEX_DEPLOY_TYPES=webhook - -################################################################################ diff --git a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_none_circleci/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_none_circleci/CLAUDE.md deleted file mode 100644 index 109f9b3b5..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_none_circleci/CLAUDE.md +++ /dev/null @@ -1,9 +0,0 @@ -@@ -796,7 +796,7 @@ - - This project includes automated deployment via: - --- **GitHub Actions** - See `.github/workflows/` -+- **CircleCI** - See `.circleci/config.yml` - - ### Hosting Platforms - diff --git a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_none_circleci/docs/ci.md b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_none_circleci/docs/ci.md index 419d99d2b..542f58060 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_none_circleci/docs/ci.md +++ b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_none_circleci/docs/ci.md @@ -1,31 +1,12 @@ -@@ -5,12 +5,12 @@ - Before feature changes can be merged into a shared mainline, a complete build - must run and pass all tests on CI server. +@@ -5,9 +5,9 @@ --## GitHub Actions -+## Circle CI + ## CI provider --This project uses [GitHub Actions](https://github.com/features/actions) as a --CI server: it imports production backups into fully built codebase and runs --code linting and tests. When tests pass, a deployment process is triggered for --nominated branches (usually, `main` and `develop`). -+This project uses [Circle CI](https://circleci.com/) as a CI server: it imports -+production backups into fully built codebase and runs code linting and tests. -+When tests pass, a deployment process is triggered for nominated branches -+(usually, `main` and `develop`). +-This project uses [GitHub Actions](https://github.com/features/actions). ++This project uses [CircleCI](https://circleci.com/). - Refer to https://www.vortextemplate.com/docs/continuous-integration for more - information. -@@ -22,9 +22,6 @@ +-See [GitHub Actions documentation](https://www.vortextemplate.com/docs/continuous-integration/github-actions) ++See [CircleCI documentation](https://www.vortextemplate.com/docs/continuous-integration/circleci) + for setup and configuration details. - ### SSH - --GitHub Actions does not supports shell access to the build, but there is an --action provided withing the `build` job that allows you to run a build with SSH --support. -- --Use "Run workflow" button in GitHub Actions UI to start build with SSH support --that will be available for 120 minutes after the build is finished. -+Circle CI supports shell access to the build for 120 minutes after the build is -+finished when the build is started with SSH support. Use "Rerun job with SSH" -+button in Circle CI UI to start build with SSH support. + ## Project-specific configuration diff --git a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_none_gha/.env b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_none_gha/.env index bb8b4fd4d..ffcc670f1 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/deploy_types_none_gha/.env +++ b/.vortex/installer/tests/Fixtures/handler_process/deploy_types_none_gha/.env @@ -6,7 +6,7 @@ -################################################################################ - -# Deployment occurs when tests pass in the CI environment. --# @see https://www.vortextemplate.com/docs/workflows/deployment +-# @see https://www.vortextemplate.com/docs/deployment -VORTEX_DEPLOY_TYPES=webhook - -################################################################################ diff --git a/.vortex/installer/tests/Fixtures/handler_process/deps_updates_provider_ci_circleci/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/deps_updates_provider_ci_circleci/CLAUDE.md deleted file mode 100644 index 109f9b3b5..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/deps_updates_provider_ci_circleci/CLAUDE.md +++ /dev/null @@ -1,9 +0,0 @@ -@@ -796,7 +796,7 @@ - - This project includes automated deployment via: - --- **GitHub Actions** - See `.github/workflows/` -+- **CircleCI** - See `.circleci/config.yml` - - ### Hosting Platforms - diff --git a/.vortex/installer/tests/Fixtures/handler_process/deps_updates_provider_ci_circleci/docs/ci.md b/.vortex/installer/tests/Fixtures/handler_process/deps_updates_provider_ci_circleci/docs/ci.md index 419d99d2b..542f58060 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/deps_updates_provider_ci_circleci/docs/ci.md +++ b/.vortex/installer/tests/Fixtures/handler_process/deps_updates_provider_ci_circleci/docs/ci.md @@ -1,31 +1,12 @@ -@@ -5,12 +5,12 @@ - Before feature changes can be merged into a shared mainline, a complete build - must run and pass all tests on CI server. +@@ -5,9 +5,9 @@ --## GitHub Actions -+## Circle CI + ## CI provider --This project uses [GitHub Actions](https://github.com/features/actions) as a --CI server: it imports production backups into fully built codebase and runs --code linting and tests. When tests pass, a deployment process is triggered for --nominated branches (usually, `main` and `develop`). -+This project uses [Circle CI](https://circleci.com/) as a CI server: it imports -+production backups into fully built codebase and runs code linting and tests. -+When tests pass, a deployment process is triggered for nominated branches -+(usually, `main` and `develop`). +-This project uses [GitHub Actions](https://github.com/features/actions). ++This project uses [CircleCI](https://circleci.com/). - Refer to https://www.vortextemplate.com/docs/continuous-integration for more - information. -@@ -22,9 +22,6 @@ +-See [GitHub Actions documentation](https://www.vortextemplate.com/docs/continuous-integration/github-actions) ++See [CircleCI documentation](https://www.vortextemplate.com/docs/continuous-integration/circleci) + for setup and configuration details. - ### SSH - --GitHub Actions does not supports shell access to the build, but there is an --action provided withing the `build` job that allows you to run a build with SSH --support. -- --Use "Run workflow" button in GitHub Actions UI to start build with SSH support --that will be available for 120 minutes after the build is finished. -+Circle CI supports shell access to the build for 120 minutes after the build is -+finished when the build is started with SSH support. Use "Rerun job with SSH" -+button in Circle CI UI to start build with SSH support. + ## Project-specific configuration diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/.env b/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/.env index c67d6835e..176e4d873 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/.env +++ b/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/.env @@ -49,7 +49,7 @@ @@ -172,7 +177,7 @@ # Deployment occurs when tests pass in the CI environment. - # @see https://www.vortextemplate.com/docs/workflows/deployment + # @see https://www.vortextemplate.com/docs/deployment -VORTEX_DEPLOY_TYPES=webhook +VORTEX_DEPLOY_TYPES=artifact diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/CLAUDE.md index 0da52bf20..1b35c008b 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/CLAUDE.md @@ -1,45 +1,11 @@ -@@ -189,7 +189,7 @@ - │ ├── stage/ # Staging-specific overrides - │ └── ci/ # CI-specific overrides - │ --├── web/ # Drupal webroot (document root) -+├── docroot/ # Drupal webroot (document root) - │ ├── modules/custom/ # Your custom modules - │ ├── themes/custom/ # Your custom themes - │ ├── sites/default/ # Drupal site settings -@@ -214,7 +214,7 @@ - # Generate custom module scaffold - ahoy drush generate:module +@@ -56,8 +56,8 @@ --# Location: web/modules/custom/[module_name]/ -+# Location: docroot/modules/custom/[module_name]/ - # Enable module: - ahoy drush pm:install [module_name] - ``` -@@ -223,7 +223,7 @@ - - ```bash - # Navigate to custom theme --cd web/themes/custom/[theme_name] -+cd docroot/themes/custom/[theme_name] - - # Install theme dependencies - yarn install -@@ -603,7 +603,7 @@ - - ```bash - # Navigate to theme directory --cd web/themes/custom/[theme_name] -+cd docroot/themes/custom/[theme_name] - - # Add frontend dependencies - yarn add [package-name] -@@ -799,6 +799,8 @@ - - **GitHub Actions** - See `.github/workflows/` - - ### Hosting Platforms -+ -+- **Acquia Cloud** - Enterprise Drupal hosting - - - **Container Registry** - Docker-based deployments + ## Key Directories +-- `web/modules/custom/` - Custom modules +-- `web/themes/custom/` - Custom themes ++- `docroot/modules/custom/` - Custom modules ++- `docroot/themes/custom/` - Custom themes + - `config/default/` - Drupal configuration + - `scripts/custom/` - Project scripts + - `patches/` - Module patches diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/docs/deployment.md b/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/docs/deployment.md index 49b291cc4..18e6a1a31 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/docs/deployment.md +++ b/.vortex/installer/tests/Fixtures/handler_process/hosting_acquia/docs/deployment.md @@ -1,84 +1,33 @@ -@@ -16,3 +16,83 @@ - deployment. +@@ -3,6 +3,32 @@ + For information on how deployment works, see + [Vortex Deployment Documentation](https://www.vortextemplate.com/docs/deployment). - Once PR is closed, the environment will be automatically removed. ++## Hosting provider + -+GitHub is a primary code repository for this project (aka "source repository"). -+Acquia Cloud is a hosting provider for this project and it also has a git -+repository (aka "destination repository"). ++This project is hosted on [Acquia Cloud](https://www.acquia.com/products/drupal-cloud). + -+The website gets deployed using artifact built on CI and pushed to Acquia Cloud. ++See [Acquia hosting documentation](https://www.vortextemplate.com/docs/hosting/acquia) ++for setup and configuration details. + -+There are 2 types of deployments: feature branches and release tags. They are -+exactly the same except for the resulting branch name on Acquia Cloud (see -+below). ++### Deployment workflow + -+## Setup -+ -+1. Create a Deployer user (deployer@yourcompany.com) account in Acquia. -+2. Add this user to Acquia Cloud application with a role that allows to push -+ code and use Cloud API. -+3. Login with Deployer user and go to Acquia Cloud UI->Account->Credentials-> -+ Copy email and key from section "Cloud API". -+4. SSH into non-production server and run `drush ac-api-login`. Enter copied -+ email and key when prompted. This will store credentials -+ to `$HOME/.acquia/cloudapi.conf`and they will not need to be entered again. -+ This allows to use Cloud API drush commands within hooks. -+5. Create SSH key (use `deployer+yourproject@yourcompany.com` as an email to -+ distinguish SSH keys) and add it to this user. This key cannot be re-used -+ between projects! -+6. Login to CircleCI, go to Settings->SSH Permissions->Add SSH Key and paste * -+ private* key. This allows to push the code from CI to Acquia git repository. -+7. Copy SHH key fingerprint (looks -+ like `16:02:e3:ca:33:04:82:58:e8:e9:3e:5d:82:17:86:b1`) and replace it -+ inside `.circleci/config.yml`. -+ -+## Deployment workflow -+ -+1. Developer updates DB in the Acquia Cloud environment by copying PROD database -+ to required environment. -+2. Developer pushes code update to the GitHub branch. -+3. CI system picks-up the update and does the following: -+4. Builds a website using production DB. -+5. Runs code standard checks and Behat tests on the built website. -+6. Creates a deployment artifact (project files to be pushed to Acquia Cloud ++1. Code is pushed to GitHub (source repository). ++2. CI builds and tests the code. ++3. On success, CI builds an artifact and pushes to Acquia Cloud (destination + repository). -+7. Pushes created artifact to the Acquia Cloud repository: -+ - for feature-based branches (i.e. `feature/ABC-123` or `bugfix/ABC-123`) -+ the code is pushed to the branch with exactly the same name. -+ - for release deployments, which are tag-based (i.e. `__VERSION__`), the code is -+ pushed to the branch `deployment/[tag]` (i.e. `deployment/__VERSION__`). -+8. Acquia Cloud picks up recent push to the repository and -+ runs [post code update hooks](hooks/dev/post-code-update) on the environments -+ where code is already deployed. -+ OR -+9. If the branch has not been deployed into any Acquia Cloud environment yet and -+ the developer starts the deployment, Acquia Cloud -+ runs [post code deploy hooks](hooks/dev/post-code-deploy) on the environment -+ where code is being deployed. ++4. Acquia Cloud runs deployment hooks. + -+### Release outcome ++### Branch naming on Acquia Cloud + -+1. Release branch exists as `deployment/X.Y.Z` in remote GitHub repository. -+2. Release tag exists as `X.Y.Z` in remote GitHub repository. -+3. The `HEAD` of the `main` branch has `X.Y.Z` tag assigned. -+4. The hash of the `HEAD` of the `main` branch exists in the `develop` branch. -+ This is to ensure that everything pushed to `main` exists in `developed` (in -+ case if `main` had any hot-fixes that not yet have been merged to `develop`). -+5. There are no PRs in GitHub related to releases. -+6. Release branch is available on Acquia Cloud as `deployment/X.Y.Z` branch. -+ Note: we are building release branches on Acquia Cloud out of tags in GitHub. -+7. Release branch `deployment/X.Y.Z` is deployed into PROD environment. Note: we -+ are NOT deploying tags to Acquia Cloud PROD. ++- Feature branches (`feature/ABC-123`) → same name on Acquia ++- Release tags (`__VERSION__`) → `deployment/__VERSION__` branch on Acquia + -+### Important ++### Important rules + -+Since Acquia Cloud becomes a destination repository, the following rules MUST be -+followed by all developers: ++- No direct pushes to Acquia Cloud repository. ++- Only Technical Lead and Deployer user should have access to Acquia repository. ++- Technical Lead should regularly clean up `feature/*` and `bugfix/*` branches. + -+1. There should be no direct access to Acquia Cloud repository for anyone except -+ for project Technical Lead and Deployer user. -+2. There should be no pushes to Acquia Cloud repository. -+3. There may be `main` or `develop` branch in Acquia Cloud repository. -+4. Technical Lead is expected to regularly cleanup `feature/*` and `bugfix/*` -+ branches in Acquia Cloud repository. + ## Project-specific configuration + + diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_lagoon/.env b/.vortex/installer/tests/Fixtures/handler_process/hosting_lagoon/.env index df89bcf51..fc190f9c5 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/hosting_lagoon/.env +++ b/.vortex/installer/tests/Fixtures/handler_process/hosting_lagoon/.env @@ -35,7 +35,7 @@ @@ -172,7 +179,7 @@ # Deployment occurs when tests pass in the CI environment. - # @see https://www.vortextemplate.com/docs/workflows/deployment + # @see https://www.vortextemplate.com/docs/deployment -VORTEX_DEPLOY_TYPES=webhook +VORTEX_DEPLOY_TYPES=lagoon diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_lagoon/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/hosting_lagoon/CLAUDE.md deleted file mode 100644 index b75036869..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/hosting_lagoon/CLAUDE.md +++ /dev/null @@ -1,9 +0,0 @@ -@@ -800,6 +800,8 @@ - - ### Hosting Platforms - -+- **Lagoon** - Container-based hosting platform -+ - - **Container Registry** - Docker-based deployments - - ### Manual Deployment Commands diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_lagoon/docs/deployment.md b/.vortex/installer/tests/Fixtures/handler_process/hosting_lagoon/docs/deployment.md index 0901ecf4e..056defcbe 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/hosting_lagoon/docs/deployment.md +++ b/.vortex/installer/tests/Fixtures/handler_process/hosting_lagoon/docs/deployment.md @@ -1,13 +1,22 @@ -@@ -16,3 +16,12 @@ - deployment. +@@ -3,6 +3,21 @@ + For information on how deployment works, see + [Vortex Deployment Documentation](https://www.vortextemplate.com/docs/deployment). - Once PR is closed, the environment will be automatically removed. ++## Hosting provider + -+## Database refresh in Lagoon environments ++This project is hosted on [Lagoon](https://www.amazee.io/lagoon). + -+To refresh the database in the existing Lagoon environment with the database from -+production environment, run: ++See [Lagoon hosting documentation](https://www.vortextemplate.com/docs/hosting/lagoon) ++for setup and configuration details. ++ ++### Database refresh ++ ++To refresh the database in an existing Lagoon environment with production data: + +```bash +VORTEX_DEPLOY_BRANCH= VORTEX_DEPLOY_ACTION=deploy_override_db ahoy deploy +``` ++ + ## Project-specific configuration + + diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/.env b/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/.env index 6ef0db6b8..e9c2b99dd 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/.env +++ b/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/.env @@ -49,7 +49,7 @@ @@ -172,7 +177,7 @@ # Deployment occurs when tests pass in the CI environment. - # @see https://www.vortextemplate.com/docs/workflows/deployment + # @see https://www.vortextemplate.com/docs/deployment -VORTEX_DEPLOY_TYPES=webhook +VORTEX_DEPLOY_TYPES=artifact diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/CLAUDE.md index 0da52bf20..1b35c008b 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/CLAUDE.md @@ -1,45 +1,11 @@ -@@ -189,7 +189,7 @@ - │ ├── stage/ # Staging-specific overrides - │ └── ci/ # CI-specific overrides - │ --├── web/ # Drupal webroot (document root) -+├── docroot/ # Drupal webroot (document root) - │ ├── modules/custom/ # Your custom modules - │ ├── themes/custom/ # Your custom themes - │ ├── sites/default/ # Drupal site settings -@@ -214,7 +214,7 @@ - # Generate custom module scaffold - ahoy drush generate:module +@@ -56,8 +56,8 @@ --# Location: web/modules/custom/[module_name]/ -+# Location: docroot/modules/custom/[module_name]/ - # Enable module: - ahoy drush pm:install [module_name] - ``` -@@ -223,7 +223,7 @@ - - ```bash - # Navigate to custom theme --cd web/themes/custom/[theme_name] -+cd docroot/themes/custom/[theme_name] - - # Install theme dependencies - yarn install -@@ -603,7 +603,7 @@ - - ```bash - # Navigate to theme directory --cd web/themes/custom/[theme_name] -+cd docroot/themes/custom/[theme_name] - - # Add frontend dependencies - yarn add [package-name] -@@ -799,6 +799,8 @@ - - **GitHub Actions** - See `.github/workflows/` - - ### Hosting Platforms -+ -+- **Acquia Cloud** - Enterprise Drupal hosting - - - **Container Registry** - Docker-based deployments + ## Key Directories +-- `web/modules/custom/` - Custom modules +-- `web/themes/custom/` - Custom themes ++- `docroot/modules/custom/` - Custom modules ++- `docroot/themes/custom/` - Custom themes + - `config/default/` - Drupal configuration + - `scripts/custom/` - Project scripts + - `patches/` - Module patches diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/docs/deployment.md b/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/docs/deployment.md index 49b291cc4..18e6a1a31 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/docs/deployment.md +++ b/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___acquia/docs/deployment.md @@ -1,84 +1,33 @@ -@@ -16,3 +16,83 @@ - deployment. +@@ -3,6 +3,32 @@ + For information on how deployment works, see + [Vortex Deployment Documentation](https://www.vortextemplate.com/docs/deployment). - Once PR is closed, the environment will be automatically removed. ++## Hosting provider + -+GitHub is a primary code repository for this project (aka "source repository"). -+Acquia Cloud is a hosting provider for this project and it also has a git -+repository (aka "destination repository"). ++This project is hosted on [Acquia Cloud](https://www.acquia.com/products/drupal-cloud). + -+The website gets deployed using artifact built on CI and pushed to Acquia Cloud. ++See [Acquia hosting documentation](https://www.vortextemplate.com/docs/hosting/acquia) ++for setup and configuration details. + -+There are 2 types of deployments: feature branches and release tags. They are -+exactly the same except for the resulting branch name on Acquia Cloud (see -+below). ++### Deployment workflow + -+## Setup -+ -+1. Create a Deployer user (deployer@yourcompany.com) account in Acquia. -+2. Add this user to Acquia Cloud application with a role that allows to push -+ code and use Cloud API. -+3. Login with Deployer user and go to Acquia Cloud UI->Account->Credentials-> -+ Copy email and key from section "Cloud API". -+4. SSH into non-production server and run `drush ac-api-login`. Enter copied -+ email and key when prompted. This will store credentials -+ to `$HOME/.acquia/cloudapi.conf`and they will not need to be entered again. -+ This allows to use Cloud API drush commands within hooks. -+5. Create SSH key (use `deployer+yourproject@yourcompany.com` as an email to -+ distinguish SSH keys) and add it to this user. This key cannot be re-used -+ between projects! -+6. Login to CircleCI, go to Settings->SSH Permissions->Add SSH Key and paste * -+ private* key. This allows to push the code from CI to Acquia git repository. -+7. Copy SHH key fingerprint (looks -+ like `16:02:e3:ca:33:04:82:58:e8:e9:3e:5d:82:17:86:b1`) and replace it -+ inside `.circleci/config.yml`. -+ -+## Deployment workflow -+ -+1. Developer updates DB in the Acquia Cloud environment by copying PROD database -+ to required environment. -+2. Developer pushes code update to the GitHub branch. -+3. CI system picks-up the update and does the following: -+4. Builds a website using production DB. -+5. Runs code standard checks and Behat tests on the built website. -+6. Creates a deployment artifact (project files to be pushed to Acquia Cloud ++1. Code is pushed to GitHub (source repository). ++2. CI builds and tests the code. ++3. On success, CI builds an artifact and pushes to Acquia Cloud (destination + repository). -+7. Pushes created artifact to the Acquia Cloud repository: -+ - for feature-based branches (i.e. `feature/ABC-123` or `bugfix/ABC-123`) -+ the code is pushed to the branch with exactly the same name. -+ - for release deployments, which are tag-based (i.e. `__VERSION__`), the code is -+ pushed to the branch `deployment/[tag]` (i.e. `deployment/__VERSION__`). -+8. Acquia Cloud picks up recent push to the repository and -+ runs [post code update hooks](hooks/dev/post-code-update) on the environments -+ where code is already deployed. -+ OR -+9. If the branch has not been deployed into any Acquia Cloud environment yet and -+ the developer starts the deployment, Acquia Cloud -+ runs [post code deploy hooks](hooks/dev/post-code-deploy) on the environment -+ where code is being deployed. ++4. Acquia Cloud runs deployment hooks. + -+### Release outcome ++### Branch naming on Acquia Cloud + -+1. Release branch exists as `deployment/X.Y.Z` in remote GitHub repository. -+2. Release tag exists as `X.Y.Z` in remote GitHub repository. -+3. The `HEAD` of the `main` branch has `X.Y.Z` tag assigned. -+4. The hash of the `HEAD` of the `main` branch exists in the `develop` branch. -+ This is to ensure that everything pushed to `main` exists in `developed` (in -+ case if `main` had any hot-fixes that not yet have been merged to `develop`). -+5. There are no PRs in GitHub related to releases. -+6. Release branch is available on Acquia Cloud as `deployment/X.Y.Z` branch. -+ Note: we are building release branches on Acquia Cloud out of tags in GitHub. -+7. Release branch `deployment/X.Y.Z` is deployed into PROD environment. Note: we -+ are NOT deploying tags to Acquia Cloud PROD. ++- Feature branches (`feature/ABC-123`) → same name on Acquia ++- Release tags (`__VERSION__`) → `deployment/__VERSION__` branch on Acquia + -+### Important ++### Important rules + -+Since Acquia Cloud becomes a destination repository, the following rules MUST be -+followed by all developers: ++- No direct pushes to Acquia Cloud repository. ++- Only Technical Lead and Deployer user should have access to Acquia repository. ++- Technical Lead should regularly clean up `feature/*` and `bugfix/*` branches. + -+1. There should be no direct access to Acquia Cloud repository for anyone except -+ for project Technical Lead and Deployer user. -+2. There should be no pushes to Acquia Cloud repository. -+3. There may be `main` or `develop` branch in Acquia Cloud repository. -+4. Technical Lead is expected to regularly cleanup `feature/*` and `bugfix/*` -+ branches in Acquia Cloud repository. + ## Project-specific configuration + + diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___lagoon/.env b/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___lagoon/.env index cdebb4109..b14fb092d 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___lagoon/.env +++ b/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___lagoon/.env @@ -35,7 +35,7 @@ @@ -172,7 +179,7 @@ # Deployment occurs when tests pass in the CI environment. - # @see https://www.vortextemplate.com/docs/workflows/deployment + # @see https://www.vortextemplate.com/docs/deployment -VORTEX_DEPLOY_TYPES=webhook +VORTEX_DEPLOY_TYPES=lagoon diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___lagoon/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___lagoon/CLAUDE.md deleted file mode 100644 index b75036869..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___lagoon/CLAUDE.md +++ /dev/null @@ -1,9 +0,0 @@ -@@ -800,6 +800,8 @@ - - ### Hosting Platforms - -+- **Lagoon** - Container-based hosting platform -+ - - **Container Registry** - Docker-based deployments - - ### Manual Deployment Commands diff --git a/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___lagoon/docs/deployment.md b/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___lagoon/docs/deployment.md index 0901ecf4e..056defcbe 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___lagoon/docs/deployment.md +++ b/.vortex/installer/tests/Fixtures/handler_process/hosting_project_name___lagoon/docs/deployment.md @@ -1,13 +1,22 @@ -@@ -16,3 +16,12 @@ - deployment. +@@ -3,6 +3,21 @@ + For information on how deployment works, see + [Vortex Deployment Documentation](https://www.vortextemplate.com/docs/deployment). - Once PR is closed, the environment will be automatically removed. ++## Hosting provider + -+## Database refresh in Lagoon environments ++This project is hosted on [Lagoon](https://www.amazee.io/lagoon). + -+To refresh the database in the existing Lagoon environment with the database from -+production environment, run: ++See [Lagoon hosting documentation](https://www.vortextemplate.com/docs/hosting/lagoon) ++for setup and configuration details. ++ ++### Database refresh ++ ++To refresh the database in an existing Lagoon environment with production data: + +```bash +VORTEX_DEPLOY_BRANCH= VORTEX_DEPLOY_ACTION=deploy_override_db ahoy deploy +``` ++ + ## Project-specific configuration + + diff --git a/.vortex/installer/tests/Fixtures/handler_process/names/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/names/CLAUDE.md new file mode 100644 index 000000000..413cef42b --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/names/CLAUDE.md @@ -0,0 +1,6 @@ +@@ -1,4 +1,4 @@ +-# star wars - Development Guide ++# New hope - Development Guide + + diff --git a/.vortex/installer/tests/Fixtures/handler_process/services_no_clamav/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/services_no_clamav/CLAUDE.md deleted file mode 100644 index f7d027220..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/services_no_clamav/CLAUDE.md +++ /dev/null @@ -1,20 +0,0 @@ -@@ -318,19 +318,6 @@ - ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" - ``` - --### ClamAV Virus Scanning Service -- --```bash --# Test virus scanning functionality --ahoy drush clamav:scan /path/to/test/file -- --# Check ClamAV daemon status --ahoy drush clamav:status -- --# Update virus definitions --ahoy drush clamav:update --``` -- - ## Dependency Management - - ### Adding Drupal Modules diff --git a/.vortex/installer/tests/Fixtures/handler_process/services_no_redis/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/services_no_redis/CLAUDE.md deleted file mode 100644 index c32593524..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/services_no_redis/CLAUDE.md +++ /dev/null @@ -1,20 +0,0 @@ -@@ -305,19 +305,6 @@ - ahoy drush search-api:server-status - ``` - --### Redis Caching Service -- --```bash --# Clear all caches (includes Redis) --ahoy drush cache:rebuild -- --# Check Redis connection status --ahoy drush php:script -- redis_status -- --# Flush Redis cache specifically --ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" --``` -- - ### ClamAV Virus Scanning Service - - ```bash diff --git a/.vortex/installer/tests/Fixtures/handler_process/services_no_solr/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/services_no_solr/CLAUDE.md deleted file mode 100644 index d59e88919..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/services_no_solr/CLAUDE.md +++ /dev/null @@ -1,24 +0,0 @@ -@@ -288,23 +288,6 @@ - - ## Service Integrations - --### Solr Search Service -- --```bash --# Check Solr search status --ahoy drush search-api:status -- --# Index all content to Solr --ahoy drush search-api:index -- --# Clear and rebuild Solr index --ahoy drush search-api:clear --ahoy drush search-api:index -- --# Check Solr server connection --ahoy drush search-api:server-status --``` -- - ### Redis Caching Service - - ```bash diff --git a/.vortex/installer/tests/Fixtures/handler_process/services_none/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/services_none/CLAUDE.md deleted file mode 100644 index cd453cf14..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/services_none/CLAUDE.md +++ /dev/null @@ -1,50 +0,0 @@ -@@ -288,49 +288,6 @@ - - ## Service Integrations - --### Solr Search Service -- --```bash --# Check Solr search status --ahoy drush search-api:status -- --# Index all content to Solr --ahoy drush search-api:index -- --# Clear and rebuild Solr index --ahoy drush search-api:clear --ahoy drush search-api:index -- --# Check Solr server connection --ahoy drush search-api:server-status --``` -- --### Redis Caching Service -- --```bash --# Clear all caches (includes Redis) --ahoy drush cache:rebuild -- --# Check Redis connection status --ahoy drush php:script -- redis_status -- --# Flush Redis cache specifically --ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" --``` -- --### ClamAV Virus Scanning Service -- --```bash --# Test virus scanning functionality --ahoy drush clamav:scan /path/to/test/file -- --# Check ClamAV daemon status --ahoy drush clamav:status -- --# Update virus definitions --ahoy drush clamav:update --``` -- - ## Dependency Management - - ### Adding Drupal Modules diff --git a/.vortex/installer/tests/Fixtures/handler_process/theme_claro/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/theme_claro/CLAUDE.md deleted file mode 100644 index d11b40fbf..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/theme_claro/CLAUDE.md +++ /dev/null @@ -1,49 +0,0 @@ -@@ -219,25 +219,6 @@ - ahoy drush pm:install [module_name] - ``` - --### Theme Development -- --```bash --# Navigate to custom theme --cd web/themes/custom/[theme_name] -- --# Install theme dependencies --yarn install -- --# Build theme assets (CSS/JS) --yarn run build -- --# Watch for changes during development --yarn run watch -- --# Build for production --yarn run build:prod --``` -- - ## PHP Script Execution (IMPORTANT) - - ### ✅ Correct Way: Use PHP Scripts -@@ -597,22 +578,6 @@ - - ```bash - ahoy composer require vendor/library-name --``` -- --### Theme Dependencies -- --```bash --# Navigate to theme directory --cd web/themes/custom/[theme_name] -- --# Add frontend dependencies --yarn add [package-name] -- --# Example: Add Bootstrap --yarn add bootstrap -- --# Install dev dependencies --yarn add --dev sass webpack - ``` - - ## Testing Best Practices diff --git a/.vortex/installer/tests/Fixtures/handler_process/theme_olivero/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/theme_olivero/CLAUDE.md deleted file mode 100644 index d11b40fbf..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/theme_olivero/CLAUDE.md +++ /dev/null @@ -1,49 +0,0 @@ -@@ -219,25 +219,6 @@ - ahoy drush pm:install [module_name] - ``` - --### Theme Development -- --```bash --# Navigate to custom theme --cd web/themes/custom/[theme_name] -- --# Install theme dependencies --yarn install -- --# Build theme assets (CSS/JS) --yarn run build -- --# Watch for changes during development --yarn run watch -- --# Build for production --yarn run build:prod --``` -- - ## PHP Script Execution (IMPORTANT) - - ### ✅ Correct Way: Use PHP Scripts -@@ -597,22 +578,6 @@ - - ```bash - ahoy composer require vendor/library-name --``` -- --### Theme Dependencies -- --```bash --# Navigate to theme directory --cd web/themes/custom/[theme_name] -- --# Add frontend dependencies --yarn add [package-name] -- --# Example: Add Bootstrap --yarn add bootstrap -- --# Install dev dependencies --yarn add --dev sass webpack - ``` - - ## Testing Best Practices diff --git a/.vortex/installer/tests/Fixtures/handler_process/theme_stark/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/theme_stark/CLAUDE.md deleted file mode 100644 index d11b40fbf..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/theme_stark/CLAUDE.md +++ /dev/null @@ -1,49 +0,0 @@ -@@ -219,25 +219,6 @@ - ahoy drush pm:install [module_name] - ``` - --### Theme Development -- --```bash --# Navigate to custom theme --cd web/themes/custom/[theme_name] -- --# Install theme dependencies --yarn install -- --# Build theme assets (CSS/JS) --yarn run build -- --# Watch for changes during development --yarn run watch -- --# Build for production --yarn run build:prod --``` -- - ## PHP Script Execution (IMPORTANT) - - ### ✅ Correct Way: Use PHP Scripts -@@ -597,22 +578,6 @@ - - ```bash - ahoy composer require vendor/library-name --``` -- --### Theme Dependencies -- --```bash --# Navigate to theme directory --cd web/themes/custom/[theme_name] -- --# Add frontend dependencies --yarn add [package-name] -- --# Example: Add Bootstrap --yarn add bootstrap -- --# Install dev dependencies --yarn add --dev sass webpack - ``` - - ## Testing Best Practices diff --git a/.vortex/installer/tests/Fixtures/handler_process/timezone_circleci/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/timezone_circleci/CLAUDE.md deleted file mode 100644 index 109f9b3b5..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/timezone_circleci/CLAUDE.md +++ /dev/null @@ -1,9 +0,0 @@ -@@ -796,7 +796,7 @@ - - This project includes automated deployment via: - --- **GitHub Actions** - See `.github/workflows/` -+- **CircleCI** - See `.circleci/config.yml` - - ### Hosting Platforms - diff --git a/.vortex/installer/tests/Fixtures/handler_process/timezone_circleci/docs/ci.md b/.vortex/installer/tests/Fixtures/handler_process/timezone_circleci/docs/ci.md index 419d99d2b..542f58060 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/timezone_circleci/docs/ci.md +++ b/.vortex/installer/tests/Fixtures/handler_process/timezone_circleci/docs/ci.md @@ -1,31 +1,12 @@ -@@ -5,12 +5,12 @@ - Before feature changes can be merged into a shared mainline, a complete build - must run and pass all tests on CI server. +@@ -5,9 +5,9 @@ --## GitHub Actions -+## Circle CI + ## CI provider --This project uses [GitHub Actions](https://github.com/features/actions) as a --CI server: it imports production backups into fully built codebase and runs --code linting and tests. When tests pass, a deployment process is triggered for --nominated branches (usually, `main` and `develop`). -+This project uses [Circle CI](https://circleci.com/) as a CI server: it imports -+production backups into fully built codebase and runs code linting and tests. -+When tests pass, a deployment process is triggered for nominated branches -+(usually, `main` and `develop`). +-This project uses [GitHub Actions](https://github.com/features/actions). ++This project uses [CircleCI](https://circleci.com/). - Refer to https://www.vortextemplate.com/docs/continuous-integration for more - information. -@@ -22,9 +22,6 @@ +-See [GitHub Actions documentation](https://www.vortextemplate.com/docs/continuous-integration/github-actions) ++See [CircleCI documentation](https://www.vortextemplate.com/docs/continuous-integration/circleci) + for setup and configuration details. - ### SSH - --GitHub Actions does not supports shell access to the build, but there is an --action provided withing the `build` job that allows you to run a build with SSH --support. -- --Use "Run workflow" button in GitHub Actions UI to start build with SSH support --that will be available for 120 minutes after the build is finished. -+Circle CI supports shell access to the build for 120 minutes after the build is -+finished when the build is started with SSH support. Use "Rerun job with SSH" -+button in Circle CI UI to start build with SSH support. + ## Project-specific configuration diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_lint_circleci/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_lint_circleci/CLAUDE.md deleted file mode 100644 index 109f9b3b5..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_lint_circleci/CLAUDE.md +++ /dev/null @@ -1,9 +0,0 @@ -@@ -796,7 +796,7 @@ - - This project includes automated deployment via: - --- **GitHub Actions** - See `.github/workflows/` -+- **CircleCI** - See `.circleci/config.yml` - - ### Hosting Platforms - diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_lint_circleci/docs/ci.md b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_lint_circleci/docs/ci.md index 419d99d2b..542f58060 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_lint_circleci/docs/ci.md +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_lint_circleci/docs/ci.md @@ -1,31 +1,12 @@ -@@ -5,12 +5,12 @@ - Before feature changes can be merged into a shared mainline, a complete build - must run and pass all tests on CI server. +@@ -5,9 +5,9 @@ --## GitHub Actions -+## Circle CI + ## CI provider --This project uses [GitHub Actions](https://github.com/features/actions) as a --CI server: it imports production backups into fully built codebase and runs --code linting and tests. When tests pass, a deployment process is triggered for --nominated branches (usually, `main` and `develop`). -+This project uses [Circle CI](https://circleci.com/) as a CI server: it imports -+production backups into fully built codebase and runs code linting and tests. -+When tests pass, a deployment process is triggered for nominated branches -+(usually, `main` and `develop`). +-This project uses [GitHub Actions](https://github.com/features/actions). ++This project uses [CircleCI](https://circleci.com/). - Refer to https://www.vortextemplate.com/docs/continuous-integration for more - information. -@@ -22,9 +22,6 @@ +-See [GitHub Actions documentation](https://www.vortextemplate.com/docs/continuous-integration/github-actions) ++See [CircleCI documentation](https://www.vortextemplate.com/docs/continuous-integration/circleci) + for setup and configuration details. - ### SSH - --GitHub Actions does not supports shell access to the build, but there is an --action provided withing the `build` job that allows you to run a build with SSH --support. -- --Use "Run workflow" button in GitHub Actions UI to start build with SSH support --that will be available for 120 minutes after the build is finished. -+Circle CI supports shell access to the build for 120 minutes after the build is -+finished when the build is started with SSH support. Use "Rerun job with SSH" -+button in Circle CI UI to start build with SSH support. + ## Project-specific configuration diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/CLAUDE.md index 4196e19b3..8071a6faf 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/CLAUDE.md @@ -1,146 +1,17 @@ -@@ -8,8 +8,6 @@ - - Uses Docker for local development - - Commands are executed via 'ahoy' (task runner) - - Configuration is exported/imported via Drupal's config management --- Testing includes PHPUnit --- Testing includes Behat (BDD) - - Deployment is automated via CI/CD pipelines - - KEY CONVENTIONS: -@@ -122,19 +120,6 @@ - - ### Testing Framework - --```bash --# Run PHPUnit tests (unit/integration tests) --ahoy test-unit --``` -- --```bash --# Run Behat tests (behavioral/BDD tests) --ahoy test-bdd -- --# Run specific Behat feature --ahoy test-bdd tests/behat/features/homepage.feature --``` -- - ## Configuration Management (Critical for Drupal) - - ### Understanding Config Management -@@ -196,10 +181,6 @@ - │ └── index.php # Drupal entry point - │ - ├── tests/ --│ ├── behat/ # Behavioral tests (user scenarios) --│ │ ├── features/ # Test scenarios (.feature files) --│ │ └── behat.yml # Behat configuration --│ └── phpunit/ # Unit/integration tests - │ - └── scripts/ - ├── vortex/ # Core Vortex scripts (don't modify) -@@ -617,97 +598,6 @@ - - ## Testing Best Practices - --### Writing Behat Tests (BDD) -- --#### User Story Format (Required) -- --All Behat features MUST follow this format: -- --```gherkin --Feature: [Feature name] -- -- As a [user type] -- I want to [action/goal] -- So that [benefit/outcome] --``` -- --#### Standard User Types -- --```gherkin --As a site visitor # Anonymous users --As a site administrator # Admin users --As a content editor # Content management users --As a authenticated user # Logged-in users --``` -- --#### Test Data Conventions -- --- **Always prefix test content**: `[TEST] Page Title` --- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` --- **Avoid real names**: Don't use "Workshop" or "Training" --- **Be descriptive**: `[TEST] Event with All Fields` -- --#### Example Feature File -- --```gherkin --Feature: Homepage -- -- As a site visitor -- I want to access the homepage -- So that I can view the main landing page and navigate the site -- -- Scenario: View homepage content -- Given I am on the homepage -- Then I should see "[TEST] Welcome Message" -- And I should see "About Us" in the "navigation" region --``` -- --#### Discovering Available Step Definitions -- --```bash --# Generate step definitions reference (run once) --ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt --``` -- --Use the cached file for reference, don't regenerate unless asked. -- --### Content Type Testing Process -- --When creating comprehensive tests for content types: -- --1. **Analyze Configuration First** -- -- - Check `config/default/field.field.node.[type].*.yml` -- - Review `core.entity_view_display.node.[type].default.yml` -- - Identify visible vs hidden fields -- --1. **Create Supporting Entities** -- --```gherkin --Background: -- Given "tags" terms: -- | name | -- | [TEST] Topic 1 | -- | [TEST] Topic 2 | -- -- And the following media "image" exist: -- | name | -- | [TEST] Featured Image 1 | --``` -- --1. **Test All Visible Fields** -- --```gherkin --Scenario: View complete content with all fields -- Given "page" content: -- | title | body | field_tags | -- | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | -- When I visit "[TEST] Complete Page Test" -- Then I should see "[TEST] Complete Page Test" -- And I should see "[TEST] This is the body text." -- And I should see "[TEST] Topic 1" --``` -- - ## Debugging & Troubleshooting - - ### Development Tools -@@ -881,7 +771,6 @@ - - Always use ahoy prefix for commands - - Never use drush php:eval directly - - Test data must use [TEST] prefix --- Behat tests need proper user story format - - The project uses Docker locally but deploys to various hosting platforms with automated CI/CD. - CLAUDE_CONTEXT_SUMMARY --> +@@ -36,16 +36,6 @@ + ahoy lint # Check code style + ahoy lint-fix # Auto-fix code style + +-# PHPUnit testing +-ahoy test # Run PHPUnit tests +-ahoy test-unit # Run PHPUnit Unit tests +-ahoy test-kernel # Run PHPUnit Kernel tests +-ahoy test-functional # Run PHPUnit Functional tests +-ahoy test -- --filters=TestClassName # Run specific PHPUnit test class +- +-# Behat testing +-ahoy test-bdd # Run Behat tests +-ahoy test-bdd -- --tags=@tagname # Run Behat tests with specific tag + ``` + + ## Critical Rules diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/docs/faqs.md b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/docs/faqs.md deleted file mode 100644 index e445b0f50..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/docs/faqs.md +++ /dev/null @@ -1,29 +0,0 @@ -@@ -58,16 +58,6 @@ - - See https://www.vortextemplate.com/docs/tools/xdebug for more details. - --## How to use Xdebug on Behat scripts? -- --1. Enable debugging: `ahoy debug` --2. Enter CLI container: `ahoy cli` --3. Run Behat tests: -- --```bash --vendor/bin/behat --xdebug path/to/test.feature --``` -- - ## What should I do to switch to a "clean" branch environment? - - Provided that your stack is already running: -@@ -158,11 +148,3 @@ - - The maintenance theme should be a valid Drupal theme that is already installed - and enabled on your site. -- --## Behat tests with `@javascript` tag sometimes get stuck -- --Behat tests with `@javascript` tag sometimes get stuck for about 10min then --fail. --The Chrome container randomly get stuck for an unknown reason. -- --Restart the Chrome container: `docker compose restart chrome` diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/docs/testing.md b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/docs/testing.md new file mode 100644 index 000000000..712b28ae7 --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests/docs/testing.md @@ -0,0 +1,227 @@ +@@ -2,226 +2,3 @@ + + This document describes **what** testing conventions and agreements apply to + this project. +- +-## PHPUnit conventions +- +-Unit, Kernel, Functional tests. +- +-See [documentation](https://www.vortextemplate.com/docs/development/phpunit) +-on how to run tests, configure environment variables and code coverage, and use +-test reports in continuous integration pipeline. +- +-### Test class structure +- +-All PHPUnit tests must follow this structure: +- +-```php +-assertEquals('expected', $result); +- } +- +-} +-``` +- +-### Base test classes +- +-- **Unit** - `Drupal\Tests\UnitTestCase` - Testing isolated PHP classes +-- **Kernel** - `Drupal\KernelTests\KernelTestBase` - Testing with database/services +-- **Functional** - `Drupal\Tests\BrowserTestBase` - Testing with full browser +- +-### Test data conventions +- +-- **Always prefix test content**: `[TEST] Node Title` +-- **Use data providers**: For testing multiple input/output combinations +- - Must be a public static method +- - Must follow naming convention `dataProvider` +- - Must be placed after the test method it provides data for. +-- **Use unique identifiers**: Include test class or method name in test data +- +-### Data providers +- +-Always use data providers for testing multiple input/output combinations: +- +-```php +-/** +- * Test my function with various inputs. +- * +- * @dataProvider dataProviderMyFunction +- */ +-public function testMyFunction(string $input, string $expected): void { +- $this->assertEquals($expected, my_function($input)); +-} +- +-/** +- * Data provider for testMyFunction. +- */ +-public static function dataProviderMyFunction(): array { +- return [ +- 'empty string' => ['', ''], +- 'simple string' => ['hello', 'HELLO'], +- 'with numbers' => ['test123', 'TEST123'], +- ]; +-} +-``` +- +-### Testing services (Kernel tests) +- +-For Kernel tests that need Drupal services: +- +-```php +-installEntitySchema('node'); +- $this->installEntitySchema('user'); +- $this->myService = $this->container->get('my_module.my_service'); +- } +- +- /** +- * Test service method. +- */ +- public function testServiceMethod(): void { +- $result = $this->myService->doSomething(); +- $this->assertNotNull($result); +- } +- +-} +-``` +- +-## Behat conventions +- +-BDD end-to-end tests. +- +-See [documentation](https://www.vortextemplate.com/docs/development/behat) +-on how to run Behat tests, configure environment variables, and use test reports +-in continuous integration pipeline. +- +-### User story format +- +-All Behat features must follow this format: +- +-```gherkin +-Feature: [Feature name] +- +- As a [user type] +- I want to [action/goal] +- So that [benefit/outcome] +-``` +- +-### Standard user types +- +-Use these consistent user type descriptions: +- +-```gherkin +-As a site visitor # Anonymous users +-As a site administrator # Admin users +-As a content editor # Content management users +-As a authenticated user # Logged-in users +-``` +- +-### Test data conventions +- +-- **Always prefix test content**: `[TEST] Page Title` +-- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +-- **Avoid real names**: Don't use "Workshop" or "Training" +-- **Be descriptive**: `[TEST] Event with All Fields` +- +-### Example feature file +- +-```gherkin +-Feature: Homepage +- +- As a site visitor +- I want to access the homepage +- So that I can view the main landing page and navigate the site +- +- Scenario: View homepage content +- Given I am on the homepage +- Then I should see "[TEST] Welcome Message" +- And I should see "About Us" in the "navigation" region +-``` +- +-### Content type testing process +- +-When creating comprehensive tests for content types: +- +-1. Analyze configuration first +- +- - Check `config/default/field.field.node.[type].*.yml` +- - Review `core.entity_view_display.node.[type].default.yml` +- - Identify visible vs hidden fields +- +-2. Create supporting entities +- +- ```gherkin +- Background: +- Given "tags" terms: +- | name | +- | [TEST] Topic 1 | +- | [TEST] Topic 2 | +- +- And the following media "image" exist: +- | name | +- | [TEST] Featured Image 1 | +- ``` +- +-3. Test all visible fields +- +- ```gherkin +- Scenario: View complete content with all fields +- Given "page" content: +- | title | body | field_tags | +- | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | +- When I visit "[TEST] Complete Page Test" +- Then I should see "[TEST] Complete Page Test" +- And I should see "[TEST] This is the body text." +- And I should see "[TEST] Topic 1" +- ``` diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/CLAUDE.md index ffcc553dd..8071a6faf 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/CLAUDE.md @@ -1,155 +1,17 @@ -@@ -8,8 +8,6 @@ - - Uses Docker for local development - - Commands are executed via 'ahoy' (task runner) - - Configuration is exported/imported via Drupal's config management --- Testing includes PHPUnit --- Testing includes Behat (BDD) - - Deployment is automated via CI/CD pipelines - - KEY CONVENTIONS: -@@ -122,19 +120,6 @@ - - ### Testing Framework - --```bash --# Run PHPUnit tests (unit/integration tests) --ahoy test-unit --``` -- --```bash --# Run Behat tests (behavioral/BDD tests) --ahoy test-bdd -- --# Run specific Behat feature --ahoy test-bdd tests/behat/features/homepage.feature --``` -- - ## Configuration Management (Critical for Drupal) - - ### Understanding Config Management -@@ -196,10 +181,6 @@ - │ └── index.php # Drupal entry point - │ - ├── tests/ --│ ├── behat/ # Behavioral tests (user scenarios) --│ │ ├── features/ # Test scenarios (.feature files) --│ │ └── behat.yml # Behat configuration --│ └── phpunit/ # Unit/integration tests - │ - └── scripts/ - ├── vortex/ # Core Vortex scripts (don't modify) -@@ -617,97 +598,6 @@ - - ## Testing Best Practices - --### Writing Behat Tests (BDD) -- --#### User Story Format (Required) -- --All Behat features MUST follow this format: -- --```gherkin --Feature: [Feature name] -- -- As a [user type] -- I want to [action/goal] -- So that [benefit/outcome] --``` -- --#### Standard User Types -- --```gherkin --As a site visitor # Anonymous users --As a site administrator # Admin users --As a content editor # Content management users --As a authenticated user # Logged-in users --``` -- --#### Test Data Conventions -- --- **Always prefix test content**: `[TEST] Page Title` --- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` --- **Avoid real names**: Don't use "Workshop" or "Training" --- **Be descriptive**: `[TEST] Event with All Fields` -- --#### Example Feature File -- --```gherkin --Feature: Homepage -- -- As a site visitor -- I want to access the homepage -- So that I can view the main landing page and navigate the site -- -- Scenario: View homepage content -- Given I am on the homepage -- Then I should see "[TEST] Welcome Message" -- And I should see "About Us" in the "navigation" region --``` -- --#### Discovering Available Step Definitions -- --```bash --# Generate step definitions reference (run once) --ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt --``` -- --Use the cached file for reference, don't regenerate unless asked. -- --### Content Type Testing Process -- --When creating comprehensive tests for content types: -- --1. **Analyze Configuration First** -- -- - Check `config/default/field.field.node.[type].*.yml` -- - Review `core.entity_view_display.node.[type].default.yml` -- - Identify visible vs hidden fields -- --1. **Create Supporting Entities** -- --```gherkin --Background: -- Given "tags" terms: -- | name | -- | [TEST] Topic 1 | -- | [TEST] Topic 2 | -- -- And the following media "image" exist: -- | name | -- | [TEST] Featured Image 1 | --``` -- --1. **Test All Visible Fields** -- --```gherkin --Scenario: View complete content with all fields -- Given "page" content: -- | title | body | field_tags | -- | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | -- When I visit "[TEST] Complete Page Test" -- Then I should see "[TEST] Complete Page Test" -- And I should see "[TEST] This is the body text." -- And I should see "[TEST] Topic 1" --``` -- - ## Debugging & Troubleshooting - - ### Development Tools -@@ -796,7 +686,7 @@ - - This project includes automated deployment via: - --- **GitHub Actions** - See `.github/workflows/` -+- **CircleCI** - See `.circleci/config.yml` - - ### Hosting Platforms - -@@ -881,7 +771,6 @@ - - Always use ahoy prefix for commands - - Never use drush php:eval directly - - Test data must use [TEST] prefix --- Behat tests need proper user story format - - The project uses Docker locally but deploys to various hosting platforms with automated CI/CD. - CLAUDE_CONTEXT_SUMMARY --> +@@ -36,16 +36,6 @@ + ahoy lint # Check code style + ahoy lint-fix # Auto-fix code style + +-# PHPUnit testing +-ahoy test # Run PHPUnit tests +-ahoy test-unit # Run PHPUnit Unit tests +-ahoy test-kernel # Run PHPUnit Kernel tests +-ahoy test-functional # Run PHPUnit Functional tests +-ahoy test -- --filters=TestClassName # Run specific PHPUnit test class +- +-# Behat testing +-ahoy test-bdd # Run Behat tests +-ahoy test-bdd -- --tags=@tagname # Run Behat tests with specific tag + ``` + + ## Critical Rules diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/docs/ci.md b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/docs/ci.md index 419d99d2b..542f58060 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/docs/ci.md +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/docs/ci.md @@ -1,31 +1,12 @@ -@@ -5,12 +5,12 @@ - Before feature changes can be merged into a shared mainline, a complete build - must run and pass all tests on CI server. +@@ -5,9 +5,9 @@ --## GitHub Actions -+## Circle CI + ## CI provider --This project uses [GitHub Actions](https://github.com/features/actions) as a --CI server: it imports production backups into fully built codebase and runs --code linting and tests. When tests pass, a deployment process is triggered for --nominated branches (usually, `main` and `develop`). -+This project uses [Circle CI](https://circleci.com/) as a CI server: it imports -+production backups into fully built codebase and runs code linting and tests. -+When tests pass, a deployment process is triggered for nominated branches -+(usually, `main` and `develop`). +-This project uses [GitHub Actions](https://github.com/features/actions). ++This project uses [CircleCI](https://circleci.com/). - Refer to https://www.vortextemplate.com/docs/continuous-integration for more - information. -@@ -22,9 +22,6 @@ +-See [GitHub Actions documentation](https://www.vortextemplate.com/docs/continuous-integration/github-actions) ++See [CircleCI documentation](https://www.vortextemplate.com/docs/continuous-integration/circleci) + for setup and configuration details. - ### SSH - --GitHub Actions does not supports shell access to the build, but there is an --action provided withing the `build` job that allows you to run a build with SSH --support. -- --Use "Run workflow" button in GitHub Actions UI to start build with SSH support --that will be available for 120 minutes after the build is finished. -+Circle CI supports shell access to the build for 120 minutes after the build is -+finished when the build is started with SSH support. Use "Rerun job with SSH" -+button in Circle CI UI to start build with SSH support. + ## Project-specific configuration diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/docs/faqs.md b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/docs/faqs.md deleted file mode 100644 index e445b0f50..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/docs/faqs.md +++ /dev/null @@ -1,29 +0,0 @@ -@@ -58,16 +58,6 @@ - - See https://www.vortextemplate.com/docs/tools/xdebug for more details. - --## How to use Xdebug on Behat scripts? -- --1. Enable debugging: `ahoy debug` --2. Enter CLI container: `ahoy cli` --3. Run Behat tests: -- --```bash --vendor/bin/behat --xdebug path/to/test.feature --``` -- - ## What should I do to switch to a "clean" branch environment? - - Provided that your stack is already running: -@@ -158,11 +148,3 @@ - - The maintenance theme should be a valid Drupal theme that is already installed - and enabled on your site. -- --## Behat tests with `@javascript` tag sometimes get stuck -- --Behat tests with `@javascript` tag sometimes get stuck for about 10min then --fail. --The Chrome container randomly get stuck for an unknown reason. -- --Restart the Chrome container: `docker compose restart chrome` diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/docs/testing.md b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/docs/testing.md new file mode 100644 index 000000000..712b28ae7 --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_groups_no_be_tests_circleci/docs/testing.md @@ -0,0 +1,227 @@ +@@ -2,226 +2,3 @@ + + This document describes **what** testing conventions and agreements apply to + this project. +- +-## PHPUnit conventions +- +-Unit, Kernel, Functional tests. +- +-See [documentation](https://www.vortextemplate.com/docs/development/phpunit) +-on how to run tests, configure environment variables and code coverage, and use +-test reports in continuous integration pipeline. +- +-### Test class structure +- +-All PHPUnit tests must follow this structure: +- +-```php +-assertEquals('expected', $result); +- } +- +-} +-``` +- +-### Base test classes +- +-- **Unit** - `Drupal\Tests\UnitTestCase` - Testing isolated PHP classes +-- **Kernel** - `Drupal\KernelTests\KernelTestBase` - Testing with database/services +-- **Functional** - `Drupal\Tests\BrowserTestBase` - Testing with full browser +- +-### Test data conventions +- +-- **Always prefix test content**: `[TEST] Node Title` +-- **Use data providers**: For testing multiple input/output combinations +- - Must be a public static method +- - Must follow naming convention `dataProvider` +- - Must be placed after the test method it provides data for. +-- **Use unique identifiers**: Include test class or method name in test data +- +-### Data providers +- +-Always use data providers for testing multiple input/output combinations: +- +-```php +-/** +- * Test my function with various inputs. +- * +- * @dataProvider dataProviderMyFunction +- */ +-public function testMyFunction(string $input, string $expected): void { +- $this->assertEquals($expected, my_function($input)); +-} +- +-/** +- * Data provider for testMyFunction. +- */ +-public static function dataProviderMyFunction(): array { +- return [ +- 'empty string' => ['', ''], +- 'simple string' => ['hello', 'HELLO'], +- 'with numbers' => ['test123', 'TEST123'], +- ]; +-} +-``` +- +-### Testing services (Kernel tests) +- +-For Kernel tests that need Drupal services: +- +-```php +-installEntitySchema('node'); +- $this->installEntitySchema('user'); +- $this->myService = $this->container->get('my_module.my_service'); +- } +- +- /** +- * Test service method. +- */ +- public function testServiceMethod(): void { +- $result = $this->myService->doSomething(); +- $this->assertNotNull($result); +- } +- +-} +-``` +- +-## Behat conventions +- +-BDD end-to-end tests. +- +-See [documentation](https://www.vortextemplate.com/docs/development/behat) +-on how to run Behat tests, configure environment variables, and use test reports +-in continuous integration pipeline. +- +-### User story format +- +-All Behat features must follow this format: +- +-```gherkin +-Feature: [Feature name] +- +- As a [user type] +- I want to [action/goal] +- So that [benefit/outcome] +-``` +- +-### Standard user types +- +-Use these consistent user type descriptions: +- +-```gherkin +-As a site visitor # Anonymous users +-As a site administrator # Admin users +-As a content editor # Content management users +-As a authenticated user # Logged-in users +-``` +- +-### Test data conventions +- +-- **Always prefix test content**: `[TEST] Page Title` +-- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +-- **Avoid real names**: Don't use "Workshop" or "Training" +-- **Be descriptive**: `[TEST] Event with All Fields` +- +-### Example feature file +- +-```gherkin +-Feature: Homepage +- +- As a site visitor +- I want to access the homepage +- So that I can view the main landing page and navigate the site +- +- Scenario: View homepage content +- Given I am on the homepage +- Then I should see "[TEST] Welcome Message" +- And I should see "About Us" in the "navigation" region +-``` +- +-### Content type testing process +- +-When creating comprehensive tests for content types: +- +-1. Analyze configuration first +- +- - Check `config/default/field.field.node.[type].*.yml` +- - Review `core.entity_view_display.node.[type].default.yml` +- - Identify visible vs hidden fields +- +-2. Create supporting entities +- +- ```gherkin +- Background: +- Given "tags" terms: +- | name | +- | [TEST] Topic 1 | +- | [TEST] Topic 2 | +- +- And the following media "image" exist: +- | name | +- | [TEST] Featured Image 1 | +- ``` +- +-3. Test all visible fields +- +- ```gherkin +- Scenario: View complete content with all fields +- Given "page" content: +- | title | body | field_tags | +- | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | +- When I visit "[TEST] Complete Page Test" +- Then I should see "[TEST] Complete Page Test" +- And I should see "[TEST] This is the body text." +- And I should see "[TEST] Topic 1" +- ``` diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat/CLAUDE.md index 5c254711f..1fe81f60c 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat/CLAUDE.md @@ -1,139 +1,10 @@ -@@ -9,7 +9,6 @@ - - Commands are executed via 'ahoy' (task runner) - - Configuration is exported/imported via Drupal's config management - - Testing includes PHPUnit --- Testing includes Behat (BDD) - - Deployment is automated via CI/CD pipelines +@@ -43,9 +43,6 @@ + ahoy test-functional # Run PHPUnit Functional tests + ahoy test -- --filters=TestClassName # Run specific PHPUnit test class - KEY CONVENTIONS: -@@ -127,14 +126,6 @@ - ahoy test-unit +-# Behat testing +-ahoy test-bdd # Run Behat tests +-ahoy test-bdd -- --tags=@tagname # Run Behat tests with specific tag ``` --```bash --# Run Behat tests (behavioral/BDD tests) --ahoy test-bdd -- --# Run specific Behat feature --ahoy test-bdd tests/behat/features/homepage.feature --``` -- - ## Configuration Management (Critical for Drupal) - - ### Understanding Config Management -@@ -196,9 +187,6 @@ - │ └── index.php # Drupal entry point - │ - ├── tests/ --│ ├── behat/ # Behavioral tests (user scenarios) --│ │ ├── features/ # Test scenarios (.feature files) --│ │ └── behat.yml # Behat configuration - │ └── phpunit/ # Unit/integration tests - │ - └── scripts/ -@@ -617,97 +605,6 @@ - - ## Testing Best Practices - --### Writing Behat Tests (BDD) -- --#### User Story Format (Required) -- --All Behat features MUST follow this format: -- --```gherkin --Feature: [Feature name] -- -- As a [user type] -- I want to [action/goal] -- So that [benefit/outcome] --``` -- --#### Standard User Types -- --```gherkin --As a site visitor # Anonymous users --As a site administrator # Admin users --As a content editor # Content management users --As a authenticated user # Logged-in users --``` -- --#### Test Data Conventions -- --- **Always prefix test content**: `[TEST] Page Title` --- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` --- **Avoid real names**: Don't use "Workshop" or "Training" --- **Be descriptive**: `[TEST] Event with All Fields` -- --#### Example Feature File -- --```gherkin --Feature: Homepage -- -- As a site visitor -- I want to access the homepage -- So that I can view the main landing page and navigate the site -- -- Scenario: View homepage content -- Given I am on the homepage -- Then I should see "[TEST] Welcome Message" -- And I should see "About Us" in the "navigation" region --``` -- --#### Discovering Available Step Definitions -- --```bash --# Generate step definitions reference (run once) --ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt --``` -- --Use the cached file for reference, don't regenerate unless asked. -- --### Content Type Testing Process -- --When creating comprehensive tests for content types: -- --1. **Analyze Configuration First** -- -- - Check `config/default/field.field.node.[type].*.yml` -- - Review `core.entity_view_display.node.[type].default.yml` -- - Identify visible vs hidden fields -- --1. **Create Supporting Entities** -- --```gherkin --Background: -- Given "tags" terms: -- | name | -- | [TEST] Topic 1 | -- | [TEST] Topic 2 | -- -- And the following media "image" exist: -- | name | -- | [TEST] Featured Image 1 | --``` -- --1. **Test All Visible Fields** -- --```gherkin --Scenario: View complete content with all fields -- Given "page" content: -- | title | body | field_tags | -- | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | -- When I visit "[TEST] Complete Page Test" -- Then I should see "[TEST] Complete Page Test" -- And I should see "[TEST] This is the body text." -- And I should see "[TEST] Topic 1" --``` -- - ## Debugging & Troubleshooting - - ### Development Tools -@@ -881,7 +778,6 @@ - - Always use ahoy prefix for commands - - Never use drush php:eval directly - - Test data must use [TEST] prefix --- Behat tests need proper user story format - - The project uses Docker locally but deploys to various hosting platforms with automated CI/CD. - CLAUDE_CONTEXT_SUMMARY --> + ## Critical Rules diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat/docs/faqs.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat/docs/faqs.md deleted file mode 100644 index e445b0f50..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat/docs/faqs.md +++ /dev/null @@ -1,29 +0,0 @@ -@@ -58,16 +58,6 @@ - - See https://www.vortextemplate.com/docs/tools/xdebug for more details. - --## How to use Xdebug on Behat scripts? -- --1. Enable debugging: `ahoy debug` --2. Enter CLI container: `ahoy cli` --3. Run Behat tests: -- --```bash --vendor/bin/behat --xdebug path/to/test.feature --``` -- - ## What should I do to switch to a "clean" branch environment? - - Provided that your stack is already running: -@@ -158,11 +148,3 @@ - - The maintenance theme should be a valid Drupal theme that is already installed - and enabled on your site. -- --## Behat tests with `@javascript` tag sometimes get stuck -- --Behat tests with `@javascript` tag sometimes get stuck for about 10min then --fail. --The Chrome container randomly get stuck for an unknown reason. -- --Restart the Chrome container: `docker compose restart chrome` diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat/docs/testing.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat/docs/testing.md new file mode 100644 index 000000000..c3dc6669b --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat/docs/testing.md @@ -0,0 +1,94 @@ +@@ -135,93 +135,3 @@ + + } + ``` +- +-## Behat conventions +- +-BDD end-to-end tests. +- +-See [documentation](https://www.vortextemplate.com/docs/development/behat) +-on how to run Behat tests, configure environment variables, and use test reports +-in continuous integration pipeline. +- +-### User story format +- +-All Behat features must follow this format: +- +-```gherkin +-Feature: [Feature name] +- +- As a [user type] +- I want to [action/goal] +- So that [benefit/outcome] +-``` +- +-### Standard user types +- +-Use these consistent user type descriptions: +- +-```gherkin +-As a site visitor # Anonymous users +-As a site administrator # Admin users +-As a content editor # Content management users +-As a authenticated user # Logged-in users +-``` +- +-### Test data conventions +- +-- **Always prefix test content**: `[TEST] Page Title` +-- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +-- **Avoid real names**: Don't use "Workshop" or "Training" +-- **Be descriptive**: `[TEST] Event with All Fields` +- +-### Example feature file +- +-```gherkin +-Feature: Homepage +- +- As a site visitor +- I want to access the homepage +- So that I can view the main landing page and navigate the site +- +- Scenario: View homepage content +- Given I am on the homepage +- Then I should see "[TEST] Welcome Message" +- And I should see "About Us" in the "navigation" region +-``` +- +-### Content type testing process +- +-When creating comprehensive tests for content types: +- +-1. Analyze configuration first +- +- - Check `config/default/field.field.node.[type].*.yml` +- - Review `core.entity_view_display.node.[type].default.yml` +- - Identify visible vs hidden fields +- +-2. Create supporting entities +- +- ```gherkin +- Background: +- Given "tags" terms: +- | name | +- | [TEST] Topic 1 | +- | [TEST] Topic 2 | +- +- And the following media "image" exist: +- | name | +- | [TEST] Featured Image 1 | +- ``` +- +-3. Test all visible fields +- +- ```gherkin +- Scenario: View complete content with all fields +- Given "page" content: +- | title | body | field_tags | +- | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | +- When I visit "[TEST] Complete Page Test" +- Then I should see "[TEST] Complete Page Test" +- And I should see "[TEST] This is the body text." +- And I should see "[TEST] Topic 1" +- ``` diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/CLAUDE.md index 27908b8a0..1fe81f60c 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/CLAUDE.md @@ -1,148 +1,10 @@ -@@ -9,7 +9,6 @@ - - Commands are executed via 'ahoy' (task runner) - - Configuration is exported/imported via Drupal's config management - - Testing includes PHPUnit --- Testing includes Behat (BDD) - - Deployment is automated via CI/CD pipelines +@@ -43,9 +43,6 @@ + ahoy test-functional # Run PHPUnit Functional tests + ahoy test -- --filters=TestClassName # Run specific PHPUnit test class - KEY CONVENTIONS: -@@ -127,14 +126,6 @@ - ahoy test-unit +-# Behat testing +-ahoy test-bdd # Run Behat tests +-ahoy test-bdd -- --tags=@tagname # Run Behat tests with specific tag ``` --```bash --# Run Behat tests (behavioral/BDD tests) --ahoy test-bdd -- --# Run specific Behat feature --ahoy test-bdd tests/behat/features/homepage.feature --``` -- - ## Configuration Management (Critical for Drupal) - - ### Understanding Config Management -@@ -196,9 +187,6 @@ - │ └── index.php # Drupal entry point - │ - ├── tests/ --│ ├── behat/ # Behavioral tests (user scenarios) --│ │ ├── features/ # Test scenarios (.feature files) --│ │ └── behat.yml # Behat configuration - │ └── phpunit/ # Unit/integration tests - │ - └── scripts/ -@@ -617,97 +605,6 @@ - - ## Testing Best Practices - --### Writing Behat Tests (BDD) -- --#### User Story Format (Required) -- --All Behat features MUST follow this format: -- --```gherkin --Feature: [Feature name] -- -- As a [user type] -- I want to [action/goal] -- So that [benefit/outcome] --``` -- --#### Standard User Types -- --```gherkin --As a site visitor # Anonymous users --As a site administrator # Admin users --As a content editor # Content management users --As a authenticated user # Logged-in users --``` -- --#### Test Data Conventions -- --- **Always prefix test content**: `[TEST] Page Title` --- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` --- **Avoid real names**: Don't use "Workshop" or "Training" --- **Be descriptive**: `[TEST] Event with All Fields` -- --#### Example Feature File -- --```gherkin --Feature: Homepage -- -- As a site visitor -- I want to access the homepage -- So that I can view the main landing page and navigate the site -- -- Scenario: View homepage content -- Given I am on the homepage -- Then I should see "[TEST] Welcome Message" -- And I should see "About Us" in the "navigation" region --``` -- --#### Discovering Available Step Definitions -- --```bash --# Generate step definitions reference (run once) --ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt --``` -- --Use the cached file for reference, don't regenerate unless asked. -- --### Content Type Testing Process -- --When creating comprehensive tests for content types: -- --1. **Analyze Configuration First** -- -- - Check `config/default/field.field.node.[type].*.yml` -- - Review `core.entity_view_display.node.[type].default.yml` -- - Identify visible vs hidden fields -- --1. **Create Supporting Entities** -- --```gherkin --Background: -- Given "tags" terms: -- | name | -- | [TEST] Topic 1 | -- | [TEST] Topic 2 | -- -- And the following media "image" exist: -- | name | -- | [TEST] Featured Image 1 | --``` -- --1. **Test All Visible Fields** -- --```gherkin --Scenario: View complete content with all fields -- Given "page" content: -- | title | body | field_tags | -- | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | -- When I visit "[TEST] Complete Page Test" -- Then I should see "[TEST] Complete Page Test" -- And I should see "[TEST] This is the body text." -- And I should see "[TEST] Topic 1" --``` -- - ## Debugging & Troubleshooting - - ### Development Tools -@@ -796,7 +693,7 @@ - - This project includes automated deployment via: - --- **GitHub Actions** - See `.github/workflows/` -+- **CircleCI** - See `.circleci/config.yml` - - ### Hosting Platforms - -@@ -881,7 +778,6 @@ - - Always use ahoy prefix for commands - - Never use drush php:eval directly - - Test data must use [TEST] prefix --- Behat tests need proper user story format - - The project uses Docker locally but deploys to various hosting platforms with automated CI/CD. - CLAUDE_CONTEXT_SUMMARY --> + ## Critical Rules diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/docs/ci.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/docs/ci.md index 419d99d2b..542f58060 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/docs/ci.md +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/docs/ci.md @@ -1,31 +1,12 @@ -@@ -5,12 +5,12 @@ - Before feature changes can be merged into a shared mainline, a complete build - must run and pass all tests on CI server. +@@ -5,9 +5,9 @@ --## GitHub Actions -+## Circle CI + ## CI provider --This project uses [GitHub Actions](https://github.com/features/actions) as a --CI server: it imports production backups into fully built codebase and runs --code linting and tests. When tests pass, a deployment process is triggered for --nominated branches (usually, `main` and `develop`). -+This project uses [Circle CI](https://circleci.com/) as a CI server: it imports -+production backups into fully built codebase and runs code linting and tests. -+When tests pass, a deployment process is triggered for nominated branches -+(usually, `main` and `develop`). +-This project uses [GitHub Actions](https://github.com/features/actions). ++This project uses [CircleCI](https://circleci.com/). - Refer to https://www.vortextemplate.com/docs/continuous-integration for more - information. -@@ -22,9 +22,6 @@ +-See [GitHub Actions documentation](https://www.vortextemplate.com/docs/continuous-integration/github-actions) ++See [CircleCI documentation](https://www.vortextemplate.com/docs/continuous-integration/circleci) + for setup and configuration details. - ### SSH - --GitHub Actions does not supports shell access to the build, but there is an --action provided withing the `build` job that allows you to run a build with SSH --support. -- --Use "Run workflow" button in GitHub Actions UI to start build with SSH support --that will be available for 120 minutes after the build is finished. -+Circle CI supports shell access to the build for 120 minutes after the build is -+finished when the build is started with SSH support. Use "Rerun job with SSH" -+button in Circle CI UI to start build with SSH support. + ## Project-specific configuration diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/docs/faqs.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/docs/faqs.md deleted file mode 100644 index e445b0f50..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/docs/faqs.md +++ /dev/null @@ -1,29 +0,0 @@ -@@ -58,16 +58,6 @@ - - See https://www.vortextemplate.com/docs/tools/xdebug for more details. - --## How to use Xdebug on Behat scripts? -- --1. Enable debugging: `ahoy debug` --2. Enter CLI container: `ahoy cli` --3. Run Behat tests: -- --```bash --vendor/bin/behat --xdebug path/to/test.feature --``` -- - ## What should I do to switch to a "clean" branch environment? - - Provided that your stack is already running: -@@ -158,11 +148,3 @@ - - The maintenance theme should be a valid Drupal theme that is already installed - and enabled on your site. -- --## Behat tests with `@javascript` tag sometimes get stuck -- --Behat tests with `@javascript` tag sometimes get stuck for about 10min then --fail. --The Chrome container randomly get stuck for an unknown reason. -- --Restart the Chrome container: `docker compose restart chrome` diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/docs/testing.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/docs/testing.md new file mode 100644 index 000000000..c3dc6669b --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_behat_circleci/docs/testing.md @@ -0,0 +1,94 @@ +@@ -135,93 +135,3 @@ + + } + ``` +- +-## Behat conventions +- +-BDD end-to-end tests. +- +-See [documentation](https://www.vortextemplate.com/docs/development/behat) +-on how to run Behat tests, configure environment variables, and use test reports +-in continuous integration pipeline. +- +-### User story format +- +-All Behat features must follow this format: +- +-```gherkin +-Feature: [Feature name] +- +- As a [user type] +- I want to [action/goal] +- So that [benefit/outcome] +-``` +- +-### Standard user types +- +-Use these consistent user type descriptions: +- +-```gherkin +-As a site visitor # Anonymous users +-As a site administrator # Admin users +-As a content editor # Content management users +-As a authenticated user # Logged-in users +-``` +- +-### Test data conventions +- +-- **Always prefix test content**: `[TEST] Page Title` +-- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +-- **Avoid real names**: Don't use "Workshop" or "Training" +-- **Be descriptive**: `[TEST] Event with All Fields` +- +-### Example feature file +- +-```gherkin +-Feature: Homepage +- +- As a site visitor +- I want to access the homepage +- So that I can view the main landing page and navigate the site +- +- Scenario: View homepage content +- Given I am on the homepage +- Then I should see "[TEST] Welcome Message" +- And I should see "About Us" in the "navigation" region +-``` +- +-### Content type testing process +- +-When creating comprehensive tests for content types: +- +-1. Analyze configuration first +- +- - Check `config/default/field.field.node.[type].*.yml` +- - Review `core.entity_view_display.node.[type].default.yml` +- - Identify visible vs hidden fields +- +-2. Create supporting entities +- +- ```gherkin +- Background: +- Given "tags" terms: +- | name | +- | [TEST] Topic 1 | +- | [TEST] Topic 2 | +- +- And the following media "image" exist: +- | name | +- | [TEST] Featured Image 1 | +- ``` +- +-3. Test all visible fields +- +- ```gherkin +- Scenario: View complete content with all fields +- Given "page" content: +- | title | body | field_tags | +- | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | +- When I visit "[TEST] Complete Page Test" +- Then I should see "[TEST] Complete Page Test" +- And I should see "[TEST] This is the body text." +- And I should see "[TEST] Topic 1" +- ``` diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpcs_circleci/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpcs_circleci/CLAUDE.md deleted file mode 100644 index 109f9b3b5..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpcs_circleci/CLAUDE.md +++ /dev/null @@ -1,9 +0,0 @@ -@@ -796,7 +796,7 @@ - - This project includes automated deployment via: - --- **GitHub Actions** - See `.github/workflows/` -+- **CircleCI** - See `.circleci/config.yml` - - ### Hosting Platforms - diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpcs_circleci/docs/ci.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpcs_circleci/docs/ci.md index 419d99d2b..542f58060 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpcs_circleci/docs/ci.md +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpcs_circleci/docs/ci.md @@ -1,31 +1,12 @@ -@@ -5,12 +5,12 @@ - Before feature changes can be merged into a shared mainline, a complete build - must run and pass all tests on CI server. +@@ -5,9 +5,9 @@ --## GitHub Actions -+## Circle CI + ## CI provider --This project uses [GitHub Actions](https://github.com/features/actions) as a --CI server: it imports production backups into fully built codebase and runs --code linting and tests. When tests pass, a deployment process is triggered for --nominated branches (usually, `main` and `develop`). -+This project uses [Circle CI](https://circleci.com/) as a CI server: it imports -+production backups into fully built codebase and runs code linting and tests. -+When tests pass, a deployment process is triggered for nominated branches -+(usually, `main` and `develop`). +-This project uses [GitHub Actions](https://github.com/features/actions). ++This project uses [CircleCI](https://circleci.com/). - Refer to https://www.vortextemplate.com/docs/continuous-integration for more - information. -@@ -22,9 +22,6 @@ +-See [GitHub Actions documentation](https://www.vortextemplate.com/docs/continuous-integration/github-actions) ++See [CircleCI documentation](https://www.vortextemplate.com/docs/continuous-integration/circleci) + for setup and configuration details. - ### SSH - --GitHub Actions does not supports shell access to the build, but there is an --action provided withing the `build` job that allows you to run a build with SSH --support. -- --Use "Run workflow" button in GitHub Actions UI to start build with SSH support --that will be available for 120 minutes after the build is finished. -+Circle CI supports shell access to the build for 120 minutes after the build is -+finished when the build is started with SSH support. Use "Rerun job with SSH" -+button in Circle CI UI to start build with SSH support. + ## Project-specific configuration diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpmd_circleci/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpmd_circleci/CLAUDE.md deleted file mode 100644 index 109f9b3b5..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpmd_circleci/CLAUDE.md +++ /dev/null @@ -1,9 +0,0 @@ -@@ -796,7 +796,7 @@ - - This project includes automated deployment via: - --- **GitHub Actions** - See `.github/workflows/` -+- **CircleCI** - See `.circleci/config.yml` - - ### Hosting Platforms - diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpmd_circleci/docs/ci.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpmd_circleci/docs/ci.md index 419d99d2b..542f58060 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpmd_circleci/docs/ci.md +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpmd_circleci/docs/ci.md @@ -1,31 +1,12 @@ -@@ -5,12 +5,12 @@ - Before feature changes can be merged into a shared mainline, a complete build - must run and pass all tests on CI server. +@@ -5,9 +5,9 @@ --## GitHub Actions -+## Circle CI + ## CI provider --This project uses [GitHub Actions](https://github.com/features/actions) as a --CI server: it imports production backups into fully built codebase and runs --code linting and tests. When tests pass, a deployment process is triggered for --nominated branches (usually, `main` and `develop`). -+This project uses [Circle CI](https://circleci.com/) as a CI server: it imports -+production backups into fully built codebase and runs code linting and tests. -+When tests pass, a deployment process is triggered for nominated branches -+(usually, `main` and `develop`). +-This project uses [GitHub Actions](https://github.com/features/actions). ++This project uses [CircleCI](https://circleci.com/). - Refer to https://www.vortextemplate.com/docs/continuous-integration for more - information. -@@ -22,9 +22,6 @@ +-See [GitHub Actions documentation](https://www.vortextemplate.com/docs/continuous-integration/github-actions) ++See [CircleCI documentation](https://www.vortextemplate.com/docs/continuous-integration/circleci) + for setup and configuration details. - ### SSH - --GitHub Actions does not supports shell access to the build, but there is an --action provided withing the `build` job that allows you to run a build with SSH --support. -- --Use "Run workflow" button in GitHub Actions UI to start build with SSH support --that will be available for 120 minutes after the build is finished. -+Circle CI supports shell access to the build for 120 minutes after the build is -+finished when the build is started with SSH support. Use "Rerun job with SSH" -+button in Circle CI UI to start build with SSH support. + ## Project-specific configuration diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpstan_circleci/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpstan_circleci/CLAUDE.md deleted file mode 100644 index 109f9b3b5..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpstan_circleci/CLAUDE.md +++ /dev/null @@ -1,9 +0,0 @@ -@@ -796,7 +796,7 @@ - - This project includes automated deployment via: - --- **GitHub Actions** - See `.github/workflows/` -+- **CircleCI** - See `.circleci/config.yml` - - ### Hosting Platforms - diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpstan_circleci/docs/ci.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpstan_circleci/docs/ci.md index 419d99d2b..542f58060 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpstan_circleci/docs/ci.md +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpstan_circleci/docs/ci.md @@ -1,31 +1,12 @@ -@@ -5,12 +5,12 @@ - Before feature changes can be merged into a shared mainline, a complete build - must run and pass all tests on CI server. +@@ -5,9 +5,9 @@ --## GitHub Actions -+## Circle CI + ## CI provider --This project uses [GitHub Actions](https://github.com/features/actions) as a --CI server: it imports production backups into fully built codebase and runs --code linting and tests. When tests pass, a deployment process is triggered for --nominated branches (usually, `main` and `develop`). -+This project uses [Circle CI](https://circleci.com/) as a CI server: it imports -+production backups into fully built codebase and runs code linting and tests. -+When tests pass, a deployment process is triggered for nominated branches -+(usually, `main` and `develop`). +-This project uses [GitHub Actions](https://github.com/features/actions). ++This project uses [CircleCI](https://circleci.com/). - Refer to https://www.vortextemplate.com/docs/continuous-integration for more - information. -@@ -22,9 +22,6 @@ +-See [GitHub Actions documentation](https://www.vortextemplate.com/docs/continuous-integration/github-actions) ++See [CircleCI documentation](https://www.vortextemplate.com/docs/continuous-integration/circleci) + for setup and configuration details. - ### SSH - --GitHub Actions does not supports shell access to the build, but there is an --action provided withing the `build` job that allows you to run a build with SSH --support. -- --Use "Run workflow" button in GitHub Actions UI to start build with SSH support --that will be available for 120 minutes after the build is finished. -+Circle CI supports shell access to the build for 120 minutes after the build is -+finished when the build is started with SSH support. Use "Rerun job with SSH" -+button in Circle CI UI to start build with SSH support. + ## Project-specific configuration diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit/CLAUDE.md index 4d4f81ca9..18f274865 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit/CLAUDE.md @@ -1,28 +1,14 @@ -@@ -8,7 +8,6 @@ - - Uses Docker for local development - - Commands are executed via 'ahoy' (task runner) - - Configuration is exported/imported via Drupal's config management --- Testing includes PHPUnit - - Testing includes Behat (BDD) - - Deployment is automated via CI/CD pipelines +@@ -36,13 +36,6 @@ + ahoy lint # Check code style + ahoy lint-fix # Auto-fix code style -@@ -123,11 +122,6 @@ - ### Testing Framework - - ```bash --# Run PHPUnit tests (unit/integration tests) --ahoy test-unit --``` +-# PHPUnit testing +-ahoy test # Run PHPUnit tests +-ahoy test-unit # Run PHPUnit Unit tests +-ahoy test-kernel # Run PHPUnit Kernel tests +-ahoy test-functional # Run PHPUnit Functional tests +-ahoy test -- --filters=TestClassName # Run specific PHPUnit test class - --```bash - # Run Behat tests (behavioral/BDD tests) - ahoy test-bdd - -@@ -199,7 +193,6 @@ - │ ├── behat/ # Behavioral tests (user scenarios) - │ │ ├── features/ # Test scenarios (.feature files) - │ │ └── behat.yml # Behat configuration --│ └── phpunit/ # Unit/integration tests - │ - └── scripts/ - ├── vortex/ # Core Vortex scripts (don't modify) + # Behat testing + ahoy test-bdd # Run Behat tests + ahoy test-bdd -- --tags=@tagname # Run Behat tests with specific tag diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit/docs/testing.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit/docs/testing.md new file mode 100644 index 000000000..57672021a --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit/docs/testing.md @@ -0,0 +1,140 @@ +@@ -3,139 +3,6 @@ + This document describes **what** testing conventions and agreements apply to + this project. + +-## PHPUnit conventions +- +-Unit, Kernel, Functional tests. +- +-See [documentation](https://www.vortextemplate.com/docs/development/phpunit) +-on how to run tests, configure environment variables and code coverage, and use +-test reports in continuous integration pipeline. +- +-### Test class structure +- +-All PHPUnit tests must follow this structure: +- +-```php +-assertEquals('expected', $result); +- } +- +-} +-``` +- +-### Base test classes +- +-- **Unit** - `Drupal\Tests\UnitTestCase` - Testing isolated PHP classes +-- **Kernel** - `Drupal\KernelTests\KernelTestBase` - Testing with database/services +-- **Functional** - `Drupal\Tests\BrowserTestBase` - Testing with full browser +- +-### Test data conventions +- +-- **Always prefix test content**: `[TEST] Node Title` +-- **Use data providers**: For testing multiple input/output combinations +- - Must be a public static method +- - Must follow naming convention `dataProvider` +- - Must be placed after the test method it provides data for. +-- **Use unique identifiers**: Include test class or method name in test data +- +-### Data providers +- +-Always use data providers for testing multiple input/output combinations: +- +-```php +-/** +- * Test my function with various inputs. +- * +- * @dataProvider dataProviderMyFunction +- */ +-public function testMyFunction(string $input, string $expected): void { +- $this->assertEquals($expected, my_function($input)); +-} +- +-/** +- * Data provider for testMyFunction. +- */ +-public static function dataProviderMyFunction(): array { +- return [ +- 'empty string' => ['', ''], +- 'simple string' => ['hello', 'HELLO'], +- 'with numbers' => ['test123', 'TEST123'], +- ]; +-} +-``` +- +-### Testing services (Kernel tests) +- +-For Kernel tests that need Drupal services: +- +-```php +-installEntitySchema('node'); +- $this->installEntitySchema('user'); +- $this->myService = $this->container->get('my_module.my_service'); +- } +- +- /** +- * Test service method. +- */ +- public function testServiceMethod(): void { +- $result = $this->myService->doSomething(); +- $this->assertNotNull($result); +- } +- +-} +-``` +- + ## Behat conventions + + BDD end-to-end tests. diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/CLAUDE.md index f37f4825b..18f274865 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/CLAUDE.md @@ -1,37 +1,14 @@ -@@ -8,7 +8,6 @@ - - Uses Docker for local development - - Commands are executed via 'ahoy' (task runner) - - Configuration is exported/imported via Drupal's config management --- Testing includes PHPUnit - - Testing includes Behat (BDD) - - Deployment is automated via CI/CD pipelines - -@@ -123,11 +122,6 @@ - ### Testing Framework - - ```bash --# Run PHPUnit tests (unit/integration tests) --ahoy test-unit --``` +@@ -36,13 +36,6 @@ + ahoy lint # Check code style + ahoy lint-fix # Auto-fix code style + +-# PHPUnit testing +-ahoy test # Run PHPUnit tests +-ahoy test-unit # Run PHPUnit Unit tests +-ahoy test-kernel # Run PHPUnit Kernel tests +-ahoy test-functional # Run PHPUnit Functional tests +-ahoy test -- --filters=TestClassName # Run specific PHPUnit test class - --```bash - # Run Behat tests (behavioral/BDD tests) - ahoy test-bdd - -@@ -199,7 +193,6 @@ - │ ├── behat/ # Behavioral tests (user scenarios) - │ │ ├── features/ # Test scenarios (.feature files) - │ │ └── behat.yml # Behat configuration --│ └── phpunit/ # Unit/integration tests - │ - └── scripts/ - ├── vortex/ # Core Vortex scripts (don't modify) -@@ -796,7 +789,7 @@ - - This project includes automated deployment via: - --- **GitHub Actions** - See `.github/workflows/` -+- **CircleCI** - See `.circleci/config.yml` - - ### Hosting Platforms - + # Behat testing + ahoy test-bdd # Run Behat tests + ahoy test-bdd -- --tags=@tagname # Run Behat tests with specific tag diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/docs/ci.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/docs/ci.md index 419d99d2b..542f58060 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/docs/ci.md +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/docs/ci.md @@ -1,31 +1,12 @@ -@@ -5,12 +5,12 @@ - Before feature changes can be merged into a shared mainline, a complete build - must run and pass all tests on CI server. +@@ -5,9 +5,9 @@ --## GitHub Actions -+## Circle CI + ## CI provider --This project uses [GitHub Actions](https://github.com/features/actions) as a --CI server: it imports production backups into fully built codebase and runs --code linting and tests. When tests pass, a deployment process is triggered for --nominated branches (usually, `main` and `develop`). -+This project uses [Circle CI](https://circleci.com/) as a CI server: it imports -+production backups into fully built codebase and runs code linting and tests. -+When tests pass, a deployment process is triggered for nominated branches -+(usually, `main` and `develop`). +-This project uses [GitHub Actions](https://github.com/features/actions). ++This project uses [CircleCI](https://circleci.com/). - Refer to https://www.vortextemplate.com/docs/continuous-integration for more - information. -@@ -22,9 +22,6 @@ +-See [GitHub Actions documentation](https://www.vortextemplate.com/docs/continuous-integration/github-actions) ++See [CircleCI documentation](https://www.vortextemplate.com/docs/continuous-integration/circleci) + for setup and configuration details. - ### SSH - --GitHub Actions does not supports shell access to the build, but there is an --action provided withing the `build` job that allows you to run a build with SSH --support. -- --Use "Run workflow" button in GitHub Actions UI to start build with SSH support --that will be available for 120 minutes after the build is finished. -+Circle CI supports shell access to the build for 120 minutes after the build is -+finished when the build is started with SSH support. Use "Rerun job with SSH" -+button in Circle CI UI to start build with SSH support. + ## Project-specific configuration diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/docs/testing.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/docs/testing.md new file mode 100644 index 000000000..57672021a --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_phpunit_circleci/docs/testing.md @@ -0,0 +1,140 @@ +@@ -3,139 +3,6 @@ + This document describes **what** testing conventions and agreements apply to + this project. + +-## PHPUnit conventions +- +-Unit, Kernel, Functional tests. +- +-See [documentation](https://www.vortextemplate.com/docs/development/phpunit) +-on how to run tests, configure environment variables and code coverage, and use +-test reports in continuous integration pipeline. +- +-### Test class structure +- +-All PHPUnit tests must follow this structure: +- +-```php +-assertEquals('expected', $result); +- } +- +-} +-``` +- +-### Base test classes +- +-- **Unit** - `Drupal\Tests\UnitTestCase` - Testing isolated PHP classes +-- **Kernel** - `Drupal\KernelTests\KernelTestBase` - Testing with database/services +-- **Functional** - `Drupal\Tests\BrowserTestBase` - Testing with full browser +- +-### Test data conventions +- +-- **Always prefix test content**: `[TEST] Node Title` +-- **Use data providers**: For testing multiple input/output combinations +- - Must be a public static method +- - Must follow naming convention `dataProvider` +- - Must be placed after the test method it provides data for. +-- **Use unique identifiers**: Include test class or method name in test data +- +-### Data providers +- +-Always use data providers for testing multiple input/output combinations: +- +-```php +-/** +- * Test my function with various inputs. +- * +- * @dataProvider dataProviderMyFunction +- */ +-public function testMyFunction(string $input, string $expected): void { +- $this->assertEquals($expected, my_function($input)); +-} +- +-/** +- * Data provider for testMyFunction. +- */ +-public static function dataProviderMyFunction(): array { +- return [ +- 'empty string' => ['', ''], +- 'simple string' => ['hello', 'HELLO'], +- 'with numbers' => ['test123', 'TEST123'], +- ]; +-} +-``` +- +-### Testing services (Kernel tests) +- +-For Kernel tests that need Drupal services: +- +-```php +-installEntitySchema('node'); +- $this->installEntitySchema('user'); +- $this->myService = $this->container->get('my_module.my_service'); +- } +- +- /** +- * Test service method. +- */ +- public function testServiceMethod(): void { +- $result = $this->myService->doSomething(); +- $this->assertNotNull($result); +- } +- +-} +-``` +- + ## Behat conventions + + BDD end-to-end tests. diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_rector_circleci/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_rector_circleci/CLAUDE.md deleted file mode 100644 index 109f9b3b5..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_rector_circleci/CLAUDE.md +++ /dev/null @@ -1,9 +0,0 @@ -@@ -796,7 +796,7 @@ - - This project includes automated deployment via: - --- **GitHub Actions** - See `.github/workflows/` -+- **CircleCI** - See `.circleci/config.yml` - - ### Hosting Platforms - diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_no_rector_circleci/docs/ci.md b/.vortex/installer/tests/Fixtures/handler_process/tools_no_rector_circleci/docs/ci.md index 419d99d2b..542f58060 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_no_rector_circleci/docs/ci.md +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_no_rector_circleci/docs/ci.md @@ -1,31 +1,12 @@ -@@ -5,12 +5,12 @@ - Before feature changes can be merged into a shared mainline, a complete build - must run and pass all tests on CI server. +@@ -5,9 +5,9 @@ --## GitHub Actions -+## Circle CI + ## CI provider --This project uses [GitHub Actions](https://github.com/features/actions) as a --CI server: it imports production backups into fully built codebase and runs --code linting and tests. When tests pass, a deployment process is triggered for --nominated branches (usually, `main` and `develop`). -+This project uses [Circle CI](https://circleci.com/) as a CI server: it imports -+production backups into fully built codebase and runs code linting and tests. -+When tests pass, a deployment process is triggered for nominated branches -+(usually, `main` and `develop`). +-This project uses [GitHub Actions](https://github.com/features/actions). ++This project uses [CircleCI](https://circleci.com/). - Refer to https://www.vortextemplate.com/docs/continuous-integration for more - information. -@@ -22,9 +22,6 @@ +-See [GitHub Actions documentation](https://www.vortextemplate.com/docs/continuous-integration/github-actions) ++See [CircleCI documentation](https://www.vortextemplate.com/docs/continuous-integration/circleci) + for setup and configuration details. - ### SSH - --GitHub Actions does not supports shell access to the build, but there is an --action provided withing the `build` job that allows you to run a build with SSH --support. -- --Use "Run workflow" button in GitHub Actions UI to start build with SSH support --that will be available for 120 minutes after the build is finished. -+Circle CI supports shell access to the build for 120 minutes after the build is -+finished when the build is started with SSH support. Use "Rerun job with SSH" -+button in Circle CI UI to start build with SSH support. + ## Project-specific configuration diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_none/CLAUDE.md b/.vortex/installer/tests/Fixtures/handler_process/tools_none/CLAUDE.md index 4196e19b3..8071a6faf 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_none/CLAUDE.md +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_none/CLAUDE.md @@ -1,146 +1,17 @@ -@@ -8,8 +8,6 @@ - - Uses Docker for local development - - Commands are executed via 'ahoy' (task runner) - - Configuration is exported/imported via Drupal's config management --- Testing includes PHPUnit --- Testing includes Behat (BDD) - - Deployment is automated via CI/CD pipelines - - KEY CONVENTIONS: -@@ -122,19 +120,6 @@ - - ### Testing Framework - --```bash --# Run PHPUnit tests (unit/integration tests) --ahoy test-unit --``` -- --```bash --# Run Behat tests (behavioral/BDD tests) --ahoy test-bdd -- --# Run specific Behat feature --ahoy test-bdd tests/behat/features/homepage.feature --``` -- - ## Configuration Management (Critical for Drupal) - - ### Understanding Config Management -@@ -196,10 +181,6 @@ - │ └── index.php # Drupal entry point - │ - ├── tests/ --│ ├── behat/ # Behavioral tests (user scenarios) --│ │ ├── features/ # Test scenarios (.feature files) --│ │ └── behat.yml # Behat configuration --│ └── phpunit/ # Unit/integration tests - │ - └── scripts/ - ├── vortex/ # Core Vortex scripts (don't modify) -@@ -617,97 +598,6 @@ - - ## Testing Best Practices - --### Writing Behat Tests (BDD) -- --#### User Story Format (Required) -- --All Behat features MUST follow this format: -- --```gherkin --Feature: [Feature name] -- -- As a [user type] -- I want to [action/goal] -- So that [benefit/outcome] --``` -- --#### Standard User Types -- --```gherkin --As a site visitor # Anonymous users --As a site administrator # Admin users --As a content editor # Content management users --As a authenticated user # Logged-in users --``` -- --#### Test Data Conventions -- --- **Always prefix test content**: `[TEST] Page Title` --- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` --- **Avoid real names**: Don't use "Workshop" or "Training" --- **Be descriptive**: `[TEST] Event with All Fields` -- --#### Example Feature File -- --```gherkin --Feature: Homepage -- -- As a site visitor -- I want to access the homepage -- So that I can view the main landing page and navigate the site -- -- Scenario: View homepage content -- Given I am on the homepage -- Then I should see "[TEST] Welcome Message" -- And I should see "About Us" in the "navigation" region --``` -- --#### Discovering Available Step Definitions -- --```bash --# Generate step definitions reference (run once) --ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt --``` -- --Use the cached file for reference, don't regenerate unless asked. -- --### Content Type Testing Process -- --When creating comprehensive tests for content types: -- --1. **Analyze Configuration First** -- -- - Check `config/default/field.field.node.[type].*.yml` -- - Review `core.entity_view_display.node.[type].default.yml` -- - Identify visible vs hidden fields -- --1. **Create Supporting Entities** -- --```gherkin --Background: -- Given "tags" terms: -- | name | -- | [TEST] Topic 1 | -- | [TEST] Topic 2 | -- -- And the following media "image" exist: -- | name | -- | [TEST] Featured Image 1 | --``` -- --1. **Test All Visible Fields** -- --```gherkin --Scenario: View complete content with all fields -- Given "page" content: -- | title | body | field_tags | -- | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | -- When I visit "[TEST] Complete Page Test" -- Then I should see "[TEST] Complete Page Test" -- And I should see "[TEST] This is the body text." -- And I should see "[TEST] Topic 1" --``` -- - ## Debugging & Troubleshooting - - ### Development Tools -@@ -881,7 +771,6 @@ - - Always use ahoy prefix for commands - - Never use drush php:eval directly - - Test data must use [TEST] prefix --- Behat tests need proper user story format - - The project uses Docker locally but deploys to various hosting platforms with automated CI/CD. - CLAUDE_CONTEXT_SUMMARY --> +@@ -36,16 +36,6 @@ + ahoy lint # Check code style + ahoy lint-fix # Auto-fix code style + +-# PHPUnit testing +-ahoy test # Run PHPUnit tests +-ahoy test-unit # Run PHPUnit Unit tests +-ahoy test-kernel # Run PHPUnit Kernel tests +-ahoy test-functional # Run PHPUnit Functional tests +-ahoy test -- --filters=TestClassName # Run specific PHPUnit test class +- +-# Behat testing +-ahoy test-bdd # Run Behat tests +-ahoy test-bdd -- --tags=@tagname # Run Behat tests with specific tag + ``` + + ## Critical Rules diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_none/docs/faqs.md b/.vortex/installer/tests/Fixtures/handler_process/tools_none/docs/faqs.md deleted file mode 100644 index e445b0f50..000000000 --- a/.vortex/installer/tests/Fixtures/handler_process/tools_none/docs/faqs.md +++ /dev/null @@ -1,29 +0,0 @@ -@@ -58,16 +58,6 @@ - - See https://www.vortextemplate.com/docs/tools/xdebug for more details. - --## How to use Xdebug on Behat scripts? -- --1. Enable debugging: `ahoy debug` --2. Enter CLI container: `ahoy cli` --3. Run Behat tests: -- --```bash --vendor/bin/behat --xdebug path/to/test.feature --``` -- - ## What should I do to switch to a "clean" branch environment? - - Provided that your stack is already running: -@@ -158,11 +148,3 @@ - - The maintenance theme should be a valid Drupal theme that is already installed - and enabled on your site. -- --## Behat tests with `@javascript` tag sometimes get stuck -- --Behat tests with `@javascript` tag sometimes get stuck for about 10min then --fail. --The Chrome container randomly get stuck for an unknown reason. -- --Restart the Chrome container: `docker compose restart chrome` diff --git a/.vortex/installer/tests/Fixtures/handler_process/tools_none/docs/testing.md b/.vortex/installer/tests/Fixtures/handler_process/tools_none/docs/testing.md new file mode 100644 index 000000000..712b28ae7 --- /dev/null +++ b/.vortex/installer/tests/Fixtures/handler_process/tools_none/docs/testing.md @@ -0,0 +1,227 @@ +@@ -2,226 +2,3 @@ + + This document describes **what** testing conventions and agreements apply to + this project. +- +-## PHPUnit conventions +- +-Unit, Kernel, Functional tests. +- +-See [documentation](https://www.vortextemplate.com/docs/development/phpunit) +-on how to run tests, configure environment variables and code coverage, and use +-test reports in continuous integration pipeline. +- +-### Test class structure +- +-All PHPUnit tests must follow this structure: +- +-```php +-assertEquals('expected', $result); +- } +- +-} +-``` +- +-### Base test classes +- +-- **Unit** - `Drupal\Tests\UnitTestCase` - Testing isolated PHP classes +-- **Kernel** - `Drupal\KernelTests\KernelTestBase` - Testing with database/services +-- **Functional** - `Drupal\Tests\BrowserTestBase` - Testing with full browser +- +-### Test data conventions +- +-- **Always prefix test content**: `[TEST] Node Title` +-- **Use data providers**: For testing multiple input/output combinations +- - Must be a public static method +- - Must follow naming convention `dataProvider` +- - Must be placed after the test method it provides data for. +-- **Use unique identifiers**: Include test class or method name in test data +- +-### Data providers +- +-Always use data providers for testing multiple input/output combinations: +- +-```php +-/** +- * Test my function with various inputs. +- * +- * @dataProvider dataProviderMyFunction +- */ +-public function testMyFunction(string $input, string $expected): void { +- $this->assertEquals($expected, my_function($input)); +-} +- +-/** +- * Data provider for testMyFunction. +- */ +-public static function dataProviderMyFunction(): array { +- return [ +- 'empty string' => ['', ''], +- 'simple string' => ['hello', 'HELLO'], +- 'with numbers' => ['test123', 'TEST123'], +- ]; +-} +-``` +- +-### Testing services (Kernel tests) +- +-For Kernel tests that need Drupal services: +- +-```php +-installEntitySchema('node'); +- $this->installEntitySchema('user'); +- $this->myService = $this->container->get('my_module.my_service'); +- } +- +- /** +- * Test service method. +- */ +- public function testServiceMethod(): void { +- $result = $this->myService->doSomething(); +- $this->assertNotNull($result); +- } +- +-} +-``` +- +-## Behat conventions +- +-BDD end-to-end tests. +- +-See [documentation](https://www.vortextemplate.com/docs/development/behat) +-on how to run Behat tests, configure environment variables, and use test reports +-in continuous integration pipeline. +- +-### User story format +- +-All Behat features must follow this format: +- +-```gherkin +-Feature: [Feature name] +- +- As a [user type] +- I want to [action/goal] +- So that [benefit/outcome] +-``` +- +-### Standard user types +- +-Use these consistent user type descriptions: +- +-```gherkin +-As a site visitor # Anonymous users +-As a site administrator # Admin users +-As a content editor # Content management users +-As a authenticated user # Logged-in users +-``` +- +-### Test data conventions +- +-- **Always prefix test content**: `[TEST] Page Title` +-- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +-- **Avoid real names**: Don't use "Workshop" or "Training" +-- **Be descriptive**: `[TEST] Event with All Fields` +- +-### Example feature file +- +-```gherkin +-Feature: Homepage +- +- As a site visitor +- I want to access the homepage +- So that I can view the main landing page and navigate the site +- +- Scenario: View homepage content +- Given I am on the homepage +- Then I should see "[TEST] Welcome Message" +- And I should see "About Us" in the "navigation" region +-``` +- +-### Content type testing process +- +-When creating comprehensive tests for content types: +- +-1. Analyze configuration first +- +- - Check `config/default/field.field.node.[type].*.yml` +- - Review `core.entity_view_display.node.[type].default.yml` +- - Identify visible vs hidden fields +- +-2. Create supporting entities +- +- ```gherkin +- Background: +- Given "tags" terms: +- | name | +- | [TEST] Topic 1 | +- | [TEST] Topic 2 | +- +- And the following media "image" exist: +- | name | +- | [TEST] Featured Image 1 | +- ``` +- +-3. Test all visible fields +- +- ```gherkin +- Scenario: View complete content with all fields +- Given "page" content: +- | title | body | field_tags | +- | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | +- When I visit "[TEST] Complete Page Test" +- Then I should see "[TEST] Complete Page Test" +- And I should see "[TEST] This is the body text." +- And I should see "[TEST] Topic 1" +- ``` diff --git a/.vortex/installer/tests/Fixtures/handler_process/version_scheme_other/.env b/.vortex/installer/tests/Fixtures/handler_process/version_scheme_other/.env index 6c7f31ea4..24e56d775 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/version_scheme_other/.env +++ b/.vortex/installer/tests/Fixtures/handler_process/version_scheme_other/.env @@ -1,7 +1,7 @@ @@ -164,7 +164,7 @@ # # Can be one of: calver, semver, other - # @see https://www.vortextemplate.com/docs/workflows/releasing + # @see https://www.vortextemplate.com/docs/releasing -VORTEX_RELEASE_VERSION_SCHEME=calver +VORTEX_RELEASE_VERSION_SCHEME=other diff --git a/.vortex/installer/tests/Fixtures/handler_process/version_scheme_other/docs/releasing.md b/.vortex/installer/tests/Fixtures/handler_process/version_scheme_other/docs/releasing.md index bf8a6867e..001bb15bd 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/version_scheme_other/docs/releasing.md +++ b/.vortex/installer/tests/Fixtures/handler_process/version_scheme_other/docs/releasing.md @@ -1,19 +1,17 @@ -@@ -20,18 +20,3 @@ - 5. There are no PRs in GitHub related to the release. +@@ -15,16 +15,6 @@ 6. The hash of the `HEAD` of the `production` branch matches the hash of the `HEAD` of `main` branch. + +-## Version scheme - --## Version Number - Calendar Versioning (CalVer) +-This project uses [Calendar Versioning](https://calver.org/) (`YY.M.Z`): - --Release versions are numbered according to [CalVer Versioning](https://calver.org/). +-- `YY` = Short year +-- `M` = Short month +-- `Z` = Hotfix/patch version - --Given a version number `YY.M.Z`: +-Examples: `__VERSION__`, `__VERSION__`, `__VERSION__`, `__VERSION__` - --- `YY` = Short year. No leading zeroes. --- `M` = Short month. No leading zeroes. --- `Z` = Hotfix/patch version. No leading zeroes. -- --Examples: -- --- Correct: `__VERSION__`, `__VERSION__` , `__VERSION__`, `__VERSION__`, `__VERSION__` --- Incorrect: `__VERSION__`, `__VERSION__` , `25` , `__VERSION__` , `__VERSION__`, `__VERSION__`, `__VERSION__` + ## Project-specific configuration + + diff --git a/.vortex/installer/tests/Fixtures/handler_process/version_scheme_semver/.env b/.vortex/installer/tests/Fixtures/handler_process/version_scheme_semver/.env index f3131aafc..720675cc7 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/version_scheme_semver/.env +++ b/.vortex/installer/tests/Fixtures/handler_process/version_scheme_semver/.env @@ -1,7 +1,7 @@ @@ -164,7 +164,7 @@ # # Can be one of: calver, semver, other - # @see https://www.vortextemplate.com/docs/workflows/releasing + # @see https://www.vortextemplate.com/docs/releasing -VORTEX_RELEASE_VERSION_SCHEME=calver +VORTEX_RELEASE_VERSION_SCHEME=semver diff --git a/.vortex/installer/tests/Fixtures/handler_process/version_scheme_semver/docs/releasing.md b/.vortex/installer/tests/Fixtures/handler_process/version_scheme_semver/docs/releasing.md index acad4f11b..2aa278561 100644 --- a/.vortex/installer/tests/Fixtures/handler_process/version_scheme_semver/docs/releasing.md +++ b/.vortex/installer/tests/Fixtures/handler_process/version_scheme_semver/docs/releasing.md @@ -1,25 +1,14 @@ -@@ -21,17 +21,17 @@ - 6. The hash of the `HEAD` of the `production` branch matches the hash of - the `HEAD` of `main` branch. +@@ -17,10 +17,10 @@ --## Version Number - Calendar Versioning (CalVer) -+## Version Number - Semantic Versioning (SemVer) + ## Version scheme --Release versions are numbered according to [CalVer Versioning](https://calver.org/). -+Release versions are numbered according to [Semantic Versioning](https://semver.org/). +-This project uses [Calendar Versioning](https://calver.org/) (`YY.M.Z`): ++This project uses [Semantic Versioning](https://semver.org/) (`X.Y.Z`): --Given a version number `YY.M.Z`: -+Given a version number `X.Y.Z`: +-- `YY` = Short year +-- `M` = Short month ++- `X` = Major release version ++- `Y` = Minor release version + - `Z` = Hotfix/patch version --- `YY` = Short year. No leading zeroes. --- `M` = Short month. No leading zeroes. -+- `X` = Major release version. No leading zeroes. -+- `Y` = Minor Release version. No leading zeroes. - - `Z` = Hotfix/patch version. No leading zeroes. - - Examples: - --- Correct: `__VERSION__`, `__VERSION__` , `__VERSION__`, `__VERSION__`, `__VERSION__` --- Incorrect: `__VERSION__`, `__VERSION__` , `25` , `__VERSION__` , `__VERSION__`, `__VERSION__`, `__VERSION__` -+- Correct: `__VERSION__`, `__VERSION__` , `__VERSION__` , `__VERSION__` -+- Incorrect: `0.1` , `1` , `1.0` , `__VERSION__` , `__VERSION__` + Examples: `__VERSION__`, `__VERSION__`, `__VERSION__`, `__VERSION__` diff --git a/.vortex/tests/.markdownlint.yaml b/.vortex/tests/.markdownlint.yaml index 3ff7a88a8..86db7628d 100644 --- a/.vortex/tests/.markdownlint.yaml +++ b/.vortex/tests/.markdownlint.yaml @@ -14,6 +14,9 @@ MD013: false # MD024/no-duplicate-heading : Multiple headings with the same content : https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md024.md MD024: false +# MD029/ol-prefix : Ordered list item prefix : https://github.com/DavidAnson/markdownlint/blob/main/doc/md029.md +MD029: false + # MD033/no-inline-html : Inline HTML : https://github.com/DavidAnson/markdownlint/blob/v0.38.0/doc/md033.md MD033: false diff --git a/.vortex/tests/CLAUDE.md b/.vortex/tests/CLAUDE.md new file mode 100644 index 000000000..0e55d2330 --- /dev/null +++ b/.vortex/tests/CLAUDE.md @@ -0,0 +1,154 @@ +# Testing System Guide + +## Overview + +**BATS** - Unit testing individual shell scripts with mocked commands. +Tests scripts in isolation without real services. Fast execution (~seconds). + +**PHPUnit** - Integration testing complete workflows in real Docker containers. +Tests actual Drupal site with real database and services. Slow execution (~minutes). + +## Setup + +```bash +cd .vortex +ahoy install # Install dependencies (run once) +``` + +## BATS - Unit Testing Shell Scripts + +**Use when**: Changed a shell script in `scripts/vortex/*.sh` or provision logic. + +**Reference**: `node_modules/bats-helpers/README.md` - Mocking, assertions, step helpers + +```bash +cd .vortex +ahoy test-bats -- tests/bats/unit/notify.bats # Single script +ahoy test-bats -- tests/bats/unit/ # All unit tests +ahoy test-bats -- tests/bats/provision.bats # Provision tests +ahoy test-bats -- tests/bats/ # All BATS tests +``` + +### Helpers System + +Located in `node_modules/bats-helpers/src/steps.bash`: + +**Step Types**: +1. **Mock**: `@ [] # [ # ]` +2. **Assert present**: `""` +3. **Assert absent**: `"- "` + +**Usage**: + +```bash +declare -a STEPS=( + "@drush -y status # 0 # success" # Mock + "Expected output" # Must contain + "- Unwanted output" # Must NOT contain +) + +mocks="$(run_steps "setup")" +# ... run code ... +run_steps "assert" "${mocks}" +``` + +### Key Files + +- `provision.bats` - Provision script tests +- `_helper.bash` - Test helpers +- `unit/` - Individual script tests +- `fixtures/` - Test data + +## PHPUnit - Integration Testing Workflows + +**Use when**: Changed ahoy commands, Docker setup, or need to test full build/deploy workflow. + +**References**: +- `vendor/alexskrypnyk/phpunit-helpers/README.md` - Test helpers, traits, assertions +- `vendor/alexskrypnyk/file/README.md` - File operations, batch processing + +```bash +cd .vortex/tests +./vendor/bin/phpunit # All tests +./vendor/bin/phpunit --filter "TestClassName" # Specific test +``` + +### cmd() Function + +Combines `processRun()` + `assertProcessSuccessful()` + assertions: + +```php +$this->cmd('ahoy drush cr'); // Simple +$this->cmd('ahoy info', 'Project name'); // With assertion +$this->cmd('ahoy info', ['line1', 'line2']); // Multiple +$this->cmd('ahoy reset', inp: ['y'], tio: 300); // Named params +``` + +### cmdFail() Function + +```php +$this->cmdFail('ahoy lint-be', tio: 120); +``` + +### Output Prefixes + +**CRITICAL**: If using ANY prefix, ALL strings must have prefixes. + +- `+` exact match present +- `*` substring present +- `-` exact match absent +- `!` substring absent + +```php +// ✅ All prefixed +$this->cmd('ahoy info', ['* Xdebug', '! Enabled']); + +// ❌ Mixed - throws exception +$this->cmd('ahoy info', ['Xdebug', '! Enabled']); +``` + +### Cross-Platform File Operations + +Use `AlexSkrypnyk\File\File` class: + +```php +use AlexSkrypnyk\File\File; + +File::mkdir($path); +File::dump($path, $content); +File::remove($path); +File::rmdir($path); +``` + +Use `self::$tmp` for temporary files (auto-cleaned). + +## Shell Script Patterns + +### Standard Structure + +```bash +#!/usr/bin/env bash +# Environment loading +t=$(mktemp) && export -p >"${t}" && set -a && . ./.env && set +a && . "${t}" && rm "${t}" + +set -eu +[ "${VORTEX_DEBUG-}" = "1" ] && set -x + +# Variables with defaults +VAR="${VAR:-default}" + +# Helpers +info() { printf "[INFO] %s\n" "${1}"; } +task() { printf " > %s\n" "${1}"; } +note() { printf " %s\n" "${1}"; } + +# Main execution +``` + +### Test Maintenance + +When updating scripts: + +1. Update main script +2. Update BATS assertions +3. Run `ahoy update-snapshots` from `.vortex/` diff --git a/CLAUDE.md b/CLAUDE.md index 35547fc7e..065047abb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,8 +1,8 @@ -# Vortex Drupal Project - Development Guide +# YOURSITE - Development Guide [//]: # (#;< VORTEX_DEV) -> **🚀 PROJECT MODE**: This guide helps with **developing Drupal projects** +> This guide helps with **developing Drupal projects** > created from the Vortex template. > > For **maintaining the Vortex template itself**, see the maintenance guide: @@ -10,964 +10,91 @@ [//]: # (#;> VORTEX_DEV) - -CRITICAL UNDERSTANDING: -- This is a PRODUCTION-READY Drupal project template -- Uses Docker for local development -- Commands are executed via 'ahoy' (task runner) -- Configuration is exported/imported via Drupal's config management -[//]: # (#;< TOOL_PHPUNIT) -- Testing includes PHPUnit -[//]: # (#;> TOOL_PHPUNIT) -[//]: # (#;< TOOL_BEHAT) -- Testing includes Behat (BDD) -[//]: # (#;> TOOL_BEHAT) -- Deployment is automated via CI/CD pipelines - -KEY CONVENTIONS: -- All local commands use 'ahoy' prefix -- Test data must use [TEST] prefix -- Never use drush php:eval directly -- Always use scripts via drush php:script -- Configuration changes must be exported -- Database operations vary by project setup - -CLAUDE_CONTEXT_END --> - -## Project Overview - -This is a **production-ready Drupal project** built with **Vortex** - a -comprehensive Drupal project template by DrevOps that provides: - -- 🐳 **Docker-based development environment** -- 🔄 **Automated CI/CD deployment workflows** -- 🧪 **Comprehensive testing framework** -- ⚙️ **Configuration management** (exportable configs) -- 🚀 **Production hosting integration** - -## Quick Start Commands - -```bash -# STEP 1: Build the site locally (first time setup) -ahoy build - -# STEP 2: Start development environment -ahoy up - -# STEP 3: Get site information and URLs -ahoy info - -# STEP 4: Get admin login link -ahoy login -``` - -## Core Development Workflow - -### 1. Environment Management - -```bash -# Start Docker containers (daily workflow) -ahoy up - -# Stop Docker containers (end of day) -ahoy down - -# Restart all containers (troubleshooting) -ahoy restart - -# Show project URLs, container status, database info -ahoy info -``` - -### 2. Site Building & Database - -```bash -# Complete site rebuild (nuclear option) -ahoy build - -# Re-provision site (install/import fresh DB) -ahoy provision - -# Reset to clean state (removes local changes) -ahoy reset -``` - -[//]: # (#;< !DB_DOWNLOAD_SOURCE_NONE) +## Daily Development Tasks ```bash -# Download fresh database from remote source -ahoy download-db +# Environment +ahoy up # Start containers +ahoy down # Stop containers +ahoy info # Show URLs and status +ahoy login # Get admin login URL -# Export current local database -ahoy export-db +# Build & Database +ahoy download-db # Download fresh database from remote +ahoy build # Complete site rebuild +ahoy provision # Re-provision (import DB + apply config) +ahoy import-db # Import database from file without applying config +ahoy export-db # Export current local database -# Import database from file -ahoy import-db [path/to/dump.sql] -``` +# Drush commands +ahoy drush cr # Clear cache +ahoy drush cex # Export configuration to code +ahoy drush cim # Import configuration from code +ahoy drush uli # Get one-time login link +ahoy drush status # Check site status -[//]: # (#;> !DB_DOWNLOAD_SOURCE_NONE) - -### 3. Daily Development Tasks - -```bash -# Run Drush commands (Drupal CLI) -ahoy drush [command] -# Examples: -ahoy drush status -ahoy drush cr # Clear cache -ahoy drush uli # Get login link - -# Run Composer commands (PHP dependencies) -ahoy composer [command] -# Examples: +# Composer ahoy composer install -ahoy composer require drupal/webform -``` - -## Code Quality & Testing - -### Linting (Code Standards) - -```bash -# Check code style issues (PHP, JS, CSS) -ahoy lint - -# Automatically fix code style issues -ahoy lint-fix -``` - -### Testing Framework - -[//]: # (#;< TOOL_PHPUNIT) - -```bash -# Run PHPUnit tests (unit/integration tests) -ahoy test-unit -``` +ahoy composer require drupal/[module_name] -[//]: # (#;> TOOL_PHPUNIT) +# Code quality +ahoy lint # Check code style +ahoy lint-fix # Auto-fix code style -[//]: # (#;< TOOL_BEHAT) - -```bash -# Run Behat tests (behavioral/BDD tests) -ahoy test-bdd - -# Run specific Behat feature -ahoy test-bdd tests/behat/features/homepage.feature -``` - -[//]: # (#;> TOOL_BEHAT) - -## Configuration Management (Critical for Drupal) - -### Understanding Config Management - -- **Structure changes** (content types, fields, views) = Configuration (exported - to code) -- **Content data** (nodes, users, media) = Database (not exported) - -### Export Configuration (After making admin changes) - -```bash -# Export ALL configuration changes to code -ahoy drush config:export -# Short version: -ahoy drush cex - -# Export with diff preview -ahoy drush config:export --diff -``` - -### Import Configuration (Deploy config changes) - -```bash -# Import configuration from code -ahoy drush config:import -# Short version: -ahoy drush cim - -# Import from specific environment -ahoy drush config:import --source=../config/stage -``` - -### Typical Config Workflow - -1. Make changes in Drupal admin UI -2. Run `ahoy drush cex` to export to code -3. Commit the config files to git -4. Deploy code and run `ahoy drush cim` on target environment - -## Project Structure (Critical Understanding) - -```text -your-project/ -├── .ahoy.yml # Ahoy task definitions -├── .env # Environment variables (local) -├── docker-compose.yml # Local development containers -├── composer.json # PHP dependencies -│ -├── config/ # Drupal configuration (version controlled) -│ ├── default/ # Base configuration (all environments) -│ ├── dev/ # Development-specific overrides -│ ├── stage/ # Staging-specific overrides -│ └── ci/ # CI-specific overrides -│ -├── web/ # Drupal webroot (document root) -│ ├── modules/custom/ # Your custom modules -│ ├── themes/custom/ # Your custom themes -│ ├── sites/default/ # Drupal site settings -│ └── index.php # Drupal entry point -│ -├── tests/ -[//]: # (#;< TOOL_BEHAT) -│ ├── behat/ # Behavioral tests (user scenarios) -│ │ ├── features/ # Test scenarios (.feature files) -│ │ └── behat.yml # Behat configuration -[//]: # (#;> TOOL_BEHAT) -[//]: # (#;< TOOL_PHPUNIT) -│ └── phpunit/ # Unit/integration tests -[//]: # (#;> TOOL_PHPUNIT) -│ -└── scripts/ - ├── vortex/ # Core Vortex scripts (don't modify) - └── custom/ # Project-specific scripts -``` - -## Custom Code Development - -### Creating Custom Modules - -```bash -# Generate custom module scaffold -ahoy drush generate:module - -# Location: web/modules/custom/[module_name]/ -# Enable module: -ahoy drush pm:install [module_name] -``` - -[//]: # (#;< DRUPAL_THEME) - -### Theme Development - -```bash -# Navigate to custom theme -cd web/themes/custom/[theme_name] - -# Install theme dependencies -yarn install - -# Build theme assets (CSS/JS) -yarn run build - -# Watch for changes during development -yarn run watch - -# Build for production -yarn run build:prod -``` - -[//]: # (#;> DRUPAL_THEME) - -## PHP Script Execution (IMPORTANT) - -### ✅ Correct Way: Use PHP Scripts - -```bash -# Run PHP script with full Drupal bootstrap -ahoy drush php:script script_name - -# List available scripts -ahoy drush php:script - -# Run with custom script path -ahoy drush php:script script_name --script-path=scripts/custom - -# Pass arguments to script (note the -- separator) -ahoy drush php:script -- script_name --arg1=value1 --arg2=value2 -``` - -### ❌ NEVER Do This - -```bash -# DANGEROUS - Never evaluate PHP directly! -ahoy drush php:eval "dangerous_code_here" -``` - -### Creating PHP Scripts - -Create scripts in `scripts/custom/` directory: - -```php -getStorage('node') - ->loadByProperties(['type' => 'page']); - -foreach ($nodes as $node) { - print $node->getTitle(); -} -``` - -## Service Integrations - -[//]: # (#;< SERVICE_SOLR) - -### Solr Search Service - -```bash -# Check Solr search status -ahoy drush search-api:status - -# Index all content to Solr -ahoy drush search-api:index - -# Clear and rebuild Solr index -ahoy drush search-api:clear -ahoy drush search-api:index - -# Check Solr server connection -ahoy drush search-api:server-status -``` - -[//]: # (#;> SERVICE_SOLR) - -[//]: # (#;< SERVICE_REDIS) - -### Redis Caching Service - -```bash -# Clear all caches (includes Redis) -ahoy drush cache:rebuild - -# Check Redis connection status -ahoy drush php:script -- redis_status - -# Flush Redis cache specifically -ahoy drush eval "\\Drupal::service('cache.backend.redis')->deleteAll();" -``` - -[//]: # (#;> SERVICE_REDIS) - -[//]: # (#;< SERVICE_CLAMAV) - -### ClamAV Virus Scanning Service - -```bash -# Test virus scanning functionality -ahoy drush clamav:scan /path/to/test/file - -# Check ClamAV daemon status -ahoy drush clamav:status - -# Update virus definitions -ahoy drush clamav:update -``` - -[//]: # (#;> SERVICE_CLAMAV) - -## Dependency Management - -### Adding Drupal Modules - -```bash -# Add contributed modules -ahoy composer require drupal/webform - -# Enable added modules -ahoy drush pm:install webform -``` - -### Patching Contributed Modules - -When contributed modules need fixes or customizations, use the proper patching workflow with `cweagans/composer-patches`. - -Vortex uses **composer-patches v2.x** which provides git-based patching with improved reliability and reproducibility. - -#### Key Features of v2 - -- **Git-based patching**: Uses `git apply` exclusively for cross-platform consistency -- **patches.lock.json**: Automatically generated file with patch metadata and SHA-256 checksums -- **New commands**: - - `composer patches-relock` - Regenerate patches.lock.json after adding/removing patches - - `composer patches-repatch` - Remove and reinstall patched dependencies -- **Automatic failure on patch errors**: Patches must apply successfully or installation fails - -#### Understanding patches.lock.json - -This file is automatically generated and **must be committed to version control** (like composer.lock). - -**What it contains:** - -- Patch metadata (URLs, descriptions, target packages) -- SHA-256 checksums for patch verification - -**Why it matters:** - -- Ensures reproducible builds across teams and CI/CD -- Verifies patch integrity with checksums -- Prevents "works on my machine" issues -- Makes patch state explicit and trackable - -**Always commit this file** after adding or removing patches. - -#### Prerequisites for Patching - -- Project uses `cweagans/composer-patches` package (v2.x) -- Git is available for version control (required by v2) -- Access to Drupal.org git repositories - -#### Patch Storage and Configuration - -Patches are defined in `composer.json` under the `extra.patches` section: - -```json -{ - "extra": { - "patches": { - "drupal/module_name": { - "Description of fix": "patches/module-name-description.patch", - "Another fix": "https://www.drupal.org/files/issues/external-patch.patch" - } - } - } -} -``` - -- **Local patches**: Store in `patches/` directory in project root -- **External patches**: Reference URLs directly in composer.json -- **Naming convention**: Use descriptive names like `module-name-description.patch` - -#### Creating Module Patches - -##### Step 1: Identify Module Version - -Always work with the exact version and state used in your project: - -```bash -# Check installed version -ahoy composer show drupal/module_name - -# Verify version in composer.lock -grep -A 20 "drupal/module_name" composer.lock -``` - -##### Step 2: Clone Module from Git - -**CRITICAL**: Always use the official Drupal git repository, not tarball downloads: - -```bash -# Create working directory -cd /tmp && mkdir module_patch_work && cd module_patch_work - -# Clone the module -git clone https://git.drupalcode.org/project/module_name.git - -# Navigate to module directory -cd module_name - -# Checkout the exact version/tag used in project -git checkout 1.2.3 # Replace with actual version - -# Create working branch -git checkout -b fix-description -``` - -##### Step 3: Apply Existing Patches - -If your project already has patches for this module, apply them first to match the current state: - -```bash -# Apply each existing patch in order -curl -s https://example.com/patch1.patch | patch -p1 -curl -s https://example.com/patch2.patch | patch -p1 +# PHPUnit testing +ahoy test # Run PHPUnit tests +ahoy test-unit # Run PHPUnit Unit tests +ahoy test-kernel # Run PHPUnit Kernel tests +ahoy test-functional # Run PHPUnit Functional tests +ahoy test -- --filters=TestClassName # Run specific PHPUnit test class -# Commit the patches to establish baseline -git add . -git commit -m "Apply existing patches to match project state" +# Behat testing +ahoy test-bdd # Run Behat tests +ahoy test-bdd -- --tags=@tagname # Run Behat tests with specific tag ``` -##### Step 4: Make Required Changes +## Critical Rules -Edit the necessary files to implement your fix: +- **Never modify** `scripts/vortex/` - use `scripts/custom/` for your scripts +- **Never use** `ahoy drush php:eval` - use `ahoy drush php:script` instead +- **Always export config** after admin UI changes: `ahoy drush cex` -```bash -# Make your changes using your preferred editor -vim path/to/file.php - -# Or use automated tools if applicable -sed -i 's/old_code/new_code/' path/to/file.php -``` - -##### Step 5: Generate Clean Patch - -Create a proper git-based patch: - -```bash -# Stage your changes -git add . - -# Generate patch from staged changes -git diff --cached > /path/to/project/patches/module-name-fix-description.patch -``` - -##### Step 6: Test Patch Application - -**ALWAYS test that your patch applies cleanly**: - -```bash -# Reset to test patch application -git reset --hard HEAD - -# Test patch applies without conflicts -git apply /path/to/project/patches/module-name-fix-description.patch - -# Verify changes were applied correctly -git status -git diff -``` - -##### Step 7: Integrate into Project - -Add the patch to your project's composer configuration and apply it using v2 commands: - -```bash -# Add patch definition to composer.json extra.patches section - -# Regenerate patches.lock.json -ahoy composer patches-relock - -# Remove and reinstall patched package -ahoy composer patches-repatch - -# Update composer.lock -ahoy composer update --lock - -# Verify no patch application errors -# Check that functionality works as expected - -# Commit all changes -git add composer.json composer.lock patches.lock.json patches/ -git commit -m "Added patch for drupal/module_name." -``` - -##### Step 8: Clean Up - -Remove temporary working directory: - -```bash -rm -rf /tmp/module_patch_work -``` - -#### Patching Best Practices - -**✅ Do This:** - -- Use descriptive patch names that explain what they fix -- Keep patches focused - one fix per patch when possible -- Follow Drupal coding standards in your changes -- Test locally before committing patches -- Document the issue being fixed in composer.json description -- Include issue URLs when available from drupal.org - -**❌ Avoid These Mistakes:** - -- Working with tarball downloads instead of git repositories -- Creating patches from modified project files -- Skipping patch application testing -- Creating patches without applying existing patches first -- Assuming patches work across different module versions - -#### Troubleshooting Patch Issues - -**Patch Won't Apply:** - -1. Check module version matches between patch creation and application -2. Verify existing patches are applied in correct order -3. Check for whitespace issues in patch file -4. Ensure patch paths are correct (usually relative to module root) - -**Patch Conflicts:** - -1. Identify conflicting patches by applying them individually -2. Update patch order in composer.json if needed -3. Recreate patches against the current patched state -4. Merge patches if they modify the same areas - -**Performance Issues:** - -1. Minimize external patch URLs to reduce download time -2. Store frequently used patches locally in patches directory -3. Keep patch files small and focused -4. Remove obsolete patches when updating modules - -### Adding JavaScript/CSS Libraries - -For npm packages that need to be Drupal libraries, define them as inline -Composer packages: - -1. **Add to composer.json repositories section:** - -```json -{ - "repositories": [ - { - "type": "package", - "package": { - "name": "vendor/library-name", - "type": "drupal-library", - "version": "1.0.0", - "source": { - "type": "git", - "url": "https://github.com/vendor/library-name", - "reference": "1.0.0" - } - } - } - ] -} -``` - -1. **Install via Composer:** - -```bash -ahoy composer require vendor/library-name -``` - -[//]: # (#;< DRUPAL_THEME) - -### Theme Dependencies - -```bash -# Navigate to theme directory -cd web/themes/custom/[theme_name] - -# Add frontend dependencies -yarn add [package-name] - -# Example: Add Bootstrap -yarn add bootstrap - -# Install dev dependencies -yarn add --dev sass webpack -``` - -[//]: # (#;> DRUPAL_THEME) - -## Testing Best Practices - -[//]: # (#;< TOOL_BEHAT) - -### Writing Behat Tests (BDD) - -#### User Story Format (Required) - -All Behat features MUST follow this format: - -```gherkin -Feature: [Feature name] - - As a [user type] - I want to [action/goal] - So that [benefit/outcome] -``` - -#### Standard User Types - -```gherkin -As a site visitor # Anonymous users -As a site administrator # Admin users -As a content editor # Content management users -As a authenticated user # Logged-in users -``` - -#### Test Data Conventions - -- **Always prefix test content**: `[TEST] Page Title` -- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` -- **Avoid real names**: Don't use "Workshop" or "Training" -- **Be descriptive**: `[TEST] Event with All Fields` - -#### Example Feature File - -```gherkin -Feature: Homepage - - As a site visitor - I want to access the homepage - So that I can view the main landing page and navigate the site - - Scenario: View homepage content - Given I am on the homepage - Then I should see "[TEST] Welcome Message" - And I should see "About Us" in the "navigation" region -``` - -#### Discovering Available Step Definitions - -```bash -# Generate step definitions reference (run once) -ahoy test-bdd -- --definitions=l >.claude/artifacts/behat-steps.txt -``` - -Use the cached file for reference, don't regenerate unless asked. - -### Content Type Testing Process - -When creating comprehensive tests for content types: - -1. **Analyze Configuration First** - - - Check `config/default/field.field.node.[type].*.yml` - - Review `core.entity_view_display.node.[type].default.yml` - - Identify visible vs hidden fields - -1. **Create Supporting Entities** - -```gherkin -Background: - Given "tags" terms: - | name | - | [TEST] Topic 1 | - | [TEST] Topic 2 | - - And the following media "image" exist: - | name | - | [TEST] Featured Image 1 | -``` - -1. **Test All Visible Fields** - -```gherkin -Scenario: View complete content with all fields - Given "page" content: - | title | body | field_tags | - | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | - When I visit "[TEST] Complete Page Test" - Then I should see "[TEST] Complete Page Test" - And I should see "[TEST] This is the body text." - And I should see "[TEST] Topic 1" -``` - -[//]: # (#;> TOOL_BEHAT) - -## Debugging & Troubleshooting - -### Development Tools - -```bash -# Enable development modules -ahoy drush pm:install devel - -# Get admin login URL -ahoy login - -# View recent log entries -ahoy drush watchdog:show - -# Clear all caches -ahoy drush cache:rebuild - -# Check system status -ahoy drush status -``` - -### Performance Optimization - -```bash -# Enable CSS/JS aggregation -ahoy drush config:set system.performance css.preprocess 1 -ahoy drush config:set system.performance js.preprocess 1 - -# Clear render cache -ahoy drush cache:rebuild-external - -# Check database updates needed -ahoy drush updatedb:status -``` - -### Container Debugging - -```bash -# Check container status -docker-compose ps - -# View container logs -docker-compose logs [service_name] -# Examples: -docker-compose logs web -docker-compose logs db - -# Access container shell -docker-compose exec web bash -docker-compose exec db mysql -u drupal -p drupal -``` - -### Common Issues & Solutions - -**Site not loading:** - -```bash -ahoy down && ahoy up -ahoy info # Verify URLs and ports -``` - -**Database connection errors:** - -```bash -docker-compose ps # Check if database container is running -ahoy reset # Nuclear option: rebuild everything -``` - -**Permission issues:** - -```bash -# Fix file permissions (Linux/Mac) -sudo chown -R $USER:$USER . -``` - -**Memory issues during composer install:** - -```bash -# Increase PHP memory temporarily -ahoy composer install --no-dev --optimize-autoloader -``` - -## CI/CD & Deployment - -### Automated Deployment - -This project includes automated deployment via: - -[//]: # (#;< CI_PROVIDER_GHA) - -- **GitHub Actions** - See `.github/workflows/` - -[//]: # (#;> CI_PROVIDER_GHA) - -[//]: # (#;< CI_PROVIDER_CIRCLECI) - -- **CircleCI** - See `.circleci/config.yml` - -[//]: # (#;> CI_PROVIDER_CIRCLECI) - -### Hosting Platforms - -[//]: # (#;< HOSTING_LAGOON) - -- **Lagoon** - Container-based hosting platform - -[//]: # (#;> HOSTING_LAGOON) - -[//]: # (#;< HOSTING_ACQUIA) - -- **Acquia Cloud** - Enterprise Drupal hosting - -[//]: # (#;> HOSTING_ACQUIA) - -[//]: # (#;< DEPLOY_TYPES_CONTAINER_REGISTRY) - -- **Container Registry** - Docker-based deployments - -[//]: # (#;> DEPLOY_TYPES_CONTAINER_REGISTRY) - -### Manual Deployment Commands - -```bash -# Export configuration before deployment -ahoy drush config:export - -# Run database updates -ahoy drush updatedb - -# Import configuration -ahoy drush config:import - -# Clear caches -ahoy drush cache:rebuild - -# Full deployment sequence -ahoy drush updatedb && ahoy drush config:import && ahoy drush cache:rebuild -``` - -## Getting Help & Resources - -### Command Help - -```bash -# List all available ahoy commands -ahoy --help -``` - -### Log Files & Debugging - -```bash -# View ahoy logs -ahoy logs - -# Check container logs -docker-compose logs --tail=50 web - -# View Drupal watchdog logs -ahoy drush watchdog:show --count=20 -``` +## Key Directories -### Documentation Resources +- `web/modules/custom/` - Custom modules +- `web/themes/custom/` - Custom themes +- `config/default/` - Drupal configuration +- `scripts/custom/` - Project scripts +- `patches/` - Module patches -- **Vortex Documentation**: https://www.vortextemplate.com -- **Drupal Documentation**: https://www.drupal.org/docs -- **Drush Documentation**: https://www.drush.org -- **Ahoy Documentation**: https://github.com/ahoy-cli/ahoy -- **Docker Compose**: https://docs.docker.com/compose/ +## Documentation -### Project-Specific Help +This project uses two documentation sources: -- Check `/docs` directory for additional project documentation -- Review `README.md` in project root -- Check `.ahoy.yml` for custom commands -- Review `composer.json` for installed packages and scripts +### Project-specific documentation (`docs/`) ---- +The `docs/` directory contains **what** applies to this project: - +Use the sitemap to discover available pages: +https://www.vortextemplate.com/sitemap.xml -*This guide covers the complete development workflow for your Vortex-powered -Drupal project. Keep this guide updated as your project grows and add -project-specific conventions below.* +**Caching:** Save fetched docs to `.claude/artifacts/docs-[topic].md` with header +``. +Re-fetch if user reports docs are outdated. diff --git a/README.md b/README.md index b1e7e0244..8ae3169fa 100644 --- a/README.md +++ b/README.md @@ -97,7 +97,7 @@ Releases are planned to occur **monthly**. However, adjustments to the release schedule may be necessary depending on the scope of features and the volume of bug fixes required. -We recommend subscribing for releases and keeping your stack [updated](https://www.vortextemplate.com/docs/workflows/updating-vortex) +We recommend subscribing for releases and keeping your stack [updated](https://www.vortextemplate.com/docs/updating-vortex) with each new version. ## Documentation diff --git a/docs/README.md b/docs/README.md index 44c9ca7e5..fdb1862c0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,11 @@ -# Project-specific documentation +# Project documentation -- [Testing](testing.md) -- [CI](ci.md) -- [Deployment](deployment.md) -- [Releasing](releasing.md) -- [FAQs](faqs.md) +This directory contains project-specific documentation that describes **what** +applies to this project. For **how** to perform operations, see +[Vortex Documentation](https://www.vortextemplate.com/docs/). + +- [Testing](testing.md) - Testing conventions and agreements +- [CI](ci.md) - Continuous integration configuration +- [Deployment](deployment.md) - Deployment configuration +- [Releasing](releasing.md) - Release process and versioning +- [FAQs](faqs.md) - Project-specific FAQs diff --git a/docs/ci.md b/docs/ci.md index c37ecae87..c61a48fab 100644 --- a/docs/ci.md +++ b/docs/ci.md @@ -1,59 +1,30 @@ # Continuous Integration -In software engineering, continuous integration (CI) is the practice of merging -all developer working copies to a shared mainline several times a day. -Before feature changes can be merged into a shared mainline, a complete build -must run and pass all tests on CI server. +For information on how CI works, see +[Vortex CI Documentation](https://www.vortextemplate.com/docs/continuous-integration). [//]: # (#;< CI_PROVIDER_CIRCLECI) -## Circle CI +## CI provider -This project uses [Circle CI](https://circleci.com/) as a CI server: it imports -production backups into fully built codebase and runs code linting and tests. -When tests pass, a deployment process is triggered for nominated branches -(usually, `main` and `develop`). +This project uses [CircleCI](https://circleci.com/). -Refer to https://www.vortextemplate.com/docs/continuous-integration for more -information. - -### Skipping CI build - -Add `[skip ci]` to the commit subject to skip CI build. Useful for documentation -changes. - -### SSH - -Circle CI supports shell access to the build for 120 minutes after the build is -finished when the build is started with SSH support. Use "Rerun job with SSH" -button in Circle CI UI to start build with SSH support. +See [CircleCI documentation](https://www.vortextemplate.com/docs/continuous-integration/circleci) +for setup and configuration details. [//]: # (#;> CI_PROVIDER_CIRCLECI) [//]: # (#;< CI_PROVIDER_GHA) -## GitHub Actions - -This project uses [GitHub Actions](https://github.com/features/actions) as a -CI server: it imports production backups into fully built codebase and runs -code linting and tests. When tests pass, a deployment process is triggered for -nominated branches (usually, `main` and `develop`). +## CI provider -Refer to https://www.vortextemplate.com/docs/continuous-integration for more -information. +This project uses [GitHub Actions](https://github.com/features/actions). -### Skipping CI build +See [GitHub Actions documentation](https://www.vortextemplate.com/docs/continuous-integration/github-actions) +for setup and configuration details. -Add `[skip ci]` to the commit subject to skip CI build. Useful for documentation -changes. - -### SSH - -GitHub Actions does not supports shell access to the build, but there is an -action provided withing the `build` job that allows you to run a build with SSH -support. +[//]: # (#;> CI_PROVIDER_GHA) -Use "Run workflow" button in GitHub Actions UI to start build with SSH support -that will be available for 120 minutes after the build is finished. +## Project-specific configuration -[//]: # (#;> CI_PROVIDER_GHA) + diff --git a/docs/deployment.md b/docs/deployment.md index 188d307f2..211ad4e89 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,115 +1,57 @@ -# Deployment process +# Deployment -Refer to https://www.vortextemplate.com/docs/workflows/deployment for more information. +For information on how deployment works, see +[Vortex Deployment Documentation](https://www.vortextemplate.com/docs/deployment). -## Workflow +[//]: # (#;< HOSTING_ACQUIA) -1. Code is authored on a local machine by a developer. -2. Once the code is ready, it is pushed to GitHub. A pull request needs to be - opened for this code change. -3. The CI "listens" for code changes and will start an automated build. -4. At the end of the build, when all tests have passed, the CI will trigger a - deployment to Lagoon. -5. Once deployed, a PR environment will appear with a PR name. The database will - be taken from production environment. - All pending update hooks and other deployment operations will run during - deployment. +## Hosting provider -Once PR is closed, the environment will be automatically removed. +This project is hosted on [Acquia Cloud](https://www.acquia.com/products/drupal-cloud). -[//]: # (#;< HOSTING_ACQUIA) +See [Acquia hosting documentation](https://www.vortextemplate.com/docs/hosting/acquia) +for setup and configuration details. + +### Deployment workflow -GitHub is a primary code repository for this project (aka "source repository"). -Acquia Cloud is a hosting provider for this project and it also has a git -repository (aka "destination repository"). - -The website gets deployed using artifact built on CI and pushed to Acquia Cloud. - -There are 2 types of deployments: feature branches and release tags. They are -exactly the same except for the resulting branch name on Acquia Cloud (see -below). - -## Setup - -1. Create a Deployer user (deployer@yourcompany.com) account in Acquia. -2. Add this user to Acquia Cloud application with a role that allows to push - code and use Cloud API. -3. Login with Deployer user and go to Acquia Cloud UI->Account->Credentials-> - Copy email and key from section "Cloud API". -4. SSH into non-production server and run `drush ac-api-login`. Enter copied - email and key when prompted. This will store credentials - to `$HOME/.acquia/cloudapi.conf`and they will not need to be entered again. - This allows to use Cloud API drush commands within hooks. -5. Create SSH key (use `deployer+yourproject@yourcompany.com` as an email to - distinguish SSH keys) and add it to this user. This key cannot be re-used - between projects! -6. Login to CircleCI, go to Settings->SSH Permissions->Add SSH Key and paste * - private* key. This allows to push the code from CI to Acquia git repository. -7. Copy SHH key fingerprint (looks - like `16:02:e3:ca:33:04:82:58:e8:e9:3e:5d:82:17:86:b1`) and replace it - inside `.circleci/config.yml`. - -## Deployment workflow - -1. Developer updates DB in the Acquia Cloud environment by copying PROD database - to required environment. -2. Developer pushes code update to the GitHub branch. -3. CI system picks-up the update and does the following: -4. Builds a website using production DB. -5. Runs code standard checks and Behat tests on the built website. -6. Creates a deployment artifact (project files to be pushed to Acquia Cloud +1. Code is pushed to GitHub (source repository). +2. CI builds and tests the code. +3. On success, CI builds an artifact and pushes to Acquia Cloud (destination repository). -7. Pushes created artifact to the Acquia Cloud repository: - - for feature-based branches (i.e. `feature/ABC-123` or `bugfix/ABC-123`) - the code is pushed to the branch with exactly the same name. - - for release deployments, which are tag-based (i.e. `0.1.4`), the code is - pushed to the branch `deployment/[tag]` (i.e. `deployment/0.1.4`). -8. Acquia Cloud picks up recent push to the repository and - runs [post code update hooks](hooks/dev/post-code-update) on the environments - where code is already deployed. - OR -9. If the branch has not been deployed into any Acquia Cloud environment yet and - the developer starts the deployment, Acquia Cloud - runs [post code deploy hooks](hooks/dev/post-code-deploy) on the environment - where code is being deployed. - -### Release outcome - -1. Release branch exists as `deployment/X.Y.Z` in remote GitHub repository. -2. Release tag exists as `X.Y.Z` in remote GitHub repository. -3. The `HEAD` of the `main` branch has `X.Y.Z` tag assigned. -4. The hash of the `HEAD` of the `main` branch exists in the `develop` branch. - This is to ensure that everything pushed to `main` exists in `developed` (in - case if `main` had any hot-fixes that not yet have been merged to `develop`). -5. There are no PRs in GitHub related to releases. -6. Release branch is available on Acquia Cloud as `deployment/X.Y.Z` branch. - Note: we are building release branches on Acquia Cloud out of tags in GitHub. -7. Release branch `deployment/X.Y.Z` is deployed into PROD environment. Note: we - are NOT deploying tags to Acquia Cloud PROD. - -### Important - -Since Acquia Cloud becomes a destination repository, the following rules MUST be -followed by all developers: - -1. There should be no direct access to Acquia Cloud repository for anyone except - for project Technical Lead and Deployer user. -2. There should be no pushes to Acquia Cloud repository. -3. There may be `main` or `develop` branch in Acquia Cloud repository. -4. Technical Lead is expected to regularly cleanup `feature/*` and `bugfix/*` - branches in Acquia Cloud repository. +4. Acquia Cloud runs deployment hooks. + +### Branch naming on Acquia Cloud + +- Feature branches (`feature/ABC-123`) → same name on Acquia +- Release tags (`0.1.4`) → `deployment/0.1.4` branch on Acquia + +### Important rules + +- No direct pushes to Acquia Cloud repository. +- Only Technical Lead and Deployer user should have access to Acquia repository. +- Technical Lead should regularly clean up `feature/*` and `bugfix/*` branches. [//]: # (#;> HOSTING_ACQUIA) [//]: # (#;< HOSTING_LAGOON) -## Database refresh in Lagoon environments +## Hosting provider + +This project is hosted on [Lagoon](https://www.amazee.io/lagoon). + +See [Lagoon hosting documentation](https://www.vortextemplate.com/docs/hosting/lagoon) +for setup and configuration details. -To refresh the database in the existing Lagoon environment with the database from -production environment, run: +### Database refresh + +To refresh the database in an existing Lagoon environment with production data: ```bash VORTEX_DEPLOY_BRANCH= VORTEX_DEPLOY_ACTION=deploy_override_db ahoy deploy ``` [//]: # (#;> HOSTING_LAGOON) + +## Project-specific configuration + + diff --git a/docs/faqs.md b/docs/faqs.md index b9ba02cc1..03f0de6c2 100644 --- a/docs/faqs.md +++ b/docs/faqs.md @@ -1,176 +1,8 @@ # FAQs -## How to know which commands are available? +For common questions and answers, see +[Vortex FAQs](https://www.vortextemplate.com/docs/development/faqs). -```bash -ahoy help -``` +## Project-specific FAQs -## How to pass CLI arguments to commands? - -```bash -ahoy mycommand -- myarg1 myarg2 --myoption1 --myoption2=myvalue -``` - -## How to clear Drupal cache? - -```bash -ahoy drush cr -``` - -## How to login to a Drupal site? - -```bash -ahoy login -``` - -## How to connect to the database? - -If you have [Sequel Ace](https://sequel-ace.com/): - -```bash -ahoy db -``` - -Otherwise: - -1. Run `ahoy info` and grab the DB host port number. -2. Use these connection details: - -- Host: `127.0.0.1` -- Username: `drupal` -- Password: `drupal` -- Database: `drupal` -- Port: the port from step 1 - -## How to use Xdebug? - -1. Run `ahoy debug`. -2. Enable listening for incoming debug connections in your IDE. -3. If required, provide server URL to your IDE as it appears in the browser. -4. Enable Xdebug flag in the request coming from your web browser (use one of - the extensions or add `?XDEBUG_SESSION_START=1` to your URL). -5. Set a breakpoint in your IDE and perform a request in the web browser. - -Use the same commands to debug CLI scripts. - -To disable, run `ahoy up`. - -See https://www.vortextemplate.com/docs/tools/xdebug for more details. - -[//]: # (#;< TOOL_BEHAT) - -## How to use Xdebug on Behat scripts? - -1. Enable debugging: `ahoy debug` -2. Enter CLI container: `ahoy cli` -3. Run Behat tests: - -```bash -vendor/bin/behat --xdebug path/to/test.feature -``` - -[//]: # (#;> TOOL_BEHAT) - -## What should I do to switch to a "clean" branch environment? - -Provided that your stack is already running: - -1. Switch to your branch -2. `composer install` -3. `ahoy provision` - -You do not need to rebuild the full stack using `ahoy build` every -time you switch branches. `ahoy provision` will update the environment -to match the current branch. - -However, sometimes you would want to have an absolutely clean environment - in -that case, use `ahoy build`. - -## How to just import a database? - -Provided that your stack is already running: - -```bash -ahoy import-db - -ahoy import-db .data/db_custom.sql -``` - -## How to add Drupal modules - -```bash -composer require drupal/module_name -``` - -## How to add patches for Drupal modules - -1. Add `title` to patch on https://drupal.org to the `patches` array in `extra` - section in `composer.json`. - - ```json - "extra": { - "patches": { - "drupal/somepackage": { - "Remote patch description": "https://www.drupal.org/files/issues/issue.patch" - "Local patch description": "patches/package-description.patch" - } - } - } - ``` - -2. Run - - ```bash - composer require drupal/somepackage - ``` - -See https://www.vortextemplate.com/docs/workflows/development#working-with-composer-packages - -## What should I do when Composer blocks package installation due to security vulnerabilities? - -Starting with Composer 2.9.0, Composer can automatically block the installation -or update of packages with known security vulnerabilities. If you encounter this -issue, you have several options: - -1. **Update the affected packages**: Try updating to newer versions that don't - have known vulnerabilities: `composer update vendor/package-name` -2. **Review the vulnerability**: Run `composer audit` to see details about the - security issues and determine if they affect your project. -3. **Adjust security settings**: If you need to proceed with installation despite - warnings (for example, if no secure version is available or the vulnerability - doesn't affect your use case), you can configure the `audit.block-insecure` - setting in your `composer.json`. - -See the [Composer configuration documentation](https://www.vortextemplate.com/docs/drupal/composer#config) -for detailed information about the `audit` configuration option and guidance on -choosing the right security settings for your project. - -## How to set a custom maintenance theme? - -To set a custom theme for Drupal's maintenance mode (when the site is offline -for updates), set the `DRUPAL_MAINTENANCE_THEME` environment variable: - -```bash -# In .env file -DRUPAL_MAINTENANCE_THEME=my_custom_theme -``` - -This theme will be used when Drupal is in maintenance mode. If -`DRUPAL_MAINTENANCE_THEME` is not set, the system will fall back to using the -value of `DRUPAL_THEME`. - -The maintenance theme should be a valid Drupal theme that is already installed -and enabled on your site. - -[//]: # (#;< TOOL_BEHAT) - -## Behat tests with `@javascript` tag sometimes get stuck - -Behat tests with `@javascript` tag sometimes get stuck for about 10min then -fail. -The Chrome container randomly get stuck for an unknown reason. - -Restart the Chrome container: `docker compose restart chrome` - -[//]: # (#;> TOOL_BEHAT) + diff --git a/docs/releasing.md b/docs/releasing.md index 73c167fb8..8a1eebd24 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -1,60 +1,48 @@ # Releasing -[git-flow](https://danielkummer.github.io/git-flow-cheatsheet/) is used to -manage releases. - -Note: after completing the release, commits must be manually pushed -from `main` to `production` branch. - -Refer to https://www.vortextemplate.com/docs/workflows/releasing for more information. +For information on how releasing works, see +[Vortex Releasing Documentation](https://www.vortextemplate.com/docs/releasing). ## Release outcome +After a successful release: + 1. Release branch exists as `release/X.Y.Z` in GitHub repository. 2. Release tag exists as `X.Y.Z` in GitHub repository. 3. The `HEAD` of the `main` branch has `X.Y.Z` tag. 4. The hash of the `HEAD` of the `main` branch exists in the `develop` branch. - This is to ensure that everything pushed to `main` exists in `develop` (in - case if `main` had any hot-fixes that not yet have been merged - to `develop`). 5. There are no PRs in GitHub related to the release. 6. The hash of the `HEAD` of the `production` branch matches the hash of the `HEAD` of `main` branch. [//]: # (#;< VERSION_RELEASE_SCHEME_SEMVER) -## Version Number - Semantic Versioning (SemVer) - -Release versions are numbered according to [Semantic Versioning](https://semver.org/). +## Version scheme -Given a version number `X.Y.Z`: +This project uses [Semantic Versioning](https://semver.org/) (`X.Y.Z`): -- `X` = Major release version. No leading zeroes. -- `Y` = Minor Release version. No leading zeroes. -- `Z` = Hotfix/patch version. No leading zeroes. +- `X` = Major release version +- `Y` = Minor release version +- `Z` = Hotfix/patch version -Examples: - -- Correct: `0.1.0`, `1.0.0` , `1.0.1` , `1.0.10` -- Incorrect: `0.1` , `1` , `1.0` , `1.0.01` , `1.0.010` +Examples: `0.1.0`, `1.0.0`, `1.0.1`, `1.0.10` [//]: # (#;> VERSION_RELEASE_SCHEME_SEMVER) [//]: # (#;< VERSION_RELEASE_SCHEME_CALVER) -## Version Number - Calendar Versioning (CalVer) +## Version scheme -Release versions are numbered according to [CalVer Versioning](https://calver.org/). +This project uses [Calendar Versioning](https://calver.org/) (`YY.M.Z`): -Given a version number `YY.M.Z`: +- `YY` = Short year +- `M` = Short month +- `Z` = Hotfix/patch version -- `YY` = Short year. No leading zeroes. -- `M` = Short month. No leading zeroes. -- `Z` = Hotfix/patch version. No leading zeroes. +Examples: `25.1.0`, `25.11.1`, `25.1.10`, `25.10.1` -Examples: +[//]: # (#;> VERSION_RELEASE_SCHEME_CALVER) -- Correct: `25.1.0`, `25.11.1` , `25.1.10`, `25.10.1`, `9.12.0` -- Incorrect: `25.0.0`, `2025.1.1` , `25` , `25.1.00` , `25.01.0`, `25.0.0`, `01.1.0` +## Project-specific configuration -[//]: # (#;> VERSION_RELEASE_SCHEME_CALVER) + diff --git a/docs/testing.md b/docs/testing.md index 0ffbd16ad..65a75415c 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1,3 +1,235 @@ # Testing -Refer to https://www.vortextemplate.com/docs/workflows/testing for more information. +This document describes **what** testing conventions and agreements apply to +this project. + +[//]: # (#;< TOOL_PHPUNIT) + +## PHPUnit conventions + +Unit, Kernel, Functional tests. + +See [documentation](https://www.vortextemplate.com/docs/development/phpunit) +on how to run tests, configure environment variables and code coverage, and use +test reports in continuous integration pipeline. + +### Test class structure + +All PHPUnit tests must follow this structure: + +```php +assertEquals('expected', $result); + } + +} +``` + +### Base test classes + +- **Unit** - `Drupal\Tests\UnitTestCase` - Testing isolated PHP classes +- **Kernel** - `Drupal\KernelTests\KernelTestBase` - Testing with database/services +- **Functional** - `Drupal\Tests\BrowserTestBase` - Testing with full browser + +### Test data conventions + +- **Always prefix test content**: `[TEST] Node Title` +- **Use data providers**: For testing multiple input/output combinations + - Must be a public static method + - Must follow naming convention `dataProvider` + - Must be placed after the test method it provides data for. +- **Use unique identifiers**: Include test class or method name in test data + +### Data providers + +Always use data providers for testing multiple input/output combinations: + +```php +/** + * Test my function with various inputs. + * + * @dataProvider dataProviderMyFunction + */ +public function testMyFunction(string $input, string $expected): void { + $this->assertEquals($expected, my_function($input)); +} + +/** + * Data provider for testMyFunction. + */ +public static function dataProviderMyFunction(): array { + return [ + 'empty string' => ['', ''], + 'simple string' => ['hello', 'HELLO'], + 'with numbers' => ['test123', 'TEST123'], + ]; +} +``` + +### Testing services (Kernel tests) + +For Kernel tests that need Drupal services: + +```php +installEntitySchema('node'); + $this->installEntitySchema('user'); + $this->myService = $this->container->get('my_module.my_service'); + } + + /** + * Test service method. + */ + public function testServiceMethod(): void { + $result = $this->myService->doSomething(); + $this->assertNotNull($result); + } + +} +``` + +[//]: # (#;> TOOL_PHPUNIT) + +[//]: # (#;< TOOL_BEHAT) + +## Behat conventions + +BDD end-to-end tests. + +See [documentation](https://www.vortextemplate.com/docs/development/behat) +on how to run Behat tests, configure environment variables, and use test reports +in continuous integration pipeline. + +### User story format + +All Behat features must follow this format: + +```gherkin +Feature: [Feature name] + + As a [user type] + I want to [action/goal] + So that [benefit/outcome] +``` + +### Standard user types + +Use these consistent user type descriptions: + +```gherkin +As a site visitor # Anonymous users +As a site administrator # Admin users +As a content editor # Content management users +As a authenticated user # Logged-in users +``` + +### Test data conventions + +- **Always prefix test content**: `[TEST] Page Title` +- **Use numbered patterns**: `[TEST] Topic 1`, `[TEST] Topic 2` +- **Avoid real names**: Don't use "Workshop" or "Training" +- **Be descriptive**: `[TEST] Event with All Fields` + +### Example feature file + +```gherkin +Feature: Homepage + + As a site visitor + I want to access the homepage + So that I can view the main landing page and navigate the site + + Scenario: View homepage content + Given I am on the homepage + Then I should see "[TEST] Welcome Message" + And I should see "About Us" in the "navigation" region +``` + +### Content type testing process + +When creating comprehensive tests for content types: + +1. Analyze configuration first + + - Check `config/default/field.field.node.[type].*.yml` + - Review `core.entity_view_display.node.[type].default.yml` + - Identify visible vs hidden fields + +2. Create supporting entities + + ```gherkin + Background: + Given "tags" terms: + | name | + | [TEST] Topic 1 | + | [TEST] Topic 2 | + + And the following media "image" exist: + | name | + | [TEST] Featured Image 1 | + ``` + +3. Test all visible fields + + ```gherkin + Scenario: View complete content with all fields + Given "page" content: + | title | body | field_tags | + | [TEST] Complete Page Test | [TEST] This is the body text. | [TEST] Topic 1 | + When I visit "[TEST] Complete Page Test" + Then I should see "[TEST] Complete Page Test" + And I should see "[TEST] This is the body text." + And I should see "[TEST] Topic 1" + ``` + +[//]: # (#;> TOOL_BEHAT) diff --git a/scripts/vortex/notify-jira.sh b/scripts/vortex/notify-jira.sh index d9ab4065e..6baa80a6b 100755 --- a/scripts/vortex/notify-jira.sh +++ b/scripts/vortex/notify-jira.sh @@ -24,7 +24,7 @@ VORTEX_NOTIFY_JIRA_USER_EMAIL="${VORTEX_NOTIFY_JIRA_USER_EMAIL:-}" # JIRA notification API token. # -# @see https://www.vortextemplate.com/docs/workflows/notifications#jira +# @see https://www.vortextemplate.com/docs/deployment/notifications#jira VORTEX_NOTIFY_JIRA_TOKEN="${VORTEX_NOTIFY_JIRA_TOKEN:-}" # JIRA notification git branch name (used for issue extraction). diff --git a/scripts/vortex/notify-newrelic.sh b/scripts/vortex/notify-newrelic.sh index 76c29e76c..ed7682b9e 100755 --- a/scripts/vortex/notify-newrelic.sh +++ b/scripts/vortex/notify-newrelic.sh @@ -26,7 +26,7 @@ VORTEX_NOTIFY_NEWRELIC_PROJECT="${VORTEX_NOTIFY_NEWRELIC_PROJECT:-${VORTEX_NOTIF # 5. The key format is: NRAK-XXXXXXXXXXXXXXXXXXXXXX # # @see https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#user-key -# @see https://www.vortextemplate.com/docs/workflows/notifications#new-relic +# @see https://www.vortextemplate.com/docs/deployment/notifications#new-relic VORTEX_NOTIFY_NEWRELIC_USER_KEY="${VORTEX_NOTIFY_NEWRELIC_USER_KEY:-${NEWRELIC_USER_KEY:-}}" # New Relic notification deployment label (human-readable identifier for display). diff --git a/scripts/vortex/notify-slack.sh b/scripts/vortex/notify-slack.sh index 12d2cdebd..1b0d72e71 100755 --- a/scripts/vortex/notify-slack.sh +++ b/scripts/vortex/notify-slack.sh @@ -32,7 +32,7 @@ VORTEX_NOTIFY_SLACK_EVENT="${VORTEX_NOTIFY_SLACK_EVENT:-${VORTEX_NOTIFY_EVENT:-p # Slack notification webhook URL. # The incoming Webhook URL from your Slack app configuration. -# @see https://www.vortextemplate.com/docs/workflows/notifications#slack +# @see https://www.vortextemplate.com/docs/deployment/notifications#slack VORTEX_NOTIFY_SLACK_WEBHOOK="${VORTEX_NOTIFY_SLACK_WEBHOOK:-}" # Slack notification target channel (optional, overrides webhook default).