From 895398d91ea82b7fa1f97e406960ee5f9414cbfa Mon Sep 17 00:00:00 2001 From: Stuart Sides Date: Sun, 20 Mar 2022 08:30:20 -0700 Subject: [PATCH] New developer doc for adding new feature (#4859) * New developer doc for adding new feature * Address comments * Address a couple comments --- .../DeveloperAddFeature.xml | 218 ++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 isis/src/docsys/documents/DeveloperAddFeature/DeveloperAddFeature.xml diff --git a/isis/src/docsys/documents/DeveloperAddFeature/DeveloperAddFeature.xml b/isis/src/docsys/documents/DeveloperAddFeature/DeveloperAddFeature.xml new file mode 100644 index 0000000000..3e57675cfe --- /dev/null +++ b/isis/src/docsys/documents/DeveloperAddFeature/DeveloperAddFeature.xml @@ -0,0 +1,218 @@ + + + + + +

Introduction

+

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

+ +

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

+ +

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. +
  2. Fork the ISIS repository
    3. +
  3. Clone your fork to a local repository
    4. +
+ +

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: +

+
    +
  • Compiler (Mac OS Xcode, Linux GNU C++)
    • +
  • Editor (Vim, Nano, Atom, ...
    • +
+ +

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

+ +

Starting a conversation with other ISIS developers

+

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

+ +

Writing your new application

+ +

Creating the files for your new application

+

+ 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 +

+ +
    +
  1. Decide where your new application belongs
    2. +
  2. Create a directory using the same name as you new application
    3. +
  3. Create a "main.cpp" file
    4. +
  4. Create a "yournewapp.cpp" file
    5. +
  5. Create a "yournew_app.h" file
    6. +
  6. Create a "yournewapp.xml" file
    7. +
  7. Create any additional support files (e.g., Supportclass.cpp, Supportclass.h
    8. +
+

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

+ +

Compile and link your new application for the first time

+

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

+
    +
  1. Change your current working directory to the ISIS build directory (cd $ISISROOT)
    2. +
  2. Remove the CMakeCache.txt file (rm CMakeCache.txt)
    3. +
  3. Re-run the cmake command (cmake -GNinja ..)
    4. +
  4. Build the ISIS library and all of the applications (ninja)
    5. +
+ +

Fix, run, hand test, debug the new application

+

+ Iterate over the following steps until you have your new feature producing the desired result +

+
    +
  1. Fix any compile or linking errors
    2. +
  2. Rebuild the ISIS library and your new application (ninja)
    3. +
  3. Run your application and test the user interface
    4. +
  4. Run your application and test the output
    5. +
      +
    1. Cube DN's - Are they what you expect?
      2. +
    2. Cube labels - Have they been modified as you intend?
      3. +
    3. History - Did the application add a cube history entry for every output cube?
      4. +
    4. Original label - If your application is an import program, did it store the original label in the output cube
      5. +
    5. print.prt file - Did your application write a log entry to the print.prt file?
      6. +
    6. Cleanup temporary files - If your application used any temporary files, did it remove them before it exited?
      7. +
    +
+ +

Testing for your new 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. +

+ +

Change Log and Attributions

+

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

+ + +

Submit your new application for review

+

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

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

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

+ + + + HTML + + + DeveloperAddFeature.html + + + + + + guide + + + + developer + + + + Developer + 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. + + Stuart Sides + 2022-03-15 + + + + Original document + +