Check if a Drupal version is compatible with the Project Browser endpoints

We’d add this in settings.all.php

// Drupal versions supported for Project Browser endpoints.
// Semver format. Could have multiple ranges.
$settings['drupalorg_jsonapi_supported_drupal_versions'] = ['^11.0.0'];

Request would be (not deployed): https://www.drupal.org/drupalorg-api/project-browser-check-version?drupa... →

{
  "supported": true,
  "message": "Version 11.0.8 is supported."
}

Or https://www.drupal.org/drupalorg-api/project-browser-check-version?drupa... →

{
  "supported": false,
  "message": "Invalid version."
}

Looks like a great start. I think we’ll want to be able to provide specific messages to be shown in the project browser UI when a Drupal version loses support. That will let us giver users a path forward, either explaining the deprecation/loss-of-support, and what to do next.

For example:

$settings['drupalorg_project_browser_unsupported_drupal_versions'] = [
  '<10.0.0' => 'Not sure how you are using project browser with Drupal 9 or earlier',
  '<11.0.0' => 'Upgrade to Drupal 11 to continue using Project browser, <a href="https://www.drupal.org/some/announcement">details are in this announcement</a>',
];

The client should ideally render some limited HTML, with filtering for XSS, and validating that all URLs are *.drupal.org.

We may also want the ability to have a message without saying that Drupal version is no longer supported, so we can communicate upcoming deprecations.

Good suggestion. Implemented in here: https://git.drupalcode.org/project/drupalorg/-/commit/361bb7ef267f66b631...

See the full logic in this block: https://git.drupalcode.org/project/drupalorg/-/blob/1.0.x/src/Controller...

There was a suggestion in Slack to distinguish deprecated vs. unsupported. I think that’d be a good idea so we can communicate ahead of dropping support for a particular Drupal client version.

I think it might make sense to combine this with the maintenance & development status metadata API into a single API request for “project browser metadata that the client can keep cached for a few hours.” While we don’t really need to over-optimize, one less HTTP request is a bit nicer for the client. As long as the client processes this support data first, we can update the rest of the API response as-needed. I can’t think of what we’ll add in the future, but I expect this pattern of needing relatively-static metadata to supplement JSON:API could be expanded to have additional metadata in the future.

Another use case for this - if something happens to the project index and we’re doing maintenance, this would be a good way to communicate that results might not be as expected, while the client Drupal version is supported.

Combined request

// https://drupalorg.ddev.site/drupalorg-api/project-browser-filters?drupal_version=10

{
  "active": [
    "db118813-d01c-4a58-aee4-0fe61092b85b",
    "dff295b3-122b-4ca0-85a7-777901b003cc"
  ],
  "maintained": [
    "034d3c61-5bd4-4878-b37c-501e6f12a6db",
    "cd604554-9bcb-4e9e-9d8e-da09e60dd13a",
    "ce5ceae9-cf50-4b66-af58-0c000716c63d"
  ],
  "drupal_version": {
    "supported": false,
    "message": "Upgrade to Drupal 11 to continue using Project browser, <a href=\"https://www.drupal.org/some/announcement\">details are in this announcement</a>"
  }
}

or without the parameter:

// https://drupalorg.ddev.site/drupalorg-api/project-browser-filters

{
  "active": [
    "db118813-d01c-4a58-aee4-0fe61092b85b",
    "dff295b3-122b-4ca0-85a7-777901b003cc"
  ],
  "maintained": [
    "034d3c61-5bd4-4878-b37c-501e6f12a6db",
    "cd604554-9bcb-4e9e-9d8e-da09e60dd13a",
    "ce5ceae9-cf50-4b66-af58-0c000716c63d"
  ]
}

Commit with the changes: https://git.drupalcode.org/project/drupalorg/-/commit/164f8709e37cba8f96...

Looks good to me. Unless we have other feedback soon, I should go ahead and put this in production, so the client side implementation is unencumbered. We can always do a follow-up deployment if we want to change something. It would be great to attach a couple example outputs for client test fixtures, here or in the client side implementation issue.

I think this can work. We have support to show Drupal messages in PB already, afaik (for example if there is a verification problem with Package Manager), so I believe the backend can utilize this to show an info/error/warning message as appropriate.

Deployed to prod.

These are the 4 scenarios we are covering so far:

1. No Drupal version passed
https://www.drupal.org/drupalorg-api/project-browser-filters →

{
  "active": [
    "e767288c-9800-4fb4-aeb8-8c311533838a",
    "219c1cf2-dd7f-474b-9dd5-a26643fbc699"
  ],
  "maintained": [
    "089406ad-304d-4737-80d1-2f08527ae49e",
    "cee844e2-68b5-489d-bafa-6a0ade2b6dfd",
    "09a378d2-fd35-41f3-bff0-10d9801741a4"
  ]
}

2. Drupal 9 version
https://www.drupal.org/drupalorg-api/project-browser-filters?drupal_vers... →

{
  "active": [
    "e767288c-9800-4fb4-aeb8-8c311533838a",
    "219c1cf2-dd7f-474b-9dd5-a26643fbc699"
  ],
  "maintained": [
    "089406ad-304d-4737-80d1-2f08527ae49e",
    "cee844e2-68b5-489d-bafa-6a0ade2b6dfd",
    "09a378d2-fd35-41f3-bff0-10d9801741a4"
  ],
  "drupal_version": {
    "supported": false,
    "message": "Not sure how you are using project browser with Drupal 9 or earlier"
  }
}

3. Drupal 10 version
https://www.drupal.org/drupalorg-api/project-browser-filters?drupal_vers... →

{
  "active": [
    "e767288c-9800-4fb4-aeb8-8c311533838a",
    "219c1cf2-dd7f-474b-9dd5-a26643fbc699"
  ],
  "maintained": [
    "089406ad-304d-4737-80d1-2f08527ae49e",
    "cee844e2-68b5-489d-bafa-6a0ade2b6dfd",
    "09a378d2-fd35-41f3-bff0-10d9801741a4"
  ],
  "drupal_version": {
    "supported": false,
    "message": "Upgrade to Drupal 11 to continue using Project browser, <a href=\"https://www.drupal.org/project/drupalorg/issues/3494314\">details are in this announcement</a>."
  }
}

4. Drupal 11+ version
https://www.drupal.org/drupalorg-api/project-browser-filters?drupal_vers... →

{
  "active": [
    "e767288c-9800-4fb4-aeb8-8c311533838a",
    "219c1cf2-dd7f-474b-9dd5-a26643fbc699"
  ],
  "maintained": [
    "089406ad-304d-4737-80d1-2f08527ae49e",
    "cee844e2-68b5-489d-bafa-6a0ade2b6dfd",
    "09a378d2-fd35-41f3-bff0-10d9801741a4"
  ],
  "drupal_version": {
    "supported": true,
    "message": "Supported version."
  }
}