ISIS 3 Documentation
Backward Compatibility Policy
Policy for ISIS backward compatibility for users
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.
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.
“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.” 
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:
The USGS ISIS developers can make the largest difference in promoting backward compatibility. They are expected to:
This section list techniques that ISIS developers will use for providing backward compatibility.
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).
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.
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.
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
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.
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.
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: