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/0001…
--
Brad Jorsch (Anomie)
Senior Software Engineer
Wikimedia Foundation