Proposed in #Community-Wishlist-Survey-2016. Received 45 support votes, and ranked #27 out of 265 proposals. [[ https://meta.wikimedia.org/wiki/2016_Community_Wishlist_Survey/Categories/Multimedia#Notifications_for_when_your_image_is_used | View full proposal with discussion and votes here. ]]
----
(Old task description - updates are needed)
== Narrative ==
As a user, I want to know if know if my file was used in an article, so I can see how it was used -- and feel good that my work is useful.
== Acceptance Criteria ==
We want to let users know if a file they uploaded (or overwrite.
To that end, we need to do the following:
* Check the Global File Usage API to see if a file I uploaded has been used recently
* If a file has been used since the user's last file notification, show a **file notification** (e.g. '<file name="">was used by <username>on '), on the web (and via email if the user has email notifications enabled)</page></username></file>
* We would leverage the [[https://www.mediawiki.org/wiki/Echo | Echo notifications]] infrastructure to make this happen
* The proposed specsfor this new notification are listed in the Echo section below, as well as on the [[https://www.mediawiki.org/wiki/Echo_(Notifications)/Feature_requirements#File_Used | Echo Feature Requirements]] page.
* We would also use [[https://www.mediawiki.org/wiki/Echo/Feature_requirements#Bundling | Echo's bundling feature]] to make sure we don't flood the user with too many notifications in a row for the same file (same as what we did for Page Link notification bundling)
== Design Notes & Mockups ==
This is a very rough mockup from our [[http://www.mediawiki.org/wiki/Echo | Echo]] tool, in case you're not familiar with this project.
The actual text and icon of the notification will be different, as specified on this card.
{F19805, size=full}
== Tasks ==
* Use the Global File Usage API to trigger each notification
* Look up all users who uploaded or edited a file that was just used
* Use the Echo extension to show/send notifications to those users
* Bundle the notifications if multiple pages use this file within the same 4-hour period
== Echo Specs ==
This notification occurs when a media file you uploaded or edited is used on a page:
**Golden-crowned sparrow close-up** was used by **Smallbones** on <**Bird Migration**> at English Wikipedia.
or, if the file was added to multiple pages since the last notification, bundle additional notifications as so:
**Golden-crowned sparrow close-up** was used on **Bird Migration** and 2 other pages at German Wikivoyage.
https://www.mediawiki.org/w/index.php?title=File%3AMultimedia_Vision_2016.pdf&page=32
Here are some key attributes for this notification:
* Trigger: User edit (on a page that now uses your file) > as reported by Global File Usage extension
* Main Link: page that uses your file (if only one page)
* Secondary Link: Commons file info page's File Usage section (ideally shown in Media Viewer, with meta-data panel open)
* Payload: None
* Frequency: Medium
* Priority: High (positive)
* Category: Media files
* Flyout Summary: [icon]**Golden-crowned sparrow close-up**was used by**Smallbones**on <**Bird Migration**>.
* All-notifications Summary: [icon] <golden-crowned close-up="" sparrow=""> was used by ~~ on **.</bird></smallbones></golden-crowned>
* Email Subject 1: Your file was used on Wikipedia
* Email Summary: <golden-crowned close-up="" sparrow=""> was used by ~~ on **. <view page="">.</view></bird></smallbones></golden-crowned>
* Web preference default: Enabled for all users
* Email preference default: Enabled for all users
* Web bundling: Enabled
* Email bundling: Enabled
* Dismiss feature: Enabled (web-only)
* Metrics group: Positive
* Metrics type: "file-use"
**Special requirements**: This notification will only be shown/sent to users on Commons -- as cross-wiki notifications do not currently work. It would be ideal if it could be sent to all users who uploaded or edited a particular file (not just to the uploader, who may no longer be active).
**New category**: Note that we need to create a new category called 'Media files' in [[https://www.mediawiki.org/wiki/Echo_(Notifications)/Feature_requirements#Notification_Settings | Notification settings]] , so that users can enable or disable these types of notifications.
**New icons**: We will also need to create a new icon for 'Media files' in [[https://www.mediawiki.org/wiki/Echo_(Notifications)/Feature_requirements#Icons_and_types | Icons and types]] , so that file notifications can be distinguished from others (if necessary, we could re-use the 'cross-reference' link icon, but a cool 'media' icon would make these notifications stand out more.)
**New metric type**: We also will need to add a new Metrics type to our schema: "file-use" -- as well as update notification dashboards for Commons, so we can track the usage of this notification.
----------
(Old task description, above)
== Questions and problems to consider ==
(please add more, or comment below...)
1. Single image opt-out. Example use-cases...
** I've uploaded a flag image, and it is used as an icon in thousands of places
** I've merely cropped/rotated an existing image, and am not interested in following it
** I've uploaded a new version of a file, and the original version was subsequently deleted
2. Who to notify:
** only the uploader of the original version.
** only the uploader of the original version, and the current version.
** All uploaders of the file.
** All uploaders who were not just `revert`ing to an earlier version
*** Some example images with >1 uploader: [[https://commons.wikimedia.org/wiki/File:Neptune_Full.jpg#filehistory|File:Neptune_Full.jpg]], and [[https://commons.wikimedia.org/wiki/File:John_Hewson.jpg#filehistory|File:John_Hewson.jpg]], and [[https://commons.wikimedia.org/wiki/File:Lyriothemis_acigastra_male_at_Kadavoor.jpg#filehistory|File:Lyriothemis_acigastra_male_at_Kadavoor.jpg]],