ISIS Documentation
Backward Compatibility PolicyPolicy for ISIS backward compatibility for users | Home |
Objective
Define an ISIS compatibility policy between releases of ISIS that minimizes impact on the user base while allowing the future growth and the maintainability of ISIS.
Scope
The scope of document is to describe how the ISIS development team will promote backward compatibility for individuals and groups developing scripts and pipelines that use the ISIS application programs to process images. It is not intended to cover backward compatibility of the API; that is, for those few people outside of the USGS developing new ISIS programs.
User Expectations
“Backward compatibility for any software platform is a high priority. Clean, maintainable code is also a high priority for any software platform. Sadly, in practice, these two ideals are often at odds. Providing backward compatibility support makes software more complex and less maintainable.” [1]
Both the ISIS developers and users are responsible for facilitating a quality backward compatibility plan that meets the objective. As such, users are expected to:
- Recognize 100% compatibility is not achievable
- Read the release notes
- Read our backward compatibility notes
- Be cognizant of deprecated programs and parameters
- Use full parameter names and values for ISIS programs in scripts
Software Developer Expectations
The USGS ISIS developers can make the largest difference in promoting backward compatibility. They are expected to:
- Adhere to development standards
- Follow the clearly defined development process
- Write well designed user interfaces
Techniques for Achieving Backward Compatibility
This section list techniques that ISIS developers will use for providing backward compatibility.
Follow the Checklist
Any change to ISIS requires the developer follows a checklist. A box on the checklist addresses backward compatibility. If you don’t check this box you must note a backward compatibility issue in the release notes (XML history or C++ header).
Follow the Parameter Naming Standards
A checkbox exists for following parameter naming standards as found on the internal ISIS Wiki development page. Verify that parameters names are consistent so that they don’t need to be changed in the future.
Major Program Changes
If major program changes are made to a significant ISIS application (e.g., cam2map) it is probably best to create a new program name. For example, if we are going to rework the entire photometric normalization package we should leave the “photomet” program alone and write an new program called “photometry”. The photomet program must be deprecated in the future to prevent code bloat and maintenance issues.
Program and Parameter Deprecation
Document when programs and/or parameters will be deprecated, typically a one year notice. This will give users the chance to fix their scripts and pipelines
Consider the Cost Impact to both Users and Programmers
This is obviously difficult, as a programmer wants to develop clean easily maintainable code. Sometimes that means changing the user interface which impacts user. Think about how many users you will be impacting. Is it a commonly used program versus one that isn’t? Likewise, think about the long-term software maintenance that goes into supporting compatibility. Are we doubling the code base for an application? Unfortunately there is no great answer here other than you are going to either frustrate users by breaking their scripts or frustrate developers by having them maintain much more code or frustrate Astrogeology project chiefs by taking longer and increasing costs to develop the code while adhering to backward compatibility.
Address Most Common Problems
Users have identified changing parameter names and defaults are some of the most common backward compatibility problems. When possible, do not make these changes. A second area is changing the contents of output of PVL or text files. For example, programs like “stats” which produced textual output that can be used in scripts.
When Compatibility is Broken
Unfortunately there will be times when compatibility is broken. The best answer is to provide quality documentation so that the user is aware of these changes. Hence, the User Expectations to read the release notes and compatibility notes.
The ISIS release notes for an application or API change should contain the tag “Backward Compatibility Issue” when we believe we have impacted how a program operates in scripts. Be aware there may be multiple instances of the tag in the release notes.
In addition, in the release notes there is ISIS documentation with a table listing:
- Program names that have been removed
- Parameters that have been deleted
- New parameters that have been added without defaults
- Parameters that have had the default value changed
Footnotes
None