Home

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
AstroDiscuss
GitHub
API Reference

Documentation Versions

ISIS 2

Documentation
Tutorials
Technical Documents
USGS

ISIS Documentation

Developer

Modifying the ISIS software

Home

Introduction

This is a step-by-step guide describing the process for modifying ISIS. There are two broad categories of modifications, minor and major. Most of the steps below are the same for both categories. Where there are differences, it will be noted. Many of the steps in this guide are similar or identical to the guide to adding a new feature.

ISIS is used by individuals, small groups, and large instrument teams to process images returned from spacecraft throughout our solar system. If anything changes in ISIS, even if it is a correction to an error, those people may be impacted. The process outlined below contains key communication steps to assist everyone interested in understanding what changes are being made, what they will affect, and when the change is available. This is crucial for the individual who may spend hours tracking down a difference between a product made with one version of ISIS versus another. Instrument teams using compute clusters to process raw image data into products might process terabytes of data before finding discrepancies and have to backtrack through thousands of lines of code and database entries to find where a change adversely affected a product.

Many people have contributed code, documentation, answers, and suggestions to the ISIS software. As part of that community you should be familiar with the contributing guide.

ISIS library and the applications are written in C++ and are supported on Ubuntu Linux and Mac OS.

Resources

The ISIS library contains hundreds of support classes and functions. Every application takes advantage of these support routines to accomplish its tasks. We encourage you to get familiar with the library before modifying anything in ISIS. Many classes in the library make heavy use of other classes in the library

There are over 400 ISIS applications. Every one of them uses many routines in the ISIS library. We suggest you get familiar with as many of these as possible.

ISIS applications are linked against many useful external libraries. We encourage you to become familiar with these external libraries. A list of the external libraries ISIS uses directly can be found in the environment.yml file.

Getting the ISIS source code

All of the ISIS source code is available on GitHub. This GitHub source code repository is the primary Git repository for ISIS. If you are unfamiliar with Git and/or GitHub you should go through the GitHub getting started pages before you start writing code.

Steps to get ISIS source code on your local machine

  1. Setup a GitHub account
  2. Fork the ISIS repository
  3. Clone your fork to a local repository

Setting up an environment to compile and link ISIS

The ISIS package is written in C++. In order to run and test your new feature, you will need to compile the source code and link it against the ISIS library and the external libraries. Follow the instructions on the ISIS GitHub Wiki for building ISIS.

Depending on how your computer is setup, you may also need to install:

Once you have a complete environment set up for ISIS development, we suggest you compile and build all of ISIS. This step will make sure you have everything setup and ready to go.

Starting a conversation with other ISIS developers

Communicating your intension to modify ISIS is crucial and required. This communication starts with a GitHub issue in the ISIS code repository. Starting this conversation will allow other ISIS developers to way in on your preposed change. By posting a description of what you want to do and asking questions, other developers can give you pointers on how to implement it. Label the issue as a Bug for changes to correct errors, or Enhancement for changes to the way an application works or is controlled.

Once other developers have read your proposed change, they may concur with your idea (i.e., minor chage), or ask you to writeup a request for comment (RFC) (i.e., major change). When writing an RFC is required, be aware the process deliberately takes time.

Before Editing the Code

Naming Conventions and Code Style

When editing the ISIS code, be aware of the style the particular class or application is written with and try to follow it within reason. The naming conventions, have changed over the years and can be confusing, so don't mix two conventions in a class or application.

Testing

Applications and complex support classes in ISIS are required to have tests that exercise the majority of the their code. These test are written using googletest (aka, gtest). The source code for all gtests is located in the isis/tests directory. Create a new test file for your application with the name FunctionalTestsYournewapp.cpp, and one for each support class with a descriptive name. Write tests to exercise the application and any support classes. Remember to test only the functionality of your new code and not the ISIS library. Tests for the ISIS library already exist. See the guide for writing tests for detailed instructions.

There are extensive tests in the isis/tests directory for both classes and applications. Many still have the older style hand written tests located with the class and in the application's tsts directory. Before you make your modification we suggest you become familiar with the tests that directly involve your changes. If you are fixing an error, check the tests to see if what you are fixing is tested, and if so, verify the output before you start.

Make the Modification

Iterate over the steps below to make your change and thoroughly test the results

  1. Write or modify the code as needed for your change
  2. Compile your changes and re-link the applications (ninja)
  3. Fix any compile or linking errros
  4. Run any test that are directly associated with the change (ctest -R ModifiedClass, ctest -R FunctionalTestsApplicationname)
  5. Modify any failed tests
  6. Run all of the tests (ctest)
  7. Modify any failed tests

Change Log and Attributions

Now you need to let the ISIS community know your changes are going into the system and add your name to the list of people who have contributed to ISIS over it's lifetime.

Edit the CHANGELOG.md file, located at the root of your local repository, and add an entry describing your changes. Read the instructions inside the file carefully.

Edit the .zenodo.json file, also located at the root or you local repository, and add your information.

Submit your new application for review

Now that you have your changes working perfectly. It's time to get them reviewed by other ISIS developers, so they can be added to ISIS and be distributed with the next appropriate public release.

  1. Tell git to track any changed or new files (git add new_files)
  2. Commit them to your local repository (git commit -m brief description)
  3. Push all of the changes to your GitHub fork (git push origin)
  4. Create a pull request on GitHub
  5. Iterate with the reviewers to fix any issues, resolve any conflicts and explain any questions
  6. Update your pull request with any changes

Once your reviewers are satisfied, one of them will merge your modified code with the ISIS dev branch. When the next appropriate public release is created, your changes will be available alongside.

Document History

Stuart Sides2022-03-19Original document