Commit 6a353d05 authored by Stuart Sides's avatar Stuart Sides Committed by Jesse Mapel
Browse files

New developer doc for adding new feature (#4859) 

* New developer doc for adding new feature

* Address comments

* Address a couple comments
parent 3e495dcd

isis/src/docsys/documents/DeveloperAddFeature/DeveloperAddFeature.xml

0 → 100644
+218 −0
Original line number Diff line number Diff line 
<?xml version="1.0" encoding="UTF-8"?>

<documentation xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://isis.astrogeology.usgs.gov/Schemas/Documentation/documentation.xsd">

  <files>

    <file>

      <body>

        <h2><a name="Introduction">Introduction</a></h2>

          <p>

            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.

          </p>

          <p>

            Many people have contributed code, documentation, answers, and suggestions to the ISIS software. As part of

            that community you should be familiar with the <a href="https://github.com/USGS-Astrogeology/ISIS3/blob/dev/CONTRIBUTING.md">contributing guide</a>.

          </p>

          <p>

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

          </p>



        <h2><a name="Resources">Resources</a></h2>

          <p>

            The <a href="../Object/Developer/index.html">ISIS library</a> 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.

          </p>

          <p>

            There are over 400 <a href="../Application/index.html">ISIS applications</a>.

            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.

          </p>

          <p>

            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. 

          </p>



        <h2><a name="Getting the ISIS source code">Getting the ISIS source code</a></h2>

          <p>

            All of the ISIS source code is available on <a href="https://github.com/USGS-Astrogeology/ISIS3">GitHub</a>.

            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 <a href="https://docs.github.com/en/get-started">getting started</a>

            pages before you start writing code.

          </p>



          <h3>Steps to get ISIS source code on your local machine</h3>

            <ol>

              <li>Setup a GitHub account</li>

              <li>Fork the ISIS repository</li>

              <li>Clone your fork to a local repository</li>

            </ol>



          <h2><a name="Setting up an environment to compile and link ISIS">Setting up an environment to compile and link ISIS</a></h2>

            <p>

              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 

              <a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake"> building ISIS</a>.

            </p>

            <p>

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

            </p>

            <ul>

              <li> Compiler (Mac OS Xcode, Linux GNU C++)</li>

              <li> Editor (Vim, Nano, Atom, ...</li>

            </ul>



            <p>

              Once you have a complete environment set up for ISIS development, we suggest you 

              <a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Developing-ISIS3-with-cmake#building-isis3">compile and build</a> 

              all of ISIS. This step will make sure sure you have everything setup and ready to go.

            </p>



          <h2><a name="Starting a conversation with other ISIS developers">Starting a conversation with other ISIS developers</a></h2>

            <p>

              Before you start writing your new feature, create an <a href="https://github.com/USGS-Astrogeology/ISIS3">issue</a> 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.

            </p>



          <h2><a name="Writing your new application">Writing your new application</a></h2>



            <h3>Creating the files for your new application</h3>

            <p>

              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.

            </p>

            <p>

              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: 

              <a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Writing-ISIS3-Tests-Using-Gtest-and-Ctest#refactoring-isis3-applications">Refactoring ISIS Applications</a>

            </p>



            <ol>

                <li>Decide where your new application belongs</li>

                <li>Create a directory using the same name as you new application</li>

                <li>Create a "main.cpp" file</li>

                <li>Create a "yournewapp.cpp" file</li>

                <li>Create a "yournew_app.h" file</li>

                <li>Create a "yournewapp.xml" file</li>

                <li>Create any additional support files (e.g., Supportclass.cpp, Supportclass.h</li>

            </ol>

            <p>

              Populate the new files with the code necessary to implement your feature.

            </p>

            <p>

              You may also want to create a test file for your new application, and one for each supporting class you write.

            </p>



            <h3>Compile and link your new application for the first time</h3>

            <p>

              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.

            </p>

            <ol>

              <li>Change your current working directory to the ISIS build directory (cd $ISISROOT)</li>

              <li>Remove the CMakeCache.txt file (rm CMakeCache.txt)</li>

              <li>Re-run the cmake command (cmake -GNinja ..)</li>

              <li>Build the ISIS library and all of the applications (ninja)</li>

            </ol>



            <h3>Fix, run, hand test, debug the new application</h3>

            <p>

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

            </p>

            <ol>

              <li>Fix any compile or linking errors</li>

              <li>Rebuild the ISIS library and your new application (ninja)</li>

              <li>Run your application and test the user interface</li>

              <li>Run your application and test the output</li>

                <ol>

                  <li>Cube DN's - Are they what you expect?</li>

                  <li>Cube labels - Have they been modified as you intend?</li>

                  <li>History - Did the application add a cube history entry for every output cube?</li>

                  <li>Original label - If your application is an import program, did it store the original label in the output cube</li>

                  <li>print.prt file - Did your application write a log entry to the print.prt file?</li>

                  <li>Cleanup temporary files - If your application used any temporary files, did it remove them before it exited?</li>

                </ol>

            </ol>



          <h2><a name="Testing for your new application">Testing for your new application</a></h2>

          <p>

            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 <a href="https://google.github.io/googletest">googletest</a> (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

            <a href="https://github.com/USGS-Astrogeology/ISIS3/wiki/Writing-ISIS3-Tests-Using-Gtest-and-Ctest">guide for writing</a> tests for detailed instructions.

          </p>



          <h2><a name="ISIS change log and attributions">Change Log and Attributions</a></h2>

          <p>

            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.

          </p>

          <p>

            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.

          </p>

          <p>

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

          </p>





          <h2><a name="Submit your new application for review">Submit your new application for review</a></h2>

          <p>

            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.

          </p>

          <ol>

            <li>Tell git to track your new files (git add new_files)</li>

            <li>Commit them to your local repository (git commit -m "brief description")</li>

            <li>Push the new application to your GitHub fork (git push origin)</li>

            <li>Create a pull request on <a href="https://github.com/USGS-Astrogeology/ISIS3/compare">GitHub</a></li>

            <li>Iterate with the reviewers to fix any issues, resolve and conflicts and explain any questions</li>

            <li>Update your pull request with any changes</li>

          </ol>

          <p>

            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. 

          </p>



      </body>



      <type>HTML</type>



      <source>

        <filename>DeveloperAddFeature.html</filename>

      </source>

    </file>

  </files>



  <category>

    <categoryItem>guide</categoryItem>

  </category>



  <audience>

    <target>developer</target>

  </audience>



  <bibliography>

    <title>Developer </title>

    <brief>Adding a new feature to the ISIS software</brief>

    <description>

      This is a step-by-step guide describing the process for adding a new feature to ISIS.

    </description>

    <author>Stuart Sides</author>

    <date>2022-03-15</date>

  </bibliography>



  <history>

    <change date="2022-03-15" name="Stuart Sides">Original document</change>

  </history>

</documentation>