In preparation for multi-content revisions (MCR), we've made[1] several changes to action=compare. These changes should be deployed to Wikimedia wikis with 1.32.0-wmf.19 or later. The changes should also be available on the Beta Cluster[2] soon for testing.

*== Supplying content using templated parameters ==*

For MCR, when specifying content (as with the `fromtext` and `totext` parameters) we need the ability to specify content for each "slot" in the page. The way this works for action=compare is that (1) the base revision is determined using the parameters that identify the page and/or revision (`fromtitle`/`totitle`, `fromrev`/`torev`, and so on), then (2) the new `fromslots`/`toslots` parameter specifies which slots are being changed, and then (3) new parameters for each value of `fromslots`/`toslots` specify the content for each of those slots.

In the API help, these new parameters for each value of `fromslots`/`toslots` are described as "templated parameters" and have a placeholder in their names. Where the help describes "totext-{slot}", it's meaning that if you supply "toslots=foo|bar" then there would be corresponding parameters "totext-foo" and "totext-bar" to supply the text for those two slots.

In Special:ApiSandbox, input fields for "totext-foo" and "totext-bar" will appear when you enter those value for "toslots".

In the future templated parameters will be introduced for action=edit and action=parse as well, and other modules as the need arises.

*== Deprecations and changes in action=compare ==*

The following parameters are deprecated, with replacements as indicated.

- `fromtext` is replaced with `fromtext-main` with `fromslots=main`. - `fromcontentmodel` is replaced with `fromcontentmodel-main` with `fromslots=main`. - .`fromcontentformat` is replaced with `fromcontentformat-main` with `fromslots=main`. - `totext` is replaced with `totext-main` with `toslots=main`. - `tocontentmodel` is replaced with `tocontentmodel-main` with `toslots=main`. - .`tocontentformat` is replaced with `tocontentformat-main` with `toslots=main`.

The `fromsection` and `tosection` parameters are also deprecated with no direct replacement. The intended use case for these parameters was to simulate a diff of a section edit, by supplying the edited section's text as `totext` and supplying `fromsection` to extract just the section being edited from the current revision. This use case is now supported by specifying `totext-main` as the edited section's text and supplying `tosection-main` to identify the section being edited, which will be combined into the existing content as for a section edit. This will result in a diff more closely matching that returned for a section edit from the web UI with respect to line numbers and context lines.

By default action=compare will return one HTML blob combining the diffs of all slots, much as is shown in the web UI. The new `slots` parameter may be used to get separate HTML blobs for each slot's diff and to limit which slots' diffs are returned..

*== Other notes ==*

Note that the already-deprecated[3] diffing parameters to revision-related modules, such as the rvdifftotext parameter to action=query&prop=revisions, will not be updated for MCR. Code using these parameters should be updated to use action=compare instead.

[1]: https://gerrit.wikimedia.org/r/c/mediawiki/core/+/448160 [2]: e.g. https://en.wikipedia.beta.wmflabs.org/w/api.php?modules=compare [3]: https://lists.wikimedia.org/pipermail/mediawiki-api-announce/2017-June/00013...