Deprecate migrate process plugins needed only for site upgrades

Updated from discussion on the Migrate video call today. benjifisher, heddn, mikelutz and quietone were present. #3518542: [meeting] Migrate Meeting 2025-04-24 2100Z

Two of the blocking issues have been Fixed, and the third is Closed (won't fix).

I suspect: https://git.drupalcode.org/project/drupal/-/blob/11.x/core/modules/filte... will be on the list for removal.

Yes, the filter_id process plugin is needed only when upgrading from Drupal 6 or 7. It should be deprecated as part of this issue.

I am updating the title to clarify that we are not planning to deprecate all process plugins. My title is a little awkward, so feel free to improve on it.

@quietone:

I am confused by the two lists in the issue summary (IS). Can you explain the "to check" list and why some items are struck through?

I guess the second list (under Proposed resolution) is meant to agree with the list of changed files in the MR. If so, then it is mostly correct, but the MR deprecates three process plugins in the migrate_drupal module. I think the IS is correct, and the MR should be updated: we do not need to deprecate these process plugins, since we will be deprecating the entire migrate_drupal module, right?

I have used the link_uri process plugin (Drupal\menu_link_content\Plugin\migrate\process\LinkUri) in custom migrations. My vote is that we should not deprecate that one.

I think I am going to have to review the other 46 process plugins and decide whether there are more that I want to keep.

I wonder if, when we want to keep a process plugin, we should move it to the migrate module. I do not think I will have a firm opinion until I review the 46 process plugins. If we think this is a good idea, then we should follow the pattern we used when moving two source plugins from migrate_drupal to migrate:

1. Deprecate the original process plugin.
2. Remove the MigrateProcess attribute from the original.
3. Add the plugin to the migrate module, with the MigrateProcess attribute.
4. Modernize the code in the new plugin. For example, use constructor promotion and add type declarations.

We might even decide to do (1) as part of this issue and postpone (2) to (4) to a followup issue.

I reviewed the process plugins in the block and field modules. I do not think we want to keep any of them. That is, they all seem to be written explicitly to handle migrations from D6/D7, and I do not think they are generally useful.

21 done, 26 to go.

I also made a RFC in the #migration Slack channel.

I reviewed the 47 process plugins, and I think there are 4 that we should consider keeping:

1. link_options (Drupal\menu_link_content\Plugin\migrate\process\LinkOptions): if $value['query'] is a string, then apply parse_str() to replace it with an array.
2. link_uri (Drupal\menu_link_content\Plugin\migrate\process\LinkUri): if $value is a path representing an internal link (starting with '/', '?', or '#'), then convert it to a URI using one of the schemes base:, entity:, or internal:.
3. timezone (Drupal\system\Plugin\migrate\process\d6\TimeZone): if $value is an offset (in seconds) from UTC, then convert it to a compatible timezone name using timezone_name_from_abbr().
4. user_langcode (Drupal\user\Plugin\migrate\process\UserLangcode): if $value is the language code of a language enabled on the site, then return $value; otherwise, fall back to 'en' or the language code of the site’s default language (depending on configuration).

The only one I feel strongly about is (2), since I have used it in custom migrations (not site upgrades). I think that (1) could be useful when migrating data into a link field, and I can see using (3) or (4) in a migration that creates users from a CSV source.

I do think that we should move any "keepers" to the migrate module. That will give us a chance to modernize the code (as I suggested in Comment #16) and to rewrite the doc blocks. To control scope, we should do that in a followup issue.

Some thoughts about the four plugins identified in #18:

link_options seems quite specific to its intended use; a more generic parse_str() plugin would be better than expecting an array with a query key.

link_uri indeed seems useful and we should keep it.

timezone doesn't seem too useful and could be done with a callback plugin if someone wanted to do it, I think?

user_langcode does seem like it has a niche use case in migrating language codes from other sources, perhaps we just keep it?

In an independent assessment following @benjifisher's comment in Slack, timezone<code> was the only process plugin outside the migrate module (other than <codel>link_uri) that struck me as potentially useful in a non-Drupal-upgrade migration.

@Longwave is probably right in #22 that it could be re-created with callback. It would be a little clumsy though because the that function takes three arguments and the first and third are constants and the middle one is the modified pipeline value. And then there's a default value. I think it would have to go something like this:

constants:
  empty_string: ''
  zero: 0
process:
  _timezone_int:
    plugin: callback
    callable: intval
    source: my_timesone
  timezone_string:
    -
      plugin: callback
      unpack_source: true
      callable: timezone_name_from_abbr
      source:
        - constants/empty_string
        - '@_timezone_int'
        - constants/zero
    -
      plugin: default_value
      default_value: 'UTC'

I'd rather use timezone if I had to do this transformation. Of course, I've never run into this case!

I don't know. It's a little piece of code that has test coverage and might be useful. I tend to be in favor of keeping things like that. I also have too much stuff in basement. :)

Let's take a step back: what is the criterion for keeping a process plugin?

I think the criterion should be

It is reasonable to expect that a few developers have used the plugin in custom migrations.

If so, then I would like to save them the trouble of updating their migrations: it is a sort of backwards compatibility. Even if the change is as simple as replacing

  'link/options':
    plugin: link_options
    source: options

(which my hypothetical developer borrowed from d6_menu_links.yml) with

  'link/options': options
  'link/options/query':
    - plugin: skip_on_empty
      source: options/query
    - plugin: parse_url

the hypothetical developer will have to

1. Notice that there is a problem
2. Find the release note or change record
3. Update the migration

In other words, Step 3 is the easy part.

In short, I am arguing in favor of a low bar for keeping a process plugin. That ends up with the same conclusion that @danflanagan8 suggested in Comment #23:

It's a little piece of code that has test coverage and might be useful. I tend to be in favor of keeping things like that.

@quietone:

Yes, I am suggesting that we keep all four that I listed in Comment #18. But I will not fight for link_options if the consensus is to deprecate it.

Ideally we want to ship this with 11.3.0 and the remaining window is very short so I think this should land ASAP.

To err on the side of caution let's just keep both of those in, it won't hurt if they go unused, and we can always deprecate them later.

Un-deprecated those two plugins, and also removed the IgnoreDeprecations from LinkUriTest now that is not deprecated either. Hopefully this is a minor enough change that I can self-RTBC.

I think we should revert the commit d21d179e293. The commit message is "remove process plugins in migrate_drupal", but it un-deprecates 3 process plugins in the migrate module, all related to the "complete" node migrations.

Other than that, I agree with Comment #31: we should get this issue mostly right ASAP, and we may change our minds later about the handful of process plugins that we are keeping.

I am adding the tag for a followup, to consider moving the four "keepers" to the migrate module.

Sorry for the noise.

I looked again, and indeed those three process plugins are in the migrate_drupal module. We do not have to deprecate the process plugins since the whole module is deprecated.

Back to RTBC.

Opened #3560075: Relocate or deprecate link_options, link_uri, timezone and user_langcode migrate plugins

Went to commit this but it needs a rebase.

Committed/pushed to 11.x and cherry-picked to 11.3.x, thanks!