Proposals:DeprecationProcedure

From KitwarePublic
Jump to navigationJump to search

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!



ITK: [Welcome | Site Map]