As part of my Clinic Duty rotation, I add a project tag and move this task to "To Estimate" because the task is clear enough to be sized and valuable in our current hypothesis.

Today I worked on updates for the core endpoints that had wikimedia-paths-GET-summary errors. For /v1/revision/{from}/compare/{to}, the Style Guide would have me change the summary from "Compare revisions" (source) to something like "Get revision comparison" or "Get comparison of revisions". However, I think those options are less clear and that "Compare revisions" is the simplest and shortest way to clearly describe what this GET operation does. I think the verb capturing the meaning of what the operation does is perhaps better than having consistent verbs for all GET operations. Perhaps we should discuss modifying or softening this Style Guide requirement?

I'd also like feedback on these changes and whether we are okay with how they attempt to translate the meaning of the operation, and also how long they are:

• /v1/search/page: changed "Search pages" to "Get pages by search query".
• /v1/search/title: changed "Autocomplete page title" to "Get pages by title query".

Based on our discussion and decisions for the above questions, I'll go on to fix the remaining endpoints with wikimedia-paths-GET-summary errors:

• /math/v0/popup/html/{qid}:
• /flaggedrevs/internal/diffheader/{oldId}/{newId}
• /oauth2/authorize
• /oauth2/resource/{type}
• /oauth2/client
• /checkuser/v0/userinfo/blocked/{name}
• /campaignevents/v0/event_registration/{id}
• /campaignevents/v0/event_registration/{id}/participants/self
• /campaignevents/v0/event_registration/{id}/organizers
• campaignevents/v0/event_registration/{id}/participants
• /campaignevents/v0/organizer/{userid}/event_registrations
• /campaignevents/v0/participant/{userid}/event_registrations
• /campaignevents/v0/participant/self/events_for_edit
• /campaignevents/v0/participant_questions
• /campaignevents/v0/formatted_time/{languageCode}/{start}/{end}
• /wikimediacampaignevents/v0/event_registration/{id}/grant_id

...and also the 31 instances of wikimedia-paths-operation-summary-exists-no-periods.

Thanks for working on this, @TBurmeister!

In T428150#11996204, @TBurmeister wrote:

I think the verb capturing the meaning of what the operation does is perhaps better than having consistent verbs for all GET operations. Perhaps we should discuss modifying or softening this Style Guide requirement?

I am in favor of relaxing this requirement to allow for more natural and more informative phrasing where appropriate. Another example is using "predict" instead of "get" for machine learning API endpoints.

I agree. This requires a change in the linter and in the style guide. For the linter, I suggest the following:

• Change the severity of wikimedia-paths-GET-summary to hint so that the linter still provides a suggestion to start a summary for get operations with Get or List unless a better option exists.
• Make sure get operations are included in wikimedia-paths-operation-summary-exists-no-periods so that a missing summary still results in a linter error.

If there are no objections, I'll prepare a merge request for these changes in the ruleset.

kbach opened https://gitlab.wikimedia.org/repos/ci-tools/wikimedia-spectral-ruleset/-/merge_requests/12

Draft: Update summary rules based on feedback

Sounds good to me! Thanks for the patch!

What do you think about these summary changes?:

• /v1/search/page: change "Search pages" to "List pages by search query".
• /v1/search/title: change "Autocomplete page title" to "List pages by title query".

My thoughts:

• I like that they follow a consistent pattern
• I dislike that they are longer
• I like that "List pages by title query" seems to more accurately reflect what that operation does than "Autocomplete title", which has always been confusing to me. I understand that one use of this is to implement page title autocomplete in search, but I think using that as the summary might be a misnomer?

Why? I'm trying to assess if we're calibrated on the desired outcomes from the linter output and on our interpretation of the Style Guide. Thanks for your input!

In T428150#12002558, @TBurmeister wrote:

What do you think about these summary changes?:

• /v1/search/page: change "Search pages" to "List pages by search query".
• /v1/search/title: change "Autocomplete page title" to "List pages by title query".

Overall, I like the consistency and clarity of the updated summaries.

I prefer "List pages by title query" (or maybe even "List pages by title"?) over "Autocomplete page title" because it's better at communicating what the input and output of the operation are.

For "Search pages"/"List pages by search query", I have a weak preference for the latter but only because of consistency.

Change #1300195 had a related patch set uploaded (by Triciaburmeister; author: Triciaburmeister):

[mediawiki/core@master] api-docs: Update core (/v1/) endpoint summaries to follow OAD style guide

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

aghirelli merged https://gitlab.wikimedia.org/repos/ci-tools/wikimedia-spectral-ruleset/-/merge_requests/12

Update summary rules based on feedback

As of now, the linter output for https://www.mediawiki.org/w/rest.php/specs/v0/module/- includes the following wikimedia-paths-GET-summary errors for the following routes:

• /math/v0/popup/html/{qid} ➤ get
• /oauth2/authorize ➤ get
• /oauth2/resource/{type} ➤ get
• /oauth2/client ➤ get
• /campaignevents/v0/event_registration/{id} ➤ get
• /campaignevents/v0/event_registration/{id}/participants/self ➤ get
• /campaignevents/v0/event_registration/{id}/organizers ➤ get
• /campaignevents/v0/event_registration/{id}/participants ➤ get
• /campaignevents/v0/organizer/{userid}/event_registrations ➤ get
• /campaignevents/v0/participant/{userid}/event_registrations ➤ get
• /campaignevents/v0/participant/self/events_for_edit ➤ get
• /campaignevents/v0/participant_questions ➤ get
• /campaignevents/v0/formatted_time/{languageCode}/{start}/{end} ➤ get
• /wikimediacampaignevents/v0/event_registration/{id}/grant_id ➤ get

...and the linter currently outputs 22 instances of the error wikimedia-paths-operation-summary-exists-no-periods:

• /securepoll/set_translation/{entityid}/{language} ➤ post
• /confirmedit/v0/hcaptcha/blocktoken ➤ post
• /oauth2/access_token ➤ post
• /oauth2/client ➤ post
• /oauth2/client/{client_key}/reset_secret ➤ post
• /ipinfo/v0/revision/{id} ➤ post
• /ipinfo/v0/archivedrevision/{id} ➤ post
• /ipinfo/v0/norevision/{username} ➤ post
• /ipinfo/v0/log/{id} ➤ post
• /eventbus/v0/internal/job/execute ➤ post
• /campaignevents/v0/event_registration ➤ post
• /campaignevents/v0/event_registration/{id} ➤ put
• /campaignevents/v0/event_registration/{id} ➤ delete
• /campaignevents/v0/event_registration/{id}/participants/self ➤ put
• /campaignevents/v0/event_registration/{id}/participants/self ➤ delete
• /campaignevents/v0/event_registration/{id}/organizers ➤ put
• /campaignevents/v0/event_registration/{id}/participants ➤ delete
• /campaignevents/v0/event_registration/{id}/email ➤ post
• /campaignevents/v0/event_registration/{id}/edits/{wiki}/{revid} ➤ put
• /campaignevents/v0/event_contributions/{id} ➤ delete
• /wikimediacampaignevents/v0/event_registration/{id}/grant_id ➤ put
• /wikimediacampaignevents/v0/event_registration/{id}/grant_id ➤ delete

The above routes should be considered out of scope for this task: in the future they won't be part of the core MW REST API OAD, they'll be in modules, and we need to wait until these routes have been moved to modules before we start creating their OAD content.

With 1300195, the work on OAD summaries for all in-scope routes (those that are /v1/ and part of the core REST API) will be complete.

Change #1300195 merged by jenkins-bot:

[mediawiki/core@master] api-docs: Update core (/v1/) endpoint summaries to follow OAD style guide

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