Improve landing-page UX and CTAs to reduce version/branch mismatch confusion

[jameswilson]

I hit a confusing setup failure while creating a Drupal Core Development workspace from an issue fork.

Drupal core (main/12.x) issue: https://www.drupal.org/project/drupal/issues/3309016

I selected Drupal 11 and used branch 3309016-add-image-preload-d11, but Composer failed because the checked-out branch resolved as Drupal 12/main:

• drupal/core 12.x-dev
• PHP requirement >=8.5.0
• workspace PHP version 8.4.20

After investigating, this appears to be caused by the issue/fork history rather than a simple template bug. The issue has moved across multiple target versions over time:

• originally around 9.5.x-dev
• moved to 10.1.x-dev
• later moved between 10.1.x-dev and 11.x-dev
• currently targets main

The MR for 3309016-add-image-preload-d11 also targets main, despite the branch name suggesting Drupal 11.

Problem

The workspace UI allowed selecting Drupal 11, and the setup log showed DDEV being configured as drupal11, but the checked-out issue branch was effectively targeting main.

That mismatch surfaced only later as a Composer/PHP constraint failure:

Root composer.json requires drupal/core 12.9999999.9999999.9999999-dev
drupal/core 12.x-dev requires php >=8.5.0
your php version (8.4.20) does not satisfy that requirement

Selected workspace parameters

• Issue fork: drupal-3309016
• Issue branch: 3309016-add-image-preload-d11
• Drupal version: 11.x
• Install profile: demo_umami (also tried with minimal and got the same issue)

Relevant setup output

The setup log showed the branch checkout and Drupal 11 DDEV configuration:

Issue fork mode: ISSUE_FORK=3309016  ISSUE_BRANCH=3309016-add-image-preload-d11  INSTALL_PROFILE=minimal
✓ Fetched from issue remote
✓ Checked out branch: 3309016-add-image-preload-d11
✓ Working tree reset to match branch
Configuring DDEV for Drupal 11 (drupal11)...
✓ .ddev/config.coder.yaml written
✓ DDEV configured (project-type=drupal11)

Then Composer failed with a Drupal 12/PHP 8.5 constraint:

Running composer update to apply merge settings
> Drupal\Composer\Composer::ensureComposerVersion
Loading composer repositories with package information
Updating dependencies
Your requirements could not be resolved to an installable set of packages.

  Problem 1
    - Root composer.json requires drupal/core 12.9999999.9999999.9999999-dev -> satisfiable by drupal/core[12.x-dev (alias of dev-main)].
    - drupal/core 12.x-dev requires php >=8.5.0 -> your php version (8.4.20) does not satisfy that requirement.

There was also a secondary Composer failure after rollback:

Update to apply merge settings failed, reverting composer.local.lock to its original content.
> Drupal\Composer\Composer::generateMetapackages

In Composer.php line 113:

  [Error]
  Class "Drupal" not found

Later Drupal install/Drush errors appear to be downstream of the failed dependency install:

drush is not available. You may need to 'ddev composer require drush/drush'

Why this was confusing

The visible setup flow made it look like one of these was broken:

• the selected Drupal version was ignored;
• the ddev-drupal-dev Composer overlay generated incorrect metadata;
• the install profile caused the wrong setup path;
• Drush was missing as a separate root problem.

The underlying issue appears to be that the selected workspace version, branch name, issue target, and MR target can diverge.

Suggested improvement

This may not be a failure of target-version detection itself. Instead, the setup output could make the detected issue/MR target and selected workspace version more explicit before Composer runs.

For example:

Selected workspace version: Drupal 11
Detected issue version: main
Detected MR target: main
Checked-out branch: 3309016-add-image-preload-d11

Warning: selected workspace version differs from the issue/MR target.
Composer may resolve this branch as Drupal 12/main.

This would make it clear that the failure is caused by branch/issue/MR target drift, not by the install profile, Drush, or the ddev-drupal-dev add-on.

Expected behavior

Before running Composer, the setup should make the relevant target/version signals explicit enough to diagnose this case:

• selected workspace Drupal version;
• detected issue target version;
• detected MR target branch, if available;
• checked-out branch name;
• detected core/composer version after checkout.

If these disagree, a warning or early targeted failure would be more actionable than the later Composer/PHP constraint error.

[rfay]

At first glance it seems that:

• You didn't (know to) use the Drupal issue picker, https://start.coder.ddev.com/drupal-issue, which would have set this up correctly
• You deliberately chose 11.x for the Drupal version even though the issue was targeted at main/12.x

I don't think Coder.ddev.com can be responsible for these things, or solve all composer issues, etc.

[jameswilson]

Discussed with Randy in Slack. This now looks less like a template/runtime bug and more like a UX/navigation problem that led me into the wrong flow.

Root cause in my case:

• I used the manual Drupal Core Development template at https://coder.ddev.com/templates/coder/drupal-core/workspace?mode=manual (big CTA button at the top of the start page and on this repo's README).
• I chose 11.x because the issue branch name ended in -d11.
• The issue/MR actually targets main, so choosing 12.x was the correct option.
• I initially selected demo_umami and the template form contains help text that seemed to indicate Drupal 12 would be selected when using Umami but it wasn't, leading to further confusion as I went back to retrace my steps and troubleshoot.
• Recreating the workspace with 12.x and demo_umami selected does work.

Suggested resolution:

• Deprioritize direct links to the manual Drupal Core Development template, since it exposes lower-level parameters and makes it easy to choose an inconsistent issue branch/version combination.
• Prioritize https://start.coder.ddev.com/drupal-issue and the Freeform template above the fold on https://start.coder.ddev.com.
• Add a clearer wrapper page for clean Drupal core work, for example https://start.coder.ddev.com/drupal-core, which links into the same underlying Drupal Core Development template but guides users through selecting a core version intentionally.
• From https://start.coder.ddev.com/drupal-issue, add a secondary link such as: “Test a clean Drupal core site without an issue fork” pointing to that wrapper.
• Keep a lower-priority “View all templates” link to https://coder.ddev.com/templates for advanced/manual use.

So I think this issue can be reframed as improving the landing page and entry-point hierarchy, rather than changing DDEV/Coder behavior around outdated or mismatched issue branches.