diff --git a/isis/src/docsys/documents/DeveloperModifyIsis/DeveloperModifyIsis.xml b/isis/src/docsys/documents/DeveloperModifyIsis/DeveloperModifyIsis.xml new file mode 100644 index 0000000000..07e3d6eaee --- /dev/null +++ b/isis/src/docsys/documents/DeveloperModifyIsis/DeveloperModifyIsis.xml @@ -0,0 +1,207 @@ + + + + + +

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. +
  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 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. +
  2. Compile your changes and re-link the applications (ninja)
    3. +
  3. Fix any compile or linking errros
    4. +
  4. Run any test that are directly associated with the change (ctest -R ModifiedClass, ctest -R FunctionalTestsApplicationname)
    5. +
  5. Modify any failed tests
    6. +
  6. Run all of the tests (ctest)
    7. +
  7. Modify any failed tests
    8. +
+ + +

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. +
  2. Commit them to your local repository (git commit -m brief description)
    3. +
  3. Push all of the changes 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 any 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 modified code with the ISIS dev branch. When + the next appropriate public release is created, your changes will be available alongside. +

+ + + + HTML + + + DeveloperModifyIsis.html + + + + + + guide + + + + developer + + + + Developer + Modifying the ISIS software + + This is a step-by-step guide describing the process for modifying the ISIS software. + + Stuart Sides + 2022-03-19 + + + + Original document + +