Last updated 28 April 2017.

On this page:

To get help completing this task, see the Getting help completing your task page.


Create a "change record" node to describe a change that was made to Drupal Core.

Skills needed

You need to be able to read English well enough to understand an issue, and write English coherently. You also need to be able to read and understand a code patch (generally PHP, with perhaps some CSS, JavaScript, etc.).

Writing style

Use tenses to your advantage. Use the past tense to describe how things were before the change, and the present tense for how things are now.

Be concise. A short, scannable change record is preferred to a long one with excessive background information.

Detailed steps

  1. Find issues for Drupal core.
  2. Use the advanced search to find an open issue tagged with Needs change record. If there are not any, you will need to find another task to do.
  3. Click through to the issue, and verify that:
    • It does not already have a change record present at the bottom of the sidebar. Here's an example of an issue that already has a change record:
      Issue summary with change records
    • No one else has recently assigned the issue to themselves saying they are writing the change record for it.

    If there is already a change record present, or if someone else is already working on writing the change record, find a different issue to work with. You will need to be a confirmed user in order to edit a change record created by someone else should changes to the change record be requested in the issue.

  4. Assign the issue to yourself and leave a comment saying that you are going to write the API change record.
  5. Read through the issue summary (if there is one), or the issue comments (if there is not one or it lacks detail), and also the committed patch, to figure out what the change was, and what the impact of the committed change was on:
    • Drupal users (site builders, administrators, editors) - user interface changes - these will probably be described in issue comments or in the issue summary.
    • Module developers - API function/class changes. You will need to look through the patch to find any functions etc. that have changed, with the exception of "internal-use" functions whose name starts with an underscore. Hook definitions deserve special notice: hook definitions are in *.api.php files, with documentation and (usually) sample code. If the signature of a hook function and all of its implementations have changed, you will just need to describe the changes to the hook definition and mention that all the implementations have been updated, rather than listing all of them.
    • Themers - theme function/template changes. Again, read through the patch to find these.
  6. Create a draft change record node. Fill in:
    • Title - Short description about what is new. In general, do not just copy the issue title. The title should be clear and specific so that people can easily see if it is relevant to them when searching the change record list.
    • Project - Drupal Core
    • Published - Whether the proposed change has been committed to core. Leave this unchecked to create a draft change record.
    • Introduced in branch/version - usually people just fill in the branch (8.x, 7.x, etc.) and leave the version blank.
    • Issues - start typing the title of the issue you are writing the change record for, and you should be able to choose it from the list.
    • Description - detailed description of the changes you identified (see below).
    • Impacts - check boxes based on who you identified would be impacted by the change

    See the background section below for links to more information.

  7. Write up a brief description of the change and post it in the description field of the draft change record. Suggested format:


    • Bulleted list here.
    • Another point.


    // Example code before the change here, probably D7


    // Example code after the change here, probably D8
  8. Save the change record node.
  9. Refresh the issue page, and verify that your new change record shows up at the bottom of the sidebar.
  10. Edit the issue node:
    • Un-assign the issue.
    • Set the issue to Needs review for the change record to be reviewed.
    • Remove the "Needs change record" tag (above the comment field).
    • Add a comment saying that you have created the change record, and include the URL of the change record into your comment.

    Save the issue (which makes all of these status changes).

  11. Watch the issue for feedback on your change record.
  12. Once the issue is Reviewed & Tested by the Community and subsequently accepted and committed by a core maintainer, the change record can be published. Do not check the "published" checkbox until the patch is committed and the issue is fixed.

Background and reference information

Next steps: moving beyond this task

Try some of the other tasks in this section, such as creating a patch for an issue, or writing a test.