What do you think about s/appearance/display? Analogous to T259547 ?

What do you think about s/appearance/display? Analogous to T259547 ?

I agree with the idea of display instead, especially since it should be consistent across endpoints.

Additionally, just want to clarify (because im not sure the use case): Is the HTML intended to be used for showing all the tags for a given contribution? If so, just clarifying we should just have one appearance_source property (however it ends up being named), instead of each tag object having appearance_source. That way we show all the tags in one html element.

I think each tag should have it's own HTML and it should be consumers responsibility to merge them together however they please.

The way that ChangeTags::formatSummaryRow() spits out the html is like: Tags: mw-revert, mobile edit. So do we want to remove Tags from the html output altogether so each tag is formatted on its own?

I believe you wouldn't really want the result of ChangeTags::formatSummaryRow() - it contains tons of MW-frontend specific stuff, like CSS classes etc.

I think instead we should include the result of ChangeTags::tagShortDescriptionMessage. And then get the source by calling plain() on the message and html by calling text()

ChangeTags::tagShortDescriptionMessage() gives us the description of the tag though, rather than the html or wikitext pointing to the tag page (https://en.wikipedia.org/wiki/MediaWiki:Tag-AWB) like I think @EvanProdromou wanted in https://phabricator.wikimedia.org/T235073#6337164?

Ok. So the tag is a message, e.g. tag-mw-manual-revert. The default message is defined in the i18n files. However, message can be overridden on wiki by creating a page MediaWiki:<message_id>.

So in the end tagShortDescriptionMessage()->parse() should end up giving you the result you want.

Change 619559 had a related patch set uploaded (by Nikki Nikkhoui; owner: Nikki Nikkhoui):
[mediawiki/tools/api-testing@master] Add option to add changetag description

https://gerrit.wikimedia.org/r/619559

Change 619578 had a related patch set uploaded (by Nikki Nikkhoui; owner: Nikki Nikkhoui):
[mediawiki/core@master] UserContribs tags prop add HTML

https://gerrit.wikimedia.org/r/619578

Change 619559 merged by jenkins-bot:
[mediawiki/tools/api-testing@master] Add option to add changetag description

https://gerrit.wikimedia.org/r/619559

If the idea for appearance_source to contain the wikitext? What's the use case for this? It's next to impossible for the client to correctly parse wikitext, attempts to do so tend to work initially, and then break unexpectedly for edge cases.

Note that the Architecture Principles state that clients shouldn't have to process wikitext: " API/FORMAT: APIs MUST be designed to enable clients to process content without the need to parse or manipulate wikitext". I believe we should only expose wikitext as an editing interface, for manipulation on the client side. I don't see how it can be useful here.

Change 619578 merged by jenkins-bot:
[mediawiki/core@master] UserContributions endpoint add tags 'display' property

https://gerrit.wikimedia.org/r/619578

Change 621340 had a related patch set uploaded (by Nikki Nikkhoui; owner: Nikki Nikkhoui):
[mediawiki/core@master] Fix UserContribs tags prop

https://gerrit.wikimedia.org/r/621340

We haven't used key-value pairs in output before, and I'm reluctant to introduce it here. I understand the idea -- that you can quickly check whether a tag is present by checking for the existence of a key -- but I think it makes iteration somewhat slower and more clumsy. Honestly, it just looks and feels weird.

Daniel brought the idea up in our 1:1 last week, and I gave the impression that I agreed, so this is my bad. From here on out, for clarity, let's use the schema as the source of truth.

I've updated the schema to use name and description for the Tag objects. I'd like to remove the key and have an ordered array of Tag objects for the tags property.

I also updated the design principles with this:

"Wikitext is source code. We provide wikitext output primarily for editing, not for display. If there's not a clear way to update an object's wikitext properties, we won't output them."

I agree, including the appearance_source wikitext property in the tag objects is unnecessary and kind of confusing.

Change 621340 merged by jenkins-bot:
[mediawiki/core@master] UserContribs tags prop as array

https://gerrit.wikimedia.org/r/621340

Looks good, thanks for the work everyone.

Name and description properties added to the draft docs