Add change records to all @deprecated code

Problem/Motivation

Drupal 8 has adopted a new deprecation policy to make it easier for developers to update outdated code: https://www.drupal.org/core/deprecation

One new part of this policy is that deprecation notices should have a change record listed with an @see that clearly indicates how to update the deprecated code. For example:

 * @deprecated in Drupal 8.0.0 and will be removed before Drupal 9.0.0.
 *   Instead, you should just check if a variable is an instance of
 *   \Drupal\Component\Render\MarkupInterface.
 *
 * @see https://www.drupal.org/node/2549395

However, we have hundreds deprecated notices in core that do not yet have the appropriate change record listed.

Proposed resolution

Read over the steps below before you start.

Try reviewing existing issues before creating more new ones. If you understand the instructions well, before creating a new issue, check to see if there are existing child issues that need review (yellow background) in the right sidebar on this page, and use the instructions as a guide to evaluate another contributor's existing patch.

1. Look for an @deprecated tag in core. (There are hundreds!)
2. Look for or create an issue for one you find with this issue as its parent. Make sure to look at the existing child issues to make sure you don't accidentally create the same issue twice!
3. Check when the @deprecated notice was added using git log -L. Reference: https://dev.acquia.com/blog/maintainers-toolbox-git-blame
4. The issue for the commit will be included in the commit message with text like:
   Issue #2575615 by alexpott, pwolanin, stefan.r, catch, dawehner, effulgentsia, xjm, David_Rothstein, iMiksu, lauriii, joelpittet: Introduce HtmlEscapedText and remove SafeMarkup::setMultiple() and SafeMarkup::getAll() and remove the static safeStrings list
   Visit the issue node by going to that node ID on Drupal.org, e.g.: https://www.drupal.org/node/2575615
5. Look in the old issue's right sidebar for the issue node for any change records it:
   
6. If there is a single change record, look it over to make sure it has instructions for how to replace the deprecated code.
7. If there are multiple change records, look over each to see which best explains how to replace the deprecated code.
8. If there are no change records attached to the issue, see below for what to do if you cannot locate a change record.
9. Check in the same file and the same commit to see if there are other @deprecated notices that should have the same change record.
10. Create a patch that adds an @see linking the change record as in the example above, and set your issue to needs review.

Examples of where it went right

In #2873721: Add Change record to @deprecated for MigrateIdMapInterface, it was noted that effort went into seeing what was the original issue(s) that made the change. Then the final patches and commit from the original issue(s) was inspected to make sure that all deprecations are/were updated to reference the @see to the change record. Later on, the reviewer checked this as well and noted in his review that he verified there were no other places where the deprecation notice should be updated.

Examples of where some things were missed

In #2873738-10: Add Change record to @deprecated for LinkUri, it was noted that not all of the deprecations where caught. The review and initial patches earlier on also just checked for code style and if the CR was linked correctly. It did not note if all locations seem to be caught. By checking the original commit that introduced the deprecation it can be noted that changes where made to several classes. All the deprecations should note the @see.

If you cannot find a change record

If there is no change record attached to the issue for the deprecation, there are a few possibilities:

• The change record wasn't attached to the issue properly
• the deprecation was done in a separate issue from the API addition without the change record being updated.
• No change record was ever created for the change (by mistake, or because it was considered too trivial, or because it was part of a larger change or pattern).
• The deprecation itself was premature or incorrect and no replacement API exists yet.

What to do when you can't locate the change record:

1. First, make note on your issue that you did not find a change record directly attached to the issue where the @deprecated line was committed.
2. Then, search the existing change records related to the API: https://www.drupal.org/list-changes/drupal Be sure to search under both the "Published" and "Draft" change records, and try a few different keywords.
3. If you find a change record that seems related, read over it to see if it has information on updating the deprecated code. Also make note of any other issues attached to the same change record, since one change record may cover many issues. These issues might help you understand more about the deprecation.
   
4. At this point it's a good idea to check with a mentor or reviewer to see if the change record you've found is a good fit. Post a comment on your issue linking whatever change records you've found. Contributors to the original issue or maintainers for the subsystem might be able to give you quick feedback; try asking in IRC. Even if no change record was ever created for your specific issue, it's often better to add to an existing change record rather than creating a new one.
5. If you find a change record that seems like a good fit:
   • Click the "Edit" tab on the change record.
     
   • Add a reference to both your issue and the issue that introduced the deprecation.
     
   • If the change record does not yet clearly cover your change, you can also edit the change record to address it. Link your revision on your issue to get review on that as well! Ask reviewers for help if you're not sure what to add.
6. If no change records are a good fit, then you can draft a new one at: http://drupal.org/node/add/changenotice Follow the instructions on: https://www.drupal.org/contributor-tasks/draft-change-record

   As above, be sure that your new change record references both your issue and the original issue that introduced the deprecation.

7. Finally, continue with the next steps above, including checking other deprecations in the same commit or the same file and seeing if they also should share the same change record.

An example where the CR didn't exist is #2873742: Add Change record to @deprecated for Term. This was noted, then the related issue was found, reviewed for impacts and a new CR was created at https://www.drupal.org/node/2879193.