Change notification F. Brosnan Advanced Software Production Line, S.L. November 11, 2008 Change notification procedure 1. Motivation Current software API policy followed by ASPL for its projects enforces that no API can be changed, modified, extended, etc, once a release is done including the API required to change. However, in a broad manner, the following situations are accepted to perform such changes: 1. The change proposed (usually in the form of API change) is to fix an API that is known to produce bad results. 2. A collision found in the naming convention with some symbol already defined. This policy tries to ensure that the user already linked to a particular API can run its software in the future. As a side effect, it is found many cases that would be more easy to just change the API, waiting general API consumers to find and react against the problem (which is also we dislike when we suffer it). This document presents a procedure to propose, accept and notify product changes, usually API changes, that seeks to improve the product quality/features but makes it incompatible with previous releases. The procedure is composed by an operation flow and a format to be followed to perform notifications. The operation flow describes under which conditions runs the process to propose, accept, and notify changes, while the format includes a detailed description that must fulfil a change notification. The main idea behind the proposal is to have the ability to perform changes in a more flexible manner, while we keep informed and up to date with all changes introduced on each release, including all fixes required to translate from previous versions to new ones. 2. When it is required to propose/notify? In the following situations will be accepted to propose change Brosnan [Page 1] Change notification Change notification procedure November 2008 notification: 1. API function rename, removal or modification. This is the usual case found: a function have a missing parameter, a wrong misspelled name or it is a symbol no longer used. 2. Internal software product modification making it incompatible in some way with previous releases. The process to propose changes is open to anyone, that follows rules described in this document. 3. Propose/Dropped/Accepted/Notify state Once a change notification is required to be proposed, it will be identified by a unique name, that will allow to refer to it in the future. Under this state, it is say that the change notification is in "Propose" state. Now the change notification can be made public, announcing it on the mailing list for the product that applies. It is also required to place the change notification document into a usual location into the project webpage. Once the change notification is evaluated, taking into consideration project main developers opinion, the change notification could be rejected, flagging it as "Dropped" or accepted to be included as "Accepted". In the later case, it is required to report which is the version that will include the change proposed. Finally, inside the release note done for the project that includes the change, it is required to place a reference to all accepted changes introduced. +---------+ +----------+ +--------+ | Propose |----->| Accepted |----->| Notify | +---------+ +----------+ +--------+ | | +---------+ +---->| Dropped | +---------+ 4. Who have the last decision to include a change? ASPL. Brosnan [Page 2] Change notification Change notification procedure November 2008 5. Change proposal format There is a template for the change proposal at: http://www.aspl.es/change/change-notification-format.txt The format described is pretty straightforward. It includes a unique number provided by the core development team, the project that applies, a reference to the release that will include the change (if it is known), current change acceptance status and the author that is behind the change. In the next sections it is required to include a description about what is being changed and how to solve problems introduced by the change. Finally, three references are mandatory: project url ref, project change notification ref, that is, the page where all change notifications proposed can be located and a reference to this document. Author's Address Francis Brosnan Advanced Software Production Line, S.L. C/ Antonio Suarez No10, Edificio Alius A, Despacho 102 Alcala de Henares, Madrid 28802 Madrid Phone: 00 34 91 134 14 22 Email: francis@aspl.es URI: http://www.aspl.es Brosnan [Page 3]