>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #648218. --> Reported by: [solotandem](https://www.drupal.org/user/240748) >>> <p>The current workflow for documentation of core API changes involves redundant posting in multiple places, is not easily tracked for updates, and does not utilize well the existing Drupal infrastructure. We can easily improve on this situation as indicated below.</p> <p>As I understand it, the current workflow involves these steps:</p> <ul> <li>Submit an issue in the D7 issue queue.</li> <li>Resolve the issue.</li> <li>Submit a patch that the testbot is happy with.</li> <li>Commit change to core.</li> <li>Reference the change in the chronological log (the top portion of <a href="http://drupal.org/update/modules/6/7">http://drupal.org/update/modules/6/7</a>) and document the change in the bottom portion of the same page.</li> <li>Cross-reference the change in the categorical page (<a href="http://drupal.org/node/394070">http://drupal.org/node/394070</a>). (New this year)</li> <li>Add an issue to the <a href="http://drupal.org/project/issues/coder?text=&amp;status=Open&amp;priorities=All&amp;categories=All&amp;version=All&amp;component=Upgrade+Routines">Coder queue</a> under the "Upgrade Routines" component. (New this month)</li> </ul> <p>The last two steps are new to the workflow this year, initially to assist the Coder module developers. In addition, the categorical page provides everyone with a topical list of the changes.</p> <p>Problems with the current workflow include:</p> <ul> <li>Revisions to an issue are not easily tracked in the details or on the categorical page. If the issue is updated, then there is no mechanism to alert the Coder developers of this, or anyone else interested in the change.</li> <li>The log page is one big ugly scroll.</li> <li>The work flow does not take advantage of the existing module facilities (e.g. Project or Views).</li> </ul> <p>To improve on this process (beginning with the D8 changes), we can:</p> <ul> <li>Create a "placeholder" project for the API changes related to core.</li> <li>Once a change is committed to core, add an issue to the API changes module with the details. This is identical to the current work flow except the information is posted in a different place.</li> <li>Tag the issue based on Unstable release number and the categories it applies to (in the same way done on the categorical page).</li> <li>Change the Coder Review and Upgrade flags as rules and routines are written.</li> <li>Questions and clarifications about the change could be posted as comments on the issue. (This could significantly improve the post as with comments on the api.drupal.org site.)</li> <li>If the change is later modified, reset the Coder Review and Upgrade flags to reflect this.</li> <li>Use views to create the current chronological and categorical documentation pages from the individual issues. The chronological page will be limited to the log at the top of the current page, with each item linking to the individual issue page containing the details. This eliminates two of the current cross-reference steps (adding a Coder module issue and the categorical page item).</li> </ul> <p>Please offer your comments and suggestions for modification.</p>