Proposals:DeprecationProcedure: Difference between revisions
No edit summary |
No edit summary |
||
| (3 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
The following is the draft of the policy on backward compatibility from the ISC | == Backward Compatibility == | ||
=== The following is the draft of the policy on backward compatibility from the ISC === | |||
The developers of open-source software toolkits should make every effort to maintain backward compatibility within its major versions (e.g., from Version 1.2 to 1.3). Specifically, the API of the existing methods should not change, the API of technologies used internal to the methods (e.g., the streaming system) will not change, and the API of new methods will conform to that of the existing methods. | The developers of open-source software toolkits should make every effort to maintain backward compatibility within its major versions (e.g., from Version 1.2 to 1.3). Specifically, the API of the existing methods should not change, the API of technologies used internal to the methods (e.g., the streaming system) will not change, and the API of new methods will conform to that of the existing methods. | ||
| Line 6: | Line 8: | ||
* Intent to release a major update must be announced to the developers 3 months in advance | * Intent to release a major update must be announced to the developers 3 months in advance | ||
* Every API change will be well documented in a | * Every API change will be well documented in a single descriptive file, included with the distribution | ||
* Every effort will be made to provide scripts to facilitate user software updating | * Every effort will be made to provide scripts to facilitate user software updating | ||
* | * Deprecated files will be moved to a deprecated directory. | ||
* Files in the | * Files in the deprecated directory from the last major update will be removed. | ||
* | * Deprecated methods will display an appropriate warning at runtime when used within a program. The warning should describe the means of fixing the compatibility issue. | ||
* | * Deprecated methods from the last major revision will be removed. | ||
Bug fixed should be applied to a branch of an old version only when specifically requested, when it will benefit a sufficient number of users, and when it will not cause an API change. Users should instead be encouraged to adopt the current release. | Bug fixed should be applied to a branch of an old version only when specifically requested, when it will benefit a sufficient number of users, and when it will not cause an API change. Users should instead be encouraged to adopt the current release. | ||
| Line 18: | Line 20: | ||
This policy is being reviewed and modified by an ISC subcommittee, consisting of Ross Whitaker, Bill Lorensen, and Will Schroeder. Comments/suggestions are welcome! | This policy is being reviewed and modified by an ISC subcommittee, consisting of Ross Whitaker, Bill Lorensen, and Will Schroeder. Comments/suggestions are welcome! | ||
{{ITK/Template/Footer}} | |||
Latest revision as of 20:38, 20 December 2005
Backward Compatibility
The following is the draft of the policy on backward compatibility from the ISC
The developers of open-source software toolkits should make every effort to maintain backward compatibility within its major versions (e.g., from Version 1.2 to 1.3). Specifically, the API of the existing methods should not change, the API of technologies used internal to the methods (e.g., the streaming system) will not change, and the API of new methods will conform to that of the existing methods.
Across major versions (e.g. from Version 1.x to 2.0), the APIs of the toolkit may change if it is in the best interest of the toolkit so as to provide effective and consistent implementations of the methods and features that are being sought by its users. When making a major version release, the following should be considered:
- Intent to release a major update must be announced to the developers 3 months in advance
- Every API change will be well documented in a single descriptive file, included with the distribution
- Every effort will be made to provide scripts to facilitate user software updating
- Deprecated files will be moved to a deprecated directory.
- Files in the deprecated directory from the last major update will be removed.
- Deprecated methods will display an appropriate warning at runtime when used within a program. The warning should describe the means of fixing the compatibility issue.
- Deprecated methods from the last major revision will be removed.
Bug fixed should be applied to a branch of an old version only when specifically requested, when it will benefit a sufficient number of users, and when it will not cause an API change. Users should instead be encouraged to adopt the current release.
Users are strongly encouraged to consult a toolkit’s web pages and join its user’s list to stay current on the changes occurring within the toolkit. Archiving your installation prior to upgrading to a new major version is also recommended.
This policy is being reviewed and modified by an ISC subcommittee, consisting of Ross Whitaker, Bill Lorensen, and Will Schroeder. Comments/suggestions are welcome!
