The public API is considered to be all the interfaces that the ISIS project provides to the community from which the ISIS user base can build more complex tools. This API therefore includes code-level structures accessible via software calls to libraries, but also more user-facing structures like command-line programs and graphical user interface (GUI) programs. Any "interface" via which a user can reasonably interact with components of the ISIS project should be considered part of the "ISIS Project public API" for the purposes of Semantic Versioning.
Examples are provided below, but are not meant to be exhaustive or complete. The above philosophy should guide our thinking in what the public API is. The above API definition should be used with Semantic Versioning policies to determine when and how the ISIS version number changes. A FAQ and some examples can be found on the Semantic Versioning website.
The public API consists of the following.
Code-level structures: Public function, member, and class names, argument signatures, and their return signatures. Where "public" is defined as those elements that are typically provided for use external to a library or module, dependent on the language.
Some examples are:
- C++ public structures are those that can be access by including the distributed header files for libraries.
- Python public structures are those that do not begin with an underbar ("_"), as described in PEP 8.
User-facing command-line and GUI programs: program name, argument list, argument defaults, configuration or preference names and their defaults, and for those programs with structured output files, the structure of those output files are analogous to the return signatures of code-level structures.
This guidance may be more straightforward to understand and apply for code-level structures which have more formalized argument and return signatures. User-facing command-line and GUI programs should include verbose information in their documentation that describes what a user can expect as far as the structure of the output.
Adding new arguments to code level structures does not violate the existing public API as long as they provide a default value. For example changing a function doThing(int a, double b) to doThing(int a, double b, double c=1.0) does not violate the existing API for the doThing function as code that calls the doThing function will still compile without modification.
Adding new optional arguments or arguments with default values to command line programs does not violate the existing public API. For example, adding a new argument called "check" that has a default value of "false" to a command line program does not violate the program's public API as scripts and commands that were valid previously are still valid after the addition.
For anything of an inherently unstructured file-type, like .txt; there is no guarantee of its contents; just that it will exist. For example, no guarantee of the contents of the bundleout.txt files generated by jigsaw is expected. They are purely human-readable output and not designed to be parsed programmatically. So sections can be added, removed, spacings on tables can be changed, etc.
Column names and data types are part of the API.
For example, a program that writes out a CSV should clearly describe the output columns which include the fieldname, data type, and whether non-data-type values can be present (e.g. a column of floating point numbers named "minimum" that could contain the string "NULL" instead of a floating point value).
New columns can be added (feature), but if a column's characteristics are changed or removed, that's a breaking change.
Object, group, and keyword names are a part of the API.
For example, the "minimum" keyword will exist in the "statistics" group. This also applies to the PVL labels in Cube files.
New aggregates or keywords can be added (feature), but if any are changed
or removed, that's a breaking change. PVL text does have data types, and
changing something from MIN = 5 to MIN = "5" is changing the data type
of the keyword MIN from an integer to a string.