Skip to content

[#2096] Updated to use cweagans/composer-patches v2. #2099

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AlexSkrypnyk merged 1 commit into from
Nov 14, 2025
Merged

[#2096] Updated to use cweagans/composer-patches v2. #2099

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 43 additions & 16 deletions .vortex/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -330,13 +330,33 @@ The installer uses a **baseline + diff** system for managing test fixtures:

### Updating Fixtures

**Critical**: Use the proper fixture update mechanism:
**CRITICAL - Use the Unified Ahoy Command**:

The correct way to update fixtures is to use the unified `ahoy update-fixtures` command from the `.vortex` directory:

```bash
cd .vortex/installer
cd .vortex

# Update all fixtures
UPDATE_FIXTURES=1 composer test
# This is the CORRECT way to update all fixtures
ahoy update-fixtures
```

**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_FIXTURES=1` commands** - the `ahoy update-fixtures` 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_FIXTURES=1 ./vendor/bin/phpunit --filter "testInstall.*baseline"
Expand All @@ -352,9 +372,10 @@ UPDATE_FIXTURES=1 ./vendor/bin/phpunit --filter 'testInstall.*"services.*no.*cla

### Fixture Update Process

1. **Baseline First**: Update baseline fixtures first
2. **Scenario Diffs**: Run individual scenario tests to update their diffs
3. **Validation**: Verify tests pass without UPDATE_FIXTURES flag
1. **Use ahoy update-fixtures**: 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_FIXTURES flag

## Script Output Formatters

Expand Down Expand Up @@ -397,7 +418,7 @@ info "Finished executing example operations in non-production environment."

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**: Use `UPDATE_FIXTURES=1` process
3. **Update Installer Fixtures**: Run `ahoy update-fixtures` from `.vortex/` directory

### Provision Script BATS Test Logic

Expand Down Expand Up @@ -712,12 +733,13 @@ Each system:

### 2. Installer System (.vortex/installer/)

**Fixture Updates Can Be Finicky**:
**Fixture Updates**:

- The `UPDATE_FIXTURES=1` mechanism can have defects
- Try updating baseline first, then individual scenarios
- Use filtered test runs for specific scenarios
- **Use `ahoy update-fixtures`** 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_FIXTURES=1` commands can be used

**Handler Development**:

Expand Down Expand Up @@ -771,10 +793,13 @@ yarn test --updateSnapshot # Update component snapshots
**Fixture Update Issues**:

```bash
# Try baseline first
UPDATE_FIXTURES=1 ./vendor/bin/phpunit --filter "testInstall.*baseline"
# RECOMMENDED: Use the unified command
cd .vortex
ahoy update-fixtures

# Then individual scenarios
# ALTERNATIVE: Manual updates for specific scenarios
cd .vortex/installer
UPDATE_FIXTURES=1 ./vendor/bin/phpunit --filter "testInstall.*baseline"
UPDATE_FIXTURES=1 ./vendor/bin/phpunit --filter 'testInstall.*"scenario_name"'

# Check for test timeouts - increase if needed
Expand Down Expand Up @@ -1209,7 +1234,9 @@ $this->cmd('ahoy export-db', '! Containers are not running.', arg: $args);
**Installer System** (`.vortex/installer/`):

- **CRITICAL**: NEVER directly modify files under `.vortex/installer/tests/Fixtures/`
- These are test fixtures that must be updated via `UPDATE_FIXTURES=1` mechanism
- These are test fixtures that must be updated via `ahoy update-fixtures` command from `.vortex/` directory
- The unified `ahoy update-fixtures` command handles all fixture updates automatically
- For debugging, manual `UPDATE_FIXTURES=1` commands can be used from `.vortex/installer/`
- Always test with baseline scenario first, then individual scenarios
- Preserve handler execution order and batching patterns

Expand Down
24 changes: 10 additions & 14 deletions .vortex/docs/content/drupal/composer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,18 +79,10 @@ The [`repositories`](https://getcomposer.org/doc/04-schema.md#repositories)
section defines custom package repositories, essential for accessing packages
outside the default Packagist repository.

See [Working with packages](../workflows/development#working-with-composer-packages) for more information on
how to provide custom and override existing packages in your project.

- [`drupal`](https://www.drupal.org/docs/develop/using-composer/using-packagesdrupalorg):
Serves as the official source for Drupal modules, themes, and distributions.
It's crucial for a Drupal project using Composer, as it allows access to
Drupal-specific packages not available on Packagist.
- [`asset-packagist`](https://asset-packagist.org/): Enables the installation of
Bower and NodeJs packages via Composer. This is especially important for Drupal
projects needing front-end libraries and tools, bridging the gap between
Composer's PHP-centric ecosystem and the broader world of front-end package
management.

### `require`

Expand All @@ -104,9 +96,11 @@ specifies the essential packages and libraries your project needs.
install packages to the correct location based on the specified package type
such as `drupal-module`, `drupal-theme`, `drupal-profile`, etc.
- [`cweagans/composer-patches`](https://github.com/cweagans/composer-patches):
Allows applying patches to Composer packages, useful for incorporating fixes
not yet in official releases.
See [Working with packages](../workflows/development#patching) for more
Enables git-based patching of Composer packages, useful for incorporating fixes
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.
- `drupal/admin_toolbar`, `drupal/clamav`, `drupal/coffee`, etc. - Drupal
modules that provide various site administration and development helping
Expand Down Expand Up @@ -266,9 +260,11 @@ a source of custom configuration for various packages. These packages read
settings from this section to tailor their behavior according to the specific
needs and structure of your Drupal project.

- [`composer-exit-on-patch-failure`](https://github.com/cweagans/composer-patches):
This setting, when enabled, causes Composer to exit if a patch from
the `cweagans/composer-patches` plugin fails to apply.
- **patches.lock.json**: Automatically generated by `cweagans/composer-patches`
v2.x. This file contains patch metadata and SHA-256 checksums, and must be
committed to version control (like `composer.lock`). It ensures reproducible
builds across teams and CI/CD environments by verifying patch integrity and
making the patch state explicit and trackable.
- [`drupal-scaffold`](https://www.drupal.org/docs/develop/using-composer/using-drupals-composer-scaffold):
This setting controls which files should be scaffolded:
- `locations`: Specifies the location of the web root (the directory
Expand Down
92 changes: 83 additions & 9 deletions .vortex/docs/content/workflows/development.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,19 +217,93 @@ To override package installation paths, modify `composer.json`:

### Patching

If you need to apply patches to included dependencies, use the `composer-patches` plugin. Add the patch definition in `composer.json` under the `extra.patches` section:
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.

```json
"extra": {
"patches": {
"drupal/foobar": {
"Patch description": "URL or local path to patch"
:::tip

For official documentation, visit: [Composer Patches Recommended Workflows](https://docs.cweagans.net/composer-patches/usage/recommended-workflows/)

:::

#### Understanding `patches.lock.json`

Composer Patches v2.x automatically generates a `patches.lock.json` file that contains:

- Patch metadata (URLs, descriptions, target packages)
- SHA-256 checksums for patch verification

**This file must be committed to version control** (like `composer.lock`).

**Benefits:**

- Ensures reproducible builds across teams and CI/CD environments
- Verifies patch integrity with checksums
- Prevents "works on my machine" issues with patches
- Makes the patch state explicit and trackable

#### Adding a New Patch

1. Define the patch in `composer.json` under `extra.patches`:

```json
"extra": {
"patches": {
"drupal/foobar": {
"Fix for issue #123": "https://www.drupal.org/files/issues/fix-123.patch"
}
}
}
}
```
```

2. Regenerate `patches.lock.json`:

```bash
composer patches-relock
```

3. Remove and reinstall patched packages:

```bash
composer patches-repatch
```

:::warning
`composer patches-repatch` removes patched dependencies from `vendor/` and reinstalls them. Ensure you have no unsaved changes in those directories.
:::
Comment on lines +270 to +272
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Nov 14, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

Clarify the scope of "unsaved changes" in the patches-repatch warning.

The warning appropriately flags that composer patches-repatch removes and reinstalls dependencies, but "unsaved changes in those directories" could be misinterpreted. Consider adding a clarification that this refers to uncommitted modifications to vendored dependencies (a rare but important distinction).

Suggested clarification:

 :::warning
-`composer patches-repatch` removes patched dependencies from `vendor/` and reinstalls them. Ensure you have no unsaved changes in those directories.
+`composer patches-repatch` removes patched dependencies from `vendor/` and reinstalls them. Ensure you have no uncommitted local modifications to these vendored packages.
 :::
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
:::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 uncommitted local modifications to these vendored packages.
:::
🤖 Prompt for AI Agents 
.vortex/docs/content/workflows/development.mdx around lines 270 to 272: the
warning "Ensure you have no unsaved changes in those directories" is ambiguous;
update the text to clarify it means uncommitted or locally modified files in
vendor/ (vendored dependencies), not unrelated unsaved editor buffers—replace or
append a brief clarification stating it refers specifically to uncommitted/local
modifications to files under vendor/ (or patches managed by composer) so users
understand to commit or stash those changes before running composer
patches-repatch.


4. Update `composer.lock`:

```bash
composer update --lock
```

#### Removing a Patch

1. Delete the patch definition from `composer.json`

2. Regenerate `patches.lock.json`:

```bash
composer patches-relock
```

3. Manually delete the affected dependency:

```bash
rm -rf vendor/drupal/foobar
```

4. Reinstall without the patch:

```bash
composer patches-repatch
```

5. Update `composer.lock`:

Run `composer update drupal/foobar` after adding patches to apply them.
```bash
composer update --lock
```

## Resetting the codebase

Expand Down
1 change: 1 addition & 0 deletions .vortex/docs/cspell.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@
"ddev",
"dealerdirect",
"drevops",
"drupalcode",
"drush",
"ergebnis",
"gherkinlint",
Expand Down
43 changes: 20 additions & 23 deletions .vortex/installer/composer.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,31 +18,31 @@
},
"require": {
"php": ">=8.3",
"alexskrypnyk/file": "^0.13",
"alexskrypnyk/file": "^0.13.1",
"alexskrypnyk/str2name": "^1.4",
"composer/composer": "^2.8",
"cweagans/composer-patches": "^1.7",
"czproject/git-php": "^4.3",
"laravel/prompts": "^0.3.7",
"nikic/iter": "^2.4",
"sebastian/diff": "*",
"symfony/console": "^7.3",
"symfony/filesystem": "^7.2",
"symfony/yaml": "^7.2"
"composer/composer": "^2.8.12",
"cweagans/composer-patches": "^2",
"czproject/git-php": "^4.5",
"laravel/prompts": "^0.3.8",
"nikic/iter": "^2.4.1",
"sebastian/diff": "^7.0",
"symfony/console": "^7.3.6",
"symfony/filesystem": "^7.3.6",
"symfony/yaml": "^7.3.5"
},
"require-dev": {
"alexskrypnyk/phpunit-helpers": "^0.13",
"bamarni/composer-bin-plugin": "^1.8",
"dealerdirect/phpcodesniffer-composer-installer": "^1",
"bamarni/composer-bin-plugin": "^1.8.2",
"dealerdirect/phpcodesniffer-composer-installer": "^1.1.2",
"drevops/phpcs-standard": "^0.2",
"drupal/coder": "^8.3",
"ergebnis/composer-normalize": "^2.45",
"laravel/serializable-closure": "^2.0",
"mockery/mockery": "^1.6",
"phpstan/phpstan": "^2",
"phpunit/phpunit": "^12",
"rector/rector": "^2",
"symfony/finder": "^7.2"
"drupal/coder": "^8.3.31",
"ergebnis/composer-normalize": "^2.48.2",
"laravel/serializable-closure": "^2.0.6",
"mockery/mockery": "^1.6.12",
"phpstan/phpstan": "^2.1.31",
"phpunit/phpunit": "^12.4.2",
"rector/rector": "^2.2.7",
"symfony/finder": "^7.3.5"
},
"repositories": [
{
Expand Down Expand Up @@ -77,9 +77,6 @@
},
"sort-packages": true
},
"extra": {
"composer-exit-on-patch-failure": true
},
"scripts": {
"build": [
"@composer bin box require --dev humbug/box",
Expand Down
Loading