Modifying the ISIS software
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.
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.
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.
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.
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.
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.
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.
Iterate over the steps below to make your change and thoroughly test the results
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.
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.
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.
|Stuart Sides||2022-03-19||Original document|