User Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Contributor Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Quick Links

Software Manual
API Reference

Documentation Versions

Public Release


Technical Documents

ISIS 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.

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:

Software Developer Expectations

The USGS ISIS developers can make the largest difference in promoting backward compatibility. They are expected to:

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: