GT Backward Compatibility
From Globus
Contents |
About this document
This document outlines a set of backward compatibility guidelines for the Globus Toolkit project. Its purpose is to create a shared understanding of backwards compatibility, and to provide guidance to GT contributors.
The guidelines are not prescriptive: responsibility for setting BC policy rests with individual projects. However, projects should be mindful of cross-project dependencies when setting policy, as the potential exists to create a ripple effect (e.g., RFT introducing an incompatibility has the potential to affect future GRAM releases.) In general, ongoing cross-project communication on this topic is a good idea.
This document is a work-in-progress. All are invited to send comments or questions about this material to gt-dev@globus.org; please include the phrase [COMPAT] in the subject of the mail and avoid cross-posting. Members of the Globus community are invited to add new implementation approaches to section 4.
Thanks to 1cc, Allcock, Bacon, Carlkesselman, Fang, Foster, Gawor, Gregor, KarlCzajkowski, Laura, Peter, Rachana, Tuecke and Vwelch for their contributions to this document.
Guiding principles
As a matter of course, consider following these "words to code by":
- The implementation should interoperate with others created by different individuals [RFC 791]
- The implementation should be conservative in its sending behavior and liberal in its receiving behavior [RFC 791]
- Changes to existing interfaces should be avoided if possible
- The frequency of interface changes should be minimized
- Backward compatibility should be maintained unless there is a compelling reason not to
- If a standards-based feature is not implemented properly by third party software, don't base your code on the broken behavior
An observational view: backward compatibility profiles
| Old servers, serverside libraries & tools | New servers, serverside libraries & tools | ||
|---|---|---|---|
| Backward Compatibility Profile 1 (BCP1): fully backward compatible | Old clients, clientside libraries & tools | do work with | do work with |
| New clients, clientside libraries & tools | do work with | do work with | |
| Backward Compatibility Profile 2 (BCP2): partially backward compatible | Old clients, clientside libraries & tools | do work with | do work with |
| New clients, clientside libraries & tools | do not work with | do work with | |
| Backward Compatibility Profile 3 (BCP3): not backward compatible | Old clients, clientside libraries & tools | do work with | do not work with |
| New clients, clientside libraries & tools | do not work with | do work with | |
A collection of implementation approaches
This section contains a collection of implementation techniques for addressing backward compatibility under various scenarios. Know of an approach that has yet to be documented? Consider sending a mail to gt-dev describing it, or add it yourself by creating a new "Approach" page (GT_BCompat_Approach_n+1) and linking to it from the table.
grey cells indicate that the issue of backward compatibility is not applicable
red cells indicate that the issue of backward compatibility will be ignored
| Potential Triggers of Backward Incompatibility | Potential Points of Backward Incompatibility | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| 1: Protocol communications between new server and old clients | 2: Protocol communications between new clients and old server | 3: API calls from old applications & plugins to new libraries | 4: API calls from new applications & plugins to old libraries | 5: Porting old scripts (wrappers around command clients) to new scripts | 6: Porting old configuration files to new config files | 7: Porting old log analysis (auditing, &c.) to new log analysis | 8: Automated installation/ repackaging of new component | ||
| a: add operation to WSDL | Approach #1 (BCP1), Approach #2 (BCP2) | Approach #1 (BCP1) | Approach #1 (BCP1), Approach #2 (BCP2) | ||||||
| b: remove operation from WSDL | Approach #2 (BCP2) | BCP3: no known approach for this scenario | Approach #2 (BCP2) | ||||||
| c: change WSDL operation param | Approach #2 (BCP2) | BCP3: no known approach for this scenario | Approach #2 (BCP2) | ||||||
| d: add resource property | Approach #1 (BCP1), Approach #2 (BCP2) | Approach #1 (BCP1) | Approach #1 (BCP1), Approach #2 (BCP2) | ||||||
| e: remove resource property | Approach #2 (BCP2) | BCP3: no known approach for this scenario | Approach #2 (BCP2) | ||||||
| f: change WSDL namespaces | Approach #2 (BCP2) | BCP3: no known approach for this scenario | Approach #2 (BCP2) | ||||||
| g: change class namespace | Approach #3 (BCP1) | ||||||||
| h: add to public api | |||||||||
| i: remove from public api | Approach #3 (BCP1) | ||||||||
| j: change class name | Approach #3 (BCP1) | ||||||||
| k: change semantics | |||||||||
| l: change commandline interface | |||||||||
| m: change configuration interface | |||||||||
| n: change build/install procedure | |||||||||
| o: change logging output | |||||||||
| p: change runtime dependencies | |||||||||
| q: change compile-time dependencies | |||||||||
