= Precursor
Since updating the page images algorithm is risky and we've hit issues in the past, T152252 should be resolved before work on this begins.
= Story
PageImages should allow specifying the selection of a page image using a magic word (or maybe in image markup). It should be required that to be the lede, it actually be visible in the article.
For example, the first image of the article may be in the second section. That image may be appropriate to accompany the second section. However, there may be a more appropriate lead image (representing the topic as a whole) later in the article.
{T90914} is about other markup options for images.
== User story
As an editor, I want to be able to select the page image for pages that do not have an assigned image
As an editor, I want to be able to select the page image for pages where the current image is inappropriate
== Background
Last year, we made a change to page images that restricted page images from selecting any image that was not in the lead section of an article (https://phabricator.wikimedia.org/T152115). This change was made because often images that were in latter sections were displayed out of context and were not a good representation of the entire article. We would like to give editors the ability to select page images from the remainder of the images within the page to increase the coverage of pages with page images. In addition, there might still be cases where images appearing later in the page might be more appropriate as page images than the image selected from the lead section. This overwrite would give editors control over selecting these images.
== Acceptance criteria
[] Create markup that allows editors to assign any image present on the page as the page image
[] If multiple images are assigned, the first instance will be the image used
[] If the image assigned is no-longer present on the page, we must default back to selecting the image as the first image from the lead section or infobox
[] If an user-selected image is no longer available on the page, the default image for the page will be used
[] If the image the user selects is not available on the page, the user must see an error upon saving their edit
[] If the image the user selects is of resolution lower than the minimum requirements, the user must see an error upon saving their edit
[] Add page image sourcing as per https://phabricator.wikimedia.org/T91683#4088612
=== Markup
```
{{#pageimage:Foo.jpg}}
```
sets the page image to Foo.jpg if Foo.jpg is in the page.
If Foo.jpg is not in the page the command is ignored.
```
{{#pageimage:}}
```
does not blank the page image.
==== The algorithm
Will consider the page image provided by the user.
* If the image is a bad choice (has a negative score) it is ignored. No feedback is given to the user.
* If the image is not in the page it is not used. No feedback is given to the user.
* If the image has a positive score, it is used regardless of whether there is an image with a higher score.
* If the image is an empty string is has no impact on the image choice. No feedback is given to the user.
== Sign off steps
Note: Allowing images from outside in a risky change and outside the scope for this task, but we'll want to consider that as part of sign off.
Risk:
* Currently we limit images to the lead section on Wikipedia, after these changes are in a place, we may want to relax this. This adds risk however as it means we may expose many unsuitable images where previously we showed none.
* There is a danger we may need to revert the change and run maintenance scripts to revert it. We should be prepared
* The page image choice bubbles into the services layer, so we'll also need to make them aware of the change.