Development

Pantheon updates do not apply when using the “Apply Upstream updates” button

This can happen if there are Git merge conflicts between the files in the site and files in the upstream. First consult Pantheon’s detailed documentation on this at https://docs.pantheon.io/guides/git/resolve-merge-conflicts

Another cause, if the site is using Composer, can be that your site’s composer.json requirements conflict with those in the upstream composer.json file. Pantheon explains how to troubleshoot this at https://docs.pantheon.io/guides/integrated-composer/ic-troubleshooting#troubleshooting-code-syncs-upstream-updates-and-redirect-errors

If you use Terminus, you can also access log output about the failure using this plugin: https://github.com/pantheon-systems/terminus-composer-logs-plugin

If, after working through above, you’re still unable to resolve the issue, email drupal-kit-support@utlists.utexas.edu to troubleshoot less common causes.

File changes pushed to Pantheon do not take effect

Scenario: a developer wanting to add new code to a site hosted on Pantheon attempts to require new Composer dependencies or commit files to Git version control. The change works locally, but when the changes are pushed to Pantheon, the new files do not appear.

What to look for: If you encounter an error during a code sync or if the site is missing files that should be added, the “Build Log” may confirm the problem.

  1. Navigate to Code in the Dev tab of your site Dashboard.

  2. Navigate to the Commit Log section, find the most recent commit, and click View Log.

  3. Error messages about Git permissions or about unexpected files indicate this problem.

Explanation: Pantheon has a build process called Integrated Composer that assembles the third-party code used in sites – the code for Drupal core, contributed modules, and libraries. These files must be placed in specific locations and should never be committed to a site’s Git repository. A developer could introduce a problem to this build process by committing files to the wrong directory or by changing the .gitignore file directives. To resolve this issue, follow the steps Build Step Affected Files That Are Not Ignored by Git.

Recommended reading: Integrated Composer FAQ

Package incompatibility with Composer 2

As of the 3.0.0-beta.9 release (January 2021), the Drupal Kit is compatible with both Composer version 1 and version 2.

Developers who originally installed a site using a prior version, however, and now want to start using Composer 2 need to make some minor adjustments to their scaffolding.

Tip

In most operating systems, it is easy to switch back and forth between Composer versions by running composer self-update --1 or composer self-update --2.

You can use this to help identify when and where Composer versions are causing issues.

To make existing packages use Composer 2, make the following changes to your root composer.json file:

  • Change the version constraint on "composer/installers" from "^1.7" to "^1.9".

  • Change the version constraint on "cweagans/composer-patches" from "^1.6" to "^1.7".

  • Change the version constraint on "oomphinc/composer-installers-extender" from "1.1.2" to "^1 || ^2".

  • Remove "zaporylie/composer-drupal-optimizations": "^1.0" (it is obsolete when using Composer 2).

  • If using Pantheon Quicksilver scripts, add a Quicksilver installer paths rule based on this scaffolding example.

If you added any optional Drupal Kit packages listed below, they will need to be explicitly added to the Composer update command shown subsequently:

  • utexas/utprof

  • utexas/utnews

  • utexas/utevent

Complete the process by pulling in the Composer 2-compatible versions of those packages (this can be done while using Composer version 1 or version 2 on your machine):

composer update utexas/utdk_profile composer/installers cweagans/composer-patches oomphinc/composer-installers-extender --with-dependencies

Your site is now compatible with Composer 2, and further updates should only require the normal steps located in the Updating a site section.

Update command in documentation fails to update the Kit

Pantheon sites

If your site is hosted on Pantheon, you must update the Drupal Kit using the site dashboard’s “Apply updates” button. This is because the version of the Drupal Kit is set by the Pantheon upstream, as described in Updating a site.

Non-Pantheon sites

Under some circumstances, the update command, composer update utexas/utdk_profile --with-all-dependencies, will not, in fact, update the Drupal Kit.

This is because the command intentionally limits the scope of the update only to the utexas/utdk_profile package and its dependencies, but excludes dependencies that are defined in your root composer.json.

Tip

Before adding new requirements to your composer.json file, it’s a good idea to check whether the package is already listed as a requirement in the Drupal Kit, you may do so by running composer show. Avoiding redundant requirements will reduce the likelihood of version conflicts.

If one of the Drupal Kit’s dependencies is also listed in your root composer.json, there is a possibility for a conflict between the versions. Composer will handle this by respecting the version requirement in the composer.lock file, and will skip updating utexas/utdk_profile if its version requirement conflicts.

You can diagnose the problem by adding the --verbose flag to the command:

composer update utexas/utdk_profile --verbose --with-all-dependencies

If the standard update command has been failing to update the Kit, the output will report one or more dependencies that are “also a root requirement”:

1 Dependency "composer/installers" is also a root requirement, but is not explicitly allowed. Ignoring.
2 Dependency "cweagans/composer-patches" is also a root requirement, but is not explicitly allowed. Ignoring.

Running composer update with no other parameter would resolve the issue, but it may not be your preferred action if you only want to update the Drupal Kit. There are a better ways to resolve this, depending on how you want to control what is updated:

  1. Explicitly update the shared dependencies only. Example command: composer update utexas/utdk_profile composer/installers/ cweagans/composer-patches --with-dependencies.

  2. Implicitly update any shared dependencies: composer update utexas/utdk_profile --with-all-dependencies.

If those commands still fail, you will most likely get new error output indicating that you have a specific version number requirement in your root composer.json that conflicts with the version number requirement in the Drupal Kit. The proper resolution in this instance would be to manually change the version requirement in your root composer.json to be compatible with the Drupal Kit’s requirement, then run one of the above commands again. For more information see Composer versions and constraints.

After using one of these approaches to resolving the update, you should once again be able to use the standard update command for future updates.

Command fails with git@github.austin.utexas.edu: Permission denied (publickey)

This output indicates that a Composer package you are requiring is being instructed to download a “source” version (branch) of a UTexas package rather than a “dist” version (tag). The most common scenario where this will happen is running composer run-script dev-scaffold to do Docksal-based local development, which would attempt to pull in the develop branch.

As of January 2021, it is preferable to use a “dist” version of the tooling, which you can do by running composer require utexas/utdk_localdev instead of the command above.

If there are other reasons you need “source” versions from git@github.austin.utexas.edu, you can resolve the command failure by adding an SSH key at https://github.austin.utexas.edu/settings/keys.

See also Version control.

“The “Grid display” for Views isn’t working”

Drupal’s Views “Grid display” template adds CSS classes such as .col-* (e.g. .col-1, .col-2) to display grid items. The Bootstrap-based Forty Acres theme uses the same classes but for a different purpose. As a result, without modifying the classes used in the Views “Grid display,” the grid will not layout properly.

One solution is to use Bootstrap’s CSS classes for grid layout (e.g., .col-sm, .col-md) instead of the Drupal “Grid display.” Note that a preceding row class is also necessary so items display side-by-side, as shown below:

Code markup of Bootstrap grid system showing "row" and "col" classes