Merge branch release-2.18.12 into main

Author: ws2-release-bot

INSTALL-INSTRUCTIONS.md

@@ -25,7 +25,7 @@ To avoid dependency clashes, remove the root-level composer.lock file.
 
 ## Temporarily remove patches
 
-- The `composer.patches.json` file at the root of your repository needs to be adjusted. Compare it with the version located in `docroot/profiles/contrib/webspark/sample-webspark-dependencies/patches.webspark.json` and remove any of the items that exist in that file from the root `composer.patches.json` file.
+- The `composer.patches.json` file at the root of your repository needs to be adjusted. Compare it with the version located in `docroot/profiles/contrib/webspark/webspark-dependencies-source/patches.webspark.json` and remove any of the items that exist in that file from the root `composer.patches.json` file.
 - Then, take what is remaining, copy it, and paste it into a temporary text file.
 - Your root `composer.patches.json` file should basically be empty now, leaving only the following content:
 
@@ -45,8 +45,8 @@ ddev composer require asuwebplatforms/webspark:^2.16.4 wikimedia/composer-merge-
 
 ## Add custom-dependencies directory (if it doesn't exist)
 
-- If your repository does not already have a `custom-dependencies` directory at the root level, you will need to create it. You can do so by copying the `sample-custom-dependencies` directory from this profile and pasting it into the root of your repository. Then, rename the copied directory from `sample-custom-dependencies` to `custom-dependencies`.
-- If you already have a `custom-dependencies` directory, you should ensure that its contents include everything that is in the `sample-custom-dependencies` directory, making adjustments as necessary.
+- If your repository does not already have a `custom-dependencies` directory at the root level, you will need to create it. You can do so by copying the `custom-dependencies-source` directory from this profile and pasting it into the root of your repository. Then, rename the copied directory from `custom-dependencies-source` to `custom-dependencies`.
+- If you already have a `custom-dependencies` directory, you should ensure that its contents include everything that is in the `custom-dependencies-source` directory, making adjustments as necessary.
   - If you have a `scripts` directory in your existing `custom-dependencies` folder, please delete it.
   - If you have a `patches` directory in your existing `custom-dependencies` folder, you can keep it, if it has local patch files that you need for your site.
 
@@ -55,8 +55,8 @@ For more information about the `custom-dependencies` folder and its purpose, ple
 ## Add webspark-dependencies directory
 
 - If your repository contains an `upstream-configuration` directory at the root level, you will need to delete it. This directory is no longer needed with the newly consolidated webspark profile (as of Webspark 2.16.4).
-- Copy the `sample-webspark-dependencies` directory from this profile and paste it into the root of your repository.
-- Rename the copied directory from `sample-webspark-dependencies` to `webspark-dependencies`.
+- Copy the `webspark-dependencies-source` directory from this profile and paste it into the root of your repository.
+- Rename the copied directory from `webspark-dependencies-source` to `webspark-dependencies`.
 - Edit the namespace declarations in the two PHP files within the `scripts` directory to be `WebsparkCustomScripts` instead of `SampleWebsparkCustomScripts` and save them.
 
 For more information about the `webspark-dependencies` folder and its purpose, please refer to the README file located within that directory.

README.md

@@ -19,3 +19,120 @@ webspark distribution.
 ## Requirements
 
 Drupal 10 or higher
+
+## Dependency sync process
+
+The Webspark profile is installed into many downstream repositories via Composer.
+A handful of files that Webspark relies on cannot live inside the profile itself —
+they have to exist at the **root** of the consuming repository. To deliver these files without causing merge conflicts on
+every upstream update, the profile ships them inside two source folders and
+syncs/distributes them out to the repository root automatically when you run
+`composer install` or `composer update`.
+
+This section documents that process so developers understand what happens, why, and
+which files they should and should not edit.
+
+### The two source folders
+
+Both folders live inside the profile and are the **source of truth**. They are
+copied out to the repository root, where they are renamed (the `-source` suffix is
+dropped):
+
+| Profile source folder           | Root destination          | How it gets there                                            |
+|---------------------------------| ------------------------- | ------------------------------------------------------------ |
+| `webspark-dependencies-source/` | `webspark-dependencies/`  | Automatically rsynced on every `composer install`/`update`.  |
+| `custom-dependencies-source/`   | `custom-dependencies/`    | Copied **once** by hand during install, then owned by the site. |
+
+- `webspark-dependencies/` is **upstream-owned**. It is overwritten on every Composer
+  run, so do **not** edit anything in it at the individual site level — your changes will be lost. Upstream changes belong in
+  `webspark-dependencies-source/`.
+- `custom-dependencies/` is **site-owned**. It holds your site-specific
+  `composer.json` and `patches.custom.json` files, and is registered as a
+  Composer `path` repository (`asu/custom-dependencies`). Manage it with
+  `composer custom-require` / `composer custom-remove` (see
+  `custom-dependencies/README.md`).
+
+### Composer hook wiring
+
+The root `composer.json` `scripts` section wires the process into Composer's
+lifecycle:
+
+  - `WebsparkCustomScripts\ComposerScripts::writeComposerPatchFile` — merges
+    `webspark-dependencies/patches.webspark.json` (upstream) and
+    `custom-dependencies/patches.custom.json` (site) into the root
+    `composer.patches.json`. That root file is generated; edit the source patch
+    files instead.
+- **`post-update-cmd`** runs after `composer update` and **`post-install-cmd`** runs
+  after `composer install`. Both start by running the
+  `docroot/profiles/contrib/webspark/sync-dependencies` script (the actual file sync,
+  described below), then perform a couple of follow-up steps:
+  - After an update, `ComposerScripts::postUpdate` merges the ASUAwesome and Font
+    Awesome icon lists for the renovation theme. After an install,
+    `ComposerScripts::buildFrontend` compiles the renovation theme's frontend assets
+    (only in the `asufactory1` CI pipeline).
+  - Both then recreate the SimpleSAMLphp symlinks so the library can locate its
+    public files and configuration.
+
+The two Composer script classes are autoloaded from
+`webspark-dependencies/scripts/ComposerScripts.php` and
+`CustomComposerScripts.php` via the root `composer.json` `autoload.classmap`.
+
+### What `sync-dependencies` does
+
+`docroot/profiles/contrib/webspark/sync-dependencies` runs on every
+`composer install` / `composer update`. It is **local-only**: it is skipped when
+`AH_SITE_ENVIRONMENT` (Acquia Cloud) or `CI` is set, because those environments
+already have the synced files committed to the repository.
+
+When it runs locally it performs the following steps:
+
+1. **Rsync the source folder.** `rsync -avq --delete` copies
+   `webspark-dependencies-source/` to the root-level `webspark-dependencies/` directory. The `--delete` flag
+   means `webspark-dependencies/` is a faithful mirror of the source — anything not
+   in the source is removed.
+2. **Rewrite PHP namespaces.** In every synced `*.php` file the namespace
+   `SampleWebsparkCustomScripts` is rewritten to `WebsparkCustomScripts` (the
+   namespace the root `composer.json` autoloader expects).
+3. **Distribute the synced files to their final homes.** Files that were rsynced
+   into `webspark-dependencies/scripts/` are moved to where they actually need to
+   live for the repository to work, and the source copy under
+   `webspark-dependencies/scripts/` is deleted after each move:
+
+   | Synced source file                         | Final destination                          | Behavior                                                                                       |
+   | ------------------------------------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
+   | `scripts/pre-commit`                       | `.git/hooks/pre-commit`                    | Installs the hook, or merges the `asu_commit_check` function into an existing hook.            |
+   | `scripts/post-commit`                      | `.git/hooks/post-commit`                   | Installs the hook, or merges the `asu_post_commit_actions` function into an existing hook.     |
+   | `scripts/.prettierignore`                  | root `.prettierignore`                     | Copied to the repository root.                                                                 |
+   | `scripts/prettierrc.js`                    | root `.prettierrc.js`                      | Copied to the repository root.                                                                 |
+   | `scripts/.root-gitignore`                  | root `.gitignore`                          | Ensures the `/node_modules` and `!/package.json` rules exist (appends them if missing).        |
+   | `scripts/package.json`                     | root `package.json`                        | Creates the root `package.json`, or merges the `prettier` devDependency into an existing one.  |
+
+4. **Align `drupal/core-dev`.** `sync_core_dev` reads the installed
+   `drupal/core-recommended` version from `composer.lock` and adds/updates a matching
+   `drupal/core-dev` entry in the root `composer.json` `require-dev`.
+
+The files that remain in `webspark-dependencies/` after distribution are the ones
+that are referenced in place: the Composer scripts (`scripts/ComposerScripts.php`,
+`scripts/CustomComposerScripts.php`, `scripts/pre-autoload-check`) and
+`patches.webspark.json`.
+
+### What developers should / should not edit
+
+- **Upstream maintainers:** make changes in `webspark-dependencies-source/`
+  (and `custom-dependencies-source/`). These are the sources of truth that ship with
+  the profile.
+- **Site developers:**
+  - **Do not** edit `webspark-dependencies/` — it is regenerated on every Composer
+    run.
+  - **Do not** hand-edit the root `composer.patches.json` — it is generated by
+    merging the two patch source files.
+  - **Do** put site-specific dependencies and patches in `custom-dependencies/` using
+    `composer custom-require` / `composer custom-remove`.
+
+### Related documentation
+
+- `INSTALL-INSTRUCTIONS.md` — For first-time setup, including the one-time copy of
+  `custom-dependencies-source/` to root-level `custom-dependencies/` and the required root
+  `composer.json` configuration.
+- `UPDATE-INSTRUCTIONS.md` — How to update an existing Webspark site.
+- `custom-dependencies/README.md` — For managing site-specific dependencies and patches.

composer.json

@@ -39,7 +39,7 @@
         "drupal/layout_builder_restrictions": "2.19.0",
         "drupal/layout_builder_usage_reports": "1.0.2",
         "drupal/layout_section_classes": "1.5.0",
-        "drupal/linkit": "7.0.13",
+        "drupal/linkit": "7.0.15",
         "drupal/maxlength": "2.1.2",
         "drupal/media_library_form_element": "2.1.0",
         "drupal/metatag": "2.2.0",

sample-custom-dependencies/README.md custom-dependencies-source/README.mdsample-custom-dependencies/README.md renamed to custom-dependencies-source/README.md

@@ -1,5 +1,11 @@
 # Managing Custom Dependencies and Patches
 
+> 📖 This document covers managing site-specific dependencies and patches. For the
+> full end-to-end documentation of how Webspark syncs its root-level dependency files
+> (including how `custom-dependencies-source/` becomes `custom-dependencies/`), see the
+> "Add custom-dependencies directory (if it doesn't exist)" section of the
+> [`INSTALL-INSTRUCTIONS.md`](../INSTALL-INSTRUCTIONS.md) file.
+
 In order to provide better separation and management of custom dependencies and patches, we've introduced two new files:
 
 - `custom-dependencies/composer.json`: For managing custom dependencies
@@ -86,4 +92,4 @@ composer update
 
 ### What if I don't want to use the `custom-require` or `custom-remove` commands?
 
-The standard `composer require` and `composer remove` commands will still work, however we HIGHLY recommend that you try not to use them. In a future update, we may need to edit the root `composer.json` file, which puts you in danger of a nasty merge conflict.
+The standard `composer require` and `composer remove` commands will still work, however we HIGHLY recommend that you try not to use them. In a future update, we may need to edit the root `composer.json` file, which puts you in danger of a nasty merge conflict.

sample-custom-dependencies/composer.json custom-dependencies-source/composer.jsonsample-custom-dependencies/composer.json renamed to custom-dependencies-source/composer.json

@@ -1,5 +1,5 @@
 components-library:
-  version: 2.18.11
+  version: 2.18.12
   dependencies:
     - core/drupal
     - core/drupalSettings
@@ -11,7 +11,7 @@ components-library:
     component:
       css/asu_brand.header.css: {}
 block__system_main_block:
-  version: 2.18.11
+  version: 2.18.12
   css:
     theme:
       css/asu-brand-edit-form.css: {}

…-custom-dependencies/patches.custom.json …-dependencies-source/patches.custom.jsonsample-custom-dependencies/patches.custom.json renamed to custom-dependencies-source/patches.custom.json sample-custom-dependencies/patches.custom.json renamed to custom-dependencies-source/patches.custom.json

@@ -1,31 +1,31 @@
 asu-degree-rfi-core:
-  version: 2.18.11
+  version: 2.18.12
   dependencies:
     - asu_react_integration/reactjs
     - core/jquery
     - core/drupal
     - core/drupalSettings
 app-rfi:
-  version: 2.18.11
+  version: 2.18.12
   dependencies:
     - asu_degree_rfi/asu-degree-rfi-core
   js:
     node_modules/@asu/app-rfi/dist/appRfi.umd.js: {}
     js/asu_degree_rfi.rfi.js: {}
 degree-page-core:
-  version: 2.18.11
+  version: 2.18.12
   dependencies:
     - asu_degree_rfi/asu-degree-rfi-core
   js:
     node_modules/@asu/app-degree-pages/dist/degreePages.umd.js: { }
 degree-listing-page:
-  version: 2.18.11
+  version: 2.18.12
   dependencies:
     - asu_degree_rfi/degree-page-core
   js:
     js/asu_degree_listing_page.js: {}
 program-detail-page:
-  version: 2.18.11
+  version: 2.18.12
   dependencies:
     - asu_degree_rfi/degree-page-core
   js:

modules/asu_brand/asu_brand.libraries.yml

@@ -1,5 +1,5 @@
 events-component:
-  version: 2.18.11
+  version: 2.18.12
   dependencies:
     - asu_react_integration/reactjs
     - core/jquery

modules/asu_degree_rfi/asu_degree_rfi.libraries.yml

@@ -1,5 +1,5 @@
 footer-block:
-  version: 2.18.11
+  version: 2.18.12
   dependencies:
     - core/jquery
     - core/drupal