Change records now needed before commit

xjm's picture

Starting February 14, issues that require API change records must have these change records written before patches are committed. This is Drupal 8 core's valentine to contributed modules. :)

What issues are affected?

Any Drupal core issues that introduce backwards-compatibility-breaking API changes are required to have change records documenting the change. Up until now, these change records were created after the issues were committed. Going forward, the change records need to be written and reviewed before the issue is marked RTBC.*

* Note that in rare cases, core maintainers may allow certain critical patches to go in before the change record is written, for example, in the case of a critical bug, or a high-impact issue that is blocking other work, but please don't count on that. ;)

How does the new process work?

  1. Follow the normal development process while the patch is being worked on.
  2. Make sure the API change tag is added to issues that break backwards compatibility. (In general, API changes should be documented in the issue summary.)
  3. Once you get the API change approved by a core maintainer, the Needs change record tag can be added to the issue. (Note that the previous tag "Needs change notification" is no longer used.)
  4. Create a change record with the Published checkbox unchecked (the default option), and then remove the "Needs change record" tag from the issue. (All draft change records can be found on the draft change record list.) The 'published' field on change record nodes
  5. In order for the issue to be marked RTBC and committed by a core maintainer, a draft change record documenting the approved API changes is required.
  6. Once the patch for the issue is committed, the core maintainer will simply mark the issue fixed (like any regular issue). The "Published" checkbox can then be checked to make the change record appear in the main Change record list.

Why are we making this change?

As we complete Drupal 8 APIs and move toward the first Drupal 8 beta, it's increasingly important that our API documentation is accurate, including our API change records. With the previous process, change records have gone unwritten for months -- 24 change records are still outstanding. Furthermore, the previous process (wherein the issue title, status, priority, category, and tags were all changed) was also convoluted and error-prone, and interfered with accurate core metrics.

Sounds great! How can I help?

We need your help to get both outstanding and upcoming change records written so that core and contrib developers can use this critical documentation. Help us stabilize our APIs by: