Clarification of replace and extra sections in composer.json for TYPO3 extensions

Update (Aug 17, 2020): the section "my_ext_key": "self.version" is no longer found in newer examples or in helhum/composer.json. See clarifications below.

There are several examples for composer.json for TYPO3 around. Some include a replace section with something like the following:

replace:

"replace": {
    "my_ext_key": "self.version",
    "typo3-ter/my-ext-key": "self.version"
},

"replace": {
    "vendorname/my-extension": "self.version",
    "typo3-ter/my-extension": "self.version"
},

https://wiki.typo3.org/Composer#Extension_key_.2F_composer_name

And / or an extra section

"extra": {
    "typo3/cms": {
        "extension-key": "extension_key"
    }
}

When are these sections necessary, what do they do and what is recommended (for TYPO3 extensions)? Are there differences between TYPO3 versions specific to these sections?

Specifically:

The second line in the replace example
```
"typo3-ter/my-ext-key": "self.version"
```
for example, makes sense if extension was published in TER and was available from composer.typo3.org, I guess. If extension was only available via packagist, it does not really make sense to include it.
About the first line of replace, when is this necessary and what does it do?
```
"my_ext_key": "self.version",
```
Usually, replace it used to replace some other package, e.g. as a drop-in-replacement which is explained for example here. This section was available in a previous example composer.json but has now been removed (see helhum/composer.json). Also, it would now cause a warning on composer validate, see also comment. Is it still necessary for older TYPO3 versions?
The extra part maps the extension key (with underscore) to package name (with dash). However, this is already the default. So, when is this required or can it be removed entirely?

Solution

As the official composer documentation for replace states:

Lists packages that are replaced by this package. This allows you to fork a package, publish it under a different name with its own version numbers, while packages requiring the original package continue to work with your fork because it replaces the original package.

This is also useful for packages that contain sub-packages, for example the main symfony/symfony package contains all the Symfony Components which are also available as individual packages. If you require the main package it will automatically fulfill any requirement of one of the individual components, since it replaces them.

Caution is advised when using replace for the sub-package purpose explained above. You should then typically only replace using self.version as a version constraint, to make sure the main package only replaces the sub-packages of that exact version, and not any other version, which would be incorrect.

For a more TYPO3 related explanation of the composer.json replace property there is an explanation available provided by Helhum:

The replace property MUST be provided if the composer package name part does not match the extension name and is highly recommended thus SHOULD be provided in any case. If it is provided, the first replace value MUST match exactly the extension key and the second replace value SHOULD match the TER package key (extension key prefixed with “typo3-ter/” and with underscores (_) replaced with dashes (-). The version constraint MUST exactly be self.version

For additional information please follow the links as they contain further information.