Change records

Last updated March 26, 2013. Created by marvil07 on October 19, 2011.
Edited by quicksketch, Cottser, Transition, xjm. Log in to edit this page.

This page explains what Change records are and how to use them. Previously, change records were called "change notices". The terms may be used interchangeably by developers but the term "change record" is preferred.

What are Change records?

A Change record is a node that lets you specify important changes to your Drupal project.

A feature of drupal.org, each Change record includes information such as the project version and branch in which the change was first applied, references to related issues, a description of the change, and any groups which the change impacts.

As such, Change records make it easier for project maintainers to document and inform developers, themers, site builders, and technically-minded users about important project changes.

Change records are editable and revisions are stored for each edit, just like this documentation page.

Why and when to use Change records

Historically, project changes have been handled by writing a documentation page explaining each change and have necessitated manually linking to all issues associated with that change. This is exactly what Change records want to rectify.

All project maintainers can create Change records for their own projects. Normally, you would create change records after the change has been committed to your project.

They are primarily useful for other contributors to your project, and other developers and people with a technical background, to understand the technical details of changes to your project.

You can view a list of changes for your project by visiting:
http://drupal.org/list-changes/[your project's short-name]

i.e. Change records for Drupal core.

There is also a link to view change records in your project page's sidebar, in the Development section.

How to create a Change record

Go to Create Change record.

Complete the 'Create Change record' form by entering the following information:

• Title
• Project - the name of the project with which the Change record is associated.
• Introduced in branch - the branch in which the change was first applied.
• Introduced in version - the release name (tag) in which the change was first applied.
• Issues - list any issues related to the change.
• Description - a high level summary of the change, its impact on site users, site builders, themers, and module developers.
• Impacts - select which groups the change impacts. For example, API changes will primarily impact module developers, while new theme functions will primarily impact themers.

How to write an API change notification

1. Find an issue tagged as Needs change notification to write an API change notification for.
2. Assign the issue to yourself and leave a comment saying that you are going to write the API change notification.
3. Read the comments of the issue to understand the nature of the change.
4. Review the accepted patch attached to the issue. You may find Dreditor useful for reviewing Drupal patches.
5. Find all the API functions in the patch. Functions that begin with an underscore, e.g. _like_this(), and test functions are not API functions. Any other function is public and part of the API.
6. Changes to hook functions are especially important because they affect all implementations of the hook. The hook definitions are in the *.api.php files, with documentation and (usually) sample code. If the signature of a hook function and all of its implementations have changed, do not list changes to every single implementation of the hook function. Instead, describe the change to the hook definition and just say that all of its implementation have been updated accordingly. See the API change notifications for issues #1291100: Remove category system from user edit and view and #1377628: taxonomy_get_term_by_name() should be taxonomy_term_load_multiple_by_name() for examples.
7. Finally, mark the issue as fixed and restore its attributes, e.g. the title, priority, etc., to whatever they were before the change notice.