Adding a new feature to the ISIS software
This is a step-by-step guide describing the process for adding a new feature to ISIS. Since ISIS is made up of many application programs, when we say new feature we mean adding a new program to ISIS. Each program in ISIS is focussed on a narrow subject, for example, isis2std is focussed on exporting ISIS cubes to standard image formats such as jpeg, tif, or png.
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 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 starting to write your first application.
There are over 400 ISIS applications. We suggest you get familiar with as many of these as possible, so you don't duplicate a feature that has already been implemented, and to use an existing application as a template for your new feature.
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 sure you have everything setup and ready to go.
Before you start writing your new feature, create an issue for it on the ISIS GitHub site. Doing this will allow other ISIS developers to way in on your preposed feature. 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 an "enhancement", to give others an idea what kind of issue it is.
The ISIS source code is organized by having a dedicated directory where all of the source code for an application is stored. The files in this directory will be exclusively to your feature. This is where using another application as a template can be very useful.
The source code inside an ISIS application directory should be organized to be a callable ISIS application. This is a change from the older style applications that could not be called directly by other applications. Details about writing callable ISIS applications can be found at: Refactoring ISIS Applications
Populate the new files with the code necessary to implement your feature.
You may also want to create a test file for your new application, and one for each supporting class you write.
Since you are adding a new application to ISIS you will need to reconfigure your build with cmake. This will add the new application to the list of applications the build system knows about.
Iterate over the following steps until you have your new feature producing the desired result
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.
Now you need to let the ISIS community know about your new application 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 new application. 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 all the pieces for your new application and it works perfectly. It's time to get it reviewed by other ISIS developers, so it can be added to ISIS and be distributed with the next public feature release.
Once your reviewers are satisfied one of them will merge your new application code with the ISIS dev branch. When the next public feature release is created, your new application will be available alongside the other ISIS applications.
|Stuart Sides||2022-03-15||Original document|