Document how to perform format mappings in D6/D7 upgrade

If the "standard" profile is used, assuming that

• "standard" profile installs a role, some format filters and theme/blocks
• all the migrations will be played

... the migration process will certainly duplicate these components (in most use-cases)

Does it mean that the minimal profile is the first choice for people intending to migrate?

Thank you for the clarification.
The approach seems sane to me, as long as writing custom mappings is simple enough and well documented.
Could the 'filtered_html' (d6/d7) => 'basic_html' (d8) mapping appear somewhere as an "example"?

Link in #7 is broken if anyone knows a working one please post it

Altered the title to match the request from #6 which is to explain how someone can manually create a format mapping if they want to. This seems like something that people will want to do and could even be an example for the documentation of StaticMap. See also #3061681: Provide the ability to map text formats between source and destination which is more ambitious, and tries to automatically perform this mapping.

I guess that the link in #7 was just a link to the StaticMap class. I am aware that the class exists, but I can't see how/where to use it. There are references to the text format in very many places: many fields on many entity types. Please could we have an explanation of what file to edit at least?

OK I have it working. Is there someone we can put this for others who are interested?

A hook to substitute the class

/**
 * Implements hook_migrate_field_info_alter().
 */
function XXX_migrate_field_info_alter(array &$definitions) {
  $definitions['d7_text']['class'] = 'Drupal\XXX\Plugin\migrate\TextFieldOverride';
}

The class itself

namespace Drupal\XXX\Plugin\migrate;

use Drupal\migrate\Plugin\MigrationInterface;
use Drupal\text\Plugin\migrate\field\d7\TextField;

/**
 * Replacement class for "d7_text" field migration.
 */
class TextFieldOverride extends TextField {

  /**
   * {@inheritdoc}
   */
  public function defineValueProcessPipeline(MigrationInterface $migration, $field_name, $data) {
    $process = [
      'plugin' => 'sub_process',
      'source' => $field_name,
      'process' => [
        'value' => 'value',
        'format' =>
        [
          'plugin' => 'static_map',
          'source' => 'format',
          'map' => [
            'filtered_html' => 'basic_html',
          ],
        ],
      ],
    ];

    $migration->mergeProcessOfProperty($field_name, $process);
  }

}

Hi @AdamPS,

we just ran into the same situation and I guess one clarification here could help others who run into the same issue:

What is "d7_text" in

/**
 * Implements hook_migrate_field_info_alter().
 */
function XXX_migrate_field_info_alter(array &$definitions) {
  $definitions['d7_text']['class'] = 'Drupal\XXX\Plugin\migrate\TextFieldOverride';
}

Is it the name of the field or or the migration id or the text format?

Like in #3061681: Provide the ability to map text formats between source and destination I guess it would make a lot of sense to document these kind of static mapping migrations somewhere for such typical cases. I'm aware of HOOK_migration_plugins_alter() and HOOK_migrate_prepare_row() which are very helpful for other cases, but in this case they don't help I guess?

So what we'd like to do is use existing Drupal 8 / 9 formats by map instead of migrating (some of / all) the old ones.

I'm curious if there is a better way to switch out upgrade_dX_filter_format and use the map instead of

  body/format:
    -
      plugin: migration_lookup
      migration: upgrade_d6_filter_format
      source: format

in node_complete_XXX migrations, but it doesn't seem to be well abstracted to do that for every field.

If anyone has a good snippet or idea, you're very welcome. I have to think about this.
Perhaps it's even easier to switch the formats after migration with a post-migrate script...

Edit:
Perhaps the strategy might be to replace "upgrade_d6_filter_format" to not import any formats but instead just return the mapping?

Here are some examples where the migration definition file has been edited, but I think it would be better to use hook_migration_plugins_alter if you need to apply this change everywhere

In my example, the D7 source site's text formats weren't migrated properly when the site was upgrade to d7, so machine names are in the d6 format.

Node body field:

process:
  body:
    -   
      plugin: sub_process
      source: body
      process:
        value: value
        format:
          -   
            plugin: static_map
            bypass: true
            source: format
            map:
              '1': 'basic_html'
              '2': 'full_html'
              '3': 'plain_text'
              '4': 'plain_text'
            default_value: 'basic_html'

Term description field:

process:
  description/value:
    -       
      plugin: get 
      source: description
  description/format:
    -       
      plugin: static_map
      source: format
      map:
        '1': 'basic_html'
        '2': 'full_html'
      default_value: 'basic_html'

Or a simple default value also works:

process:
  description/format:
    -   
      plugin: default_value
      default_value: 'basic_html'