diff --git a/docs/how-to-guides/environment-setup-and-maintenance/adding-usgscsm-plugin-to-isis.md b/docs/how-to-guides/environment-setup-and-maintenance/adding-usgscsm-plugin-to-isis.md index 0dde1e4f..1a4f519a 100644 --- a/docs/how-to-guides/environment-setup-and-maintenance/adding-usgscsm-plugin-to-isis.md +++ b/docs/how-to-guides/environment-setup-and-maintenance/adding-usgscsm-plugin-to-isis.md @@ -1,7 +1,7 @@ -# Adding USGSCSM Plugin to ISIS +# Adding the USGSCSM Plugin to ISIS ≤ 8.1 -???+ warning - Upcoming ISIS version 8.2 and future releases will include the USGSCSM library and does __not__ require a separate installation of the plugin. +!!! warning "Only needed for ISIS 8.1 and earlier" + ISIS versions 8.2 and later include the USGSCSM library and do __not__ require a separate installation of the plugin. ISIS versions 8.0LTS, 8.1, and earlier _require_ a separate installation of the USGSCSM plugin as shown below. @@ -14,8 +14,8 @@ conda install conda-forge::usgscsm ## For developers -???+ info - For USGSCSM versions 2.0 and above, the plugin is installed in `$CONDA_PREFIX/lib/csmplugins/` in an Anaconda environment. +???+ info "Plugin Install Location" + For USGSCSM versions 2.0 and above, the plugin is installed in `$CONDA_PREFIX/lib/csmplugins/` in a conda environment. ### Plugin setup If you are testing a new plugin or using older versions of USGSCSM/ISIS, you will need to update your `IsisPreferences` file located under the `ISIS3/isis` directory with the appropriate plugin path change. diff --git a/docs/how-to-guides/environment-setup-and-maintenance/anaconda-in-a-network-environment.md b/docs/how-to-guides/environment-setup-and-maintenance/anaconda-in-a-network-environment.md index e85e6b68..c5599f4e 100644 --- a/docs/how-to-guides/environment-setup-and-maintenance/anaconda-in-a-network-environment.md +++ b/docs/how-to-guides/environment-setup-and-maintenance/anaconda-in-a-network-environment.md @@ -1,5 +1,9 @@ # Creating a shared Anaconda installation +!!! info "Internal Procedures" + + This document is intended primarily for internal use at the USGS Astrogeology Science center. It details setup that is specific to our internal network. It is likely not very useful for those who don't either work for the USGS ASC or have access to our network. + ## Introduction Here at the USGS Astrogeology Science Center (ASC) we have a software development team consisting of roughly a dozen full or part time developers, another dozen or so technical users, and a few dozen scientists who all need consistent access to software builds and releases. As we moved to using Anaconda for dependency management and software installation, our IT group quickly flagged an issue where users' Home directories were growing astronomically large from each having their own Anaconda installation. Along with that, we had many users who had never used Anaconda before having to manage and debug their own installations. Fairly quickly, we settled upon having shared Anaconda installations that users could access and use across systems without having to manage their own Anaconda installation or update their environments. diff --git a/docs/how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md b/docs/how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md index 08af1ec0..02b8264b 100644 --- a/docs/how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md +++ b/docs/how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md @@ -1,5 +1,12 @@ # Installing ISIS +
+ +- [:octicons-arrow-left-24: __Introduction__ to ISIS](../../getting-started/using-isis-first-steps/introduction-to-isis.md) +- [:octicons-arrow-right-24: Setting up the __ISIS Data Area__](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md) + +
+ ## Prerequisites ??? "Conda" diff --git a/docs/how-to-guides/environment-setup-and-maintenance/isis-data-area.md b/docs/how-to-guides/environment-setup-and-maintenance/isis-data-area.md index 1869b96f..17c55ee3 100644 --- a/docs/how-to-guides/environment-setup-and-maintenance/isis-data-area.md +++ b/docs/how-to-guides/environment-setup-and-maintenance/isis-data-area.md @@ -1,5 +1,12 @@ # Setting Up the ISIS Data Area +
+ +- [:octicons-arrow-left-24: __Installing__ ISIS](../../how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md) +- [:octicons-arrow-right-24: SPICE Kernel __Updates__](../../how-to-guides/environment-setup-and-maintenance/spice-kernel-updates-in-isis.md) + +
+ Many ISIS apps need extra data to carry out their functions. This data varies depending on the mission, and may be **quite large**, so it is **not included** with the ISIS binaries. It resides in the **ISIS Data Area**. ??? info "More Info on the ISIS Data Area" diff --git a/docs/how-to-guides/environment-setup-and-maintenance/spice-kernel-updates-in-isis.md b/docs/how-to-guides/environment-setup-and-maintenance/spice-kernel-updates-in-isis.md index a2df1602..312a8768 100644 --- a/docs/how-to-guides/environment-setup-and-maintenance/spice-kernel-updates-in-isis.md +++ b/docs/how-to-guides/environment-setup-and-maintenance/spice-kernel-updates-in-isis.md @@ -1,3 +1,12 @@ +# SPICE Kernel Updates in ISIS + +
+ +- [:octicons-arrow-left-24: Setting up the __ISIS Data Area__](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md) +- [:octicons-arrow-right-24: Using ISIS in __other conda envs__](../../how-to-guides/environment-setup-and-maintenance/using-isis-in-other-conda-envs.md) + +
+ SPICE kernels are required for the use of most ISIS applications. ISIS provides SPICE kernels for each mission in the [ISIS Data Area](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md). diff --git a/docs/how-to-guides/environment-setup-and-maintenance/using-isis-in-other-conda-envs.md b/docs/how-to-guides/environment-setup-and-maintenance/using-isis-in-other-conda-envs.md index ce57f2ff..b9589405 100644 --- a/docs/how-to-guides/environment-setup-and-maintenance/using-isis-in-other-conda-envs.md +++ b/docs/how-to-guides/environment-setup-and-maintenance/using-isis-in-other-conda-envs.md @@ -1,5 +1,11 @@ # Using ISIS in other Conda Environments +
+ +- [:octicons-arrow-left-24: Setting up the __ISIS Data Area__](../../how-to-guides/environment-setup-and-maintenance/isis-data-area.md) + +
+ The ISIS conda package pins some of its requirements, which may clash with other packages. diff --git a/docs/how-to-guides/index.md b/docs/how-to-guides/index.md index a378c3cb..3ba66eb6 100644 --- a/docs/how-to-guides/index.md +++ b/docs/how-to-guides/index.md @@ -1,23 +1,54 @@ # How-To Guides -How-to guides are much like recipes in a recipe book. Write how-to docs to solve specific problems quickly, sometimes copy-pastable. Think of how-to guides as preemptive StackOverflow-like problems. +[comment]: <> (These cards are a good place to highlight specific docs with high value, or ones readers commonly want to see) +
-## For Readers -[comment]: <> (This is a good place to mention any places for someone to start looking in. Highlight specific docs with high value or we identify readers commonly want to see) +- :octicons-download-24:{ .lg .middle } __Ready to use ISIS?__ -Use the table of contents on the left to start browsing guides. + --- -## For Authors + Install ISIS with `conda` and download data for your mission. -Before you start writing a new How-To guide. Make sure what you are writing belongs here. These are similar to getting-started guides, in that they explain to users how to perform some valuable tasks with the software, but distinct in that they: + [:octicons-arrow-right-24: Install ISIS](../how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md) -1. Solve practical problems for more experienced users -1. Offer more ambiguous starting points; they should be reusable in many different contexts -1. Can be much shorter than getting-started docs. +- :octicons-code-square-24:{ .lg .middle } __ISIS Development Guides__ -??? Info Examples - * How-to: generate an ISD via loads with specific kernels - * How-to: get GEOJSON from ISIS footprints - * Cookbook of common operations in a library + --- + + Learn how to build, write code for, and contribute to ISIS. + + [:octicons-arrow-right-24: Develop in ISIS](../how-to-guides/isis-developer-guides/developing-isis3-with-cmake.md) + +- :octicons-comment-discussion-24:{ .lg .middle } __I have an Issue!__ + + --- + + Learn about how to report issues with ISIS and how the maintainers respond to issues. + + [:octicons-arrow-right-24: Report an Issue](../how-to-guides/software-management/guidelines-for-reporting-issues.md) + +
+ +----- + +How-to guides are much like recipes in a recipe book. They show how to carry out a specific task quickly, and can be copy-pastable. Think of how-to guides as preemptive StackOverflow-like answers. + +Use the table of contents on the left to start browsing guides. Check out the above cards if you aren't sure where to start. Use the search bar if you're looking for something specific. + +----- + +??? quote "Want to write a how-to guide?" + + When contributing documentation, consider what category it should should go in. Docs in the **how-to guides** category should: + + 1. Solve practical problems for more experienced users + 1. Offer more ambiguous starting points; they should be reusable in many different contexts + 1. Can be much shorter than getting-started docs + 1. Some examples: + - How-to: generate an ISD via loads with specific kernels + - How-to: get GEOJSON from ISIS footprints + - Cookbook of common operations in a library + + On the other hand, docs in the **getting started** category detail specific tasks for users who may not have much experience; docs in the **concepts** category provide an understanding of a topic without necessarily going into detail on how to carry out specific tasks. diff --git a/docs/how-to-guides/isis-developer-guides/app-testing-cookbook.md b/docs/how-to-guides/isis-developer-guides/app-testing-cookbook.md index f33e2f55..f02a91c6 100644 --- a/docs/how-to-guides/isis-developer-guides/app-testing-cookbook.md +++ b/docs/how-to-guides/isis-developer-guides/app-testing-cookbook.md @@ -1,6 +1,11 @@ +# ISIS App Testing Templates -# ISIS App Testing Cookbook +
+- [:octicons-arrow-left-24: Writing Tests with __CTest and GTest__](../../how-to-guides/isis-developer-guides/writing-isis-tests-with-ctest-and-gtest.md) +- [:octicons-arrow-right-24: __Doxygen Tags__ (class requirement)](../../how-to-guides/isis-developer-guides/class-requirements-for-using-doxygen-tags.md) + +
### Main.cpp Templates diff --git a/docs/how-to-guides/isis-developer-guides/building-and-contributing-to-isis-tutorial.md b/docs/how-to-guides/isis-developer-guides/building-and-contributing-to-isis-tutorial.md index 7b38ab00..ecad3b7c 100644 --- a/docs/how-to-guides/isis-developer-guides/building-and-contributing-to-isis-tutorial.md +++ b/docs/how-to-guides/isis-developer-guides/building-and-contributing-to-isis-tutorial.md @@ -1,4 +1,11 @@ -# Building and Contributing to ISIS Tutorial +# Contributing to ISIS - Tutorial + +
+ +- [:octicons-arrow-left-24: __Contributing to ISIS__: Overview](../../how-to-guides/isis-developer-guides/contributing-to-isis.md) +- [:octicons-arrow-right-24: Writing Tests with __CTest and GTest__](../../how-to-guides/isis-developer-guides/writing-isis-tests-with-ctest-and-gtest.md) + +
## 1. Set Up Your Local ISIS Environment diff --git a/docs/how-to-guides/isis-developer-guides/class-requirements-for-using-doxygen-tags.md b/docs/how-to-guides/isis-developer-guides/class-requirements-for-using-doxygen-tags.md index 16aaeffb..0dc7c290 100644 --- a/docs/how-to-guides/isis-developer-guides/class-requirements-for-using-doxygen-tags.md +++ b/docs/how-to-guides/isis-developer-guides/class-requirements-for-using-doxygen-tags.md @@ -1,4 +1,13 @@ -A new ISIS3 class needs to have the following Doxygen tags filled out just above the class declaration, as in this example below: +# Doxygen Tags + +
+ +- [:octicons-arrow-left-24: __Templates__ for app testing](../../how-to-guides/isis-developer-guides/app-testing-cookbook.md) +- [:octicons-arrow-right-24: ISIS Programming Exercise: `mirror`](../../how-to-guides/isis-developer-guides/exercise-1.md) + +
+ +A new ISIS class needs to have the following Doxygen tags filled out just above the class declaration, as in this example below: ```C++ /** diff --git a/docs/how-to-guides/isis-developer-guides/contributing-to-isis.md b/docs/how-to-guides/isis-developer-guides/contributing-to-isis.md index 322e13c0..2ba67d94 100644 --- a/docs/how-to-guides/isis-developer-guides/contributing-to-isis.md +++ b/docs/how-to-guides/isis-developer-guides/contributing-to-isis.md @@ -1,5 +1,11 @@ -# Contributing to ISIS -This document serves as a concise guide on how to contribute to ISIS. +# Contributing to ISIS - Overview + +
+ +- [:octicons-arrow-left-24: ISIS __Test Data__](../../how-to-guides/isis-developer-guides/obtaining-maintaining-submitting-test-data.md) +- [:octicons-arrow-right-24: __Contributing to ISIS__: Tutorial](../../how-to-guides/isis-developer-guides/building-and-contributing-to-isis-tutorial.md) + +
## Build ISIS Begin by referring to our [Developing ISIS3 with CMake](./developing-isis3-with-cmake.md) page for instructions on setting up a local clone of ISIS and configuring an Anaconda environment for building. Once you've followed the steps outlined there, you'll have a local build of ISIS ready for development. diff --git a/docs/how-to-guides/isis-developer-guides/developing-isis3-with-cmake.md b/docs/how-to-guides/isis-developer-guides/developing-isis3-with-cmake.md index 7636b1d0..afd0a7eb 100644 --- a/docs/how-to-guides/isis-developer-guides/developing-isis3-with-cmake.md +++ b/docs/how-to-guides/isis-developer-guides/developing-isis3-with-cmake.md @@ -1,3 +1,12 @@ +# Developing ISIS with cmake + +
+ +- [:octicons-arrow-left-24: __Introduction__ to ISIS](../../getting-started/using-isis-first-steps/introduction-to-isis.md) +- [:octicons-arrow-right-24: ISIS __Test Data__](../../how-to-guides/isis-developer-guides/obtaining-maintaining-submitting-test-data.md) + +
+ ## Getting Started With GitHub To get started, you want a fresh copy of ISIS to work on. You first want to create a fork of the ISIS3 repo by going to the [main ISIS3 repo page](https://github.com/DOI-USGS/ISIS3) and clicking on "Fork" at the top of the page. diff --git a/docs/how-to-guides/isis-developer-guides/exercise-1.md b/docs/how-to-guides/isis-developer-guides/exercise-1.md index 039cbaf6..74159fcf 100644 --- a/docs/how-to-guides/isis-developer-guides/exercise-1.md +++ b/docs/how-to-guides/isis-developer-guides/exercise-1.md @@ -1,6 +1,13 @@ -# Exercises 1 +# ISIS Programming Exercise 1: `mirror` -The purpose behind these exercises is to help programmers become familiar with the ISIS3 environment, the ISIS3 API, and ISIS3 standards. +
+ +- [:octicons-arrow-left-24: __Doxygen Tags__ (class requirement)](../../how-to-guides/isis-developer-guides/class-requirements-for-using-doxygen-tags.md) +- [:octicons-arrow-right-24: ISIS Programming Exercise 2: `diff`](../../how-to-guides/isis-developer-guides/exercise-2.md) + +
+ +The purpose behind these exercises is to help programmers become familiar with the ISIS environment, the ISIS API, and ISIS standards. ## Prerequisites diff --git a/docs/how-to-guides/isis-developer-guides/exercise-2.md b/docs/how-to-guides/isis-developer-guides/exercise-2.md index e609ab2b..db00dc89 100644 --- a/docs/how-to-guides/isis-developer-guides/exercise-2.md +++ b/docs/how-to-guides/isis-developer-guides/exercise-2.md @@ -1,6 +1,13 @@ -# Exercises 2 +# ISIS Programming Exercise 2: `diff` -The goal of this exercise is to familiarize the programmer with slightly more advanced features of the ISIS3 API. You will be writing an ISIS3 application that performs simple differences between adjacent pixels in the line or sample directions. +
+ +- [:octicons-arrow-left-24: ISIS Programming Exercise 1: `mirror`](../../how-to-guides/isis-developer-guides/exercise-1.md) +- [:octicons-arrow-right-24: Start soving issues on __GitHub__ :simple-github:](https://github.com/DOI-USGS/ISIS3/issues) + +
+ +The goal of this exercise is to familiarize the programmer with slightly more advanced features of the ISIS API. You will be writing an ISIS application that performs simple differences between adjacent pixels in the line or sample directions. !!! Info "This tutorial assumes that the user has completed [exercise 1](./exercise-1.md) and has access to the ISIS installation and data from that tutorial." diff --git a/docs/how-to-guides/isis-developer-guides/obtaining-maintaining-submitting-test-data.md b/docs/how-to-guides/isis-developer-guides/obtaining-maintaining-submitting-test-data.md index 9806cd5d..da5a69dd 100644 --- a/docs/how-to-guides/isis-developer-guides/obtaining-maintaining-submitting-test-data.md +++ b/docs/how-to-guides/isis-developer-guides/obtaining-maintaining-submitting-test-data.md @@ -1,5 +1,12 @@ # ISIS Test Data +
+ +- [:octicons-arrow-left-24: __Developing and Building__ ISIS](../../how-to-guides/isis-developer-guides/developing-isis3-with-cmake.md) +- [:octicons-arrow-right-24: __Contributing to ISIS__: Overview](../../how-to-guides/isis-developer-guides/contributing-to-isis.md) + +
+ ### GTests and Legacy Makefile-based Tests ISIS has of two types of tests: custom **Makefile** based tests, and **GTests**. The GTests use data from the ISIS repo along with the source, so no special data is required to run those, aside from the ISIS data area. diff --git a/docs/how-to-guides/isis-developer-guides/writing-isis-tests-with-ctest-and-gtest.md b/docs/how-to-guides/isis-developer-guides/writing-isis-tests-with-ctest-and-gtest.md index e19a1fbd..f9f9575f 100644 --- a/docs/how-to-guides/isis-developer-guides/writing-isis-tests-with-ctest-and-gtest.md +++ b/docs/how-to-guides/isis-developer-guides/writing-isis-tests-with-ctest-and-gtest.md @@ -1,4 +1,11 @@ -# How To Write ISIS Tests with CTest and GTest +# Writing ISIS Tests with CTest & GTest + +
+ +- [:octicons-arrow-left-24: __Contributing to ISIS__: Tutorial](../../how-to-guides/isis-developer-guides/building-and-contributing-to-isis-tutorial.md) +- [:octicons-arrow-right-24: __Templates__ for app testing](../../how-to-guides/isis-developer-guides/app-testing-cookbook.md) + +
??? Tip "Helpful External documentation" @@ -22,7 +29,7 @@ - [ ] New tests passing on Jenkins - [ ] Old test data removed -## Refactoring ISIS3 Applications +## Refactoring ISIS Applications In order to better integrate with the gtest unit test framework, all of our application logic needs to be callable programmatically. diff --git a/docs/how-to-guides/software-management/deprecation.md b/docs/how-to-guides/software-management/deprecation.md index d39b7774..ecb5b755 100644 --- a/docs/how-to-guides/software-management/deprecation.md +++ b/docs/how-to-guides/software-management/deprecation.md @@ -1,4 +1,12 @@ # Deprecation + +
+ +- [:octicons-arrow-left-24: __Contribute Fixes__ with Pull Requests](../../how-to-guides/software-management/guidelines-for-pull-requests.md) +- [:octicons-arrow-right-24: Astro __Software Support Process__](../../how-to-guides/software-management/software-support.md) + +
+ This document is intended to provide guidelines for the deprecation process. ## 1. Deprecation Proposal diff --git a/docs/how-to-guides/software-management/guidelines-for-pull-requests.md b/docs/how-to-guides/software-management/guidelines-for-pull-requests.md index 0394e9db..22dd48b6 100644 --- a/docs/how-to-guides/software-management/guidelines-for-pull-requests.md +++ b/docs/how-to-guides/software-management/guidelines-for-pull-requests.md @@ -1,5 +1,12 @@ # Guidelines for Pull Requests +
+ +- [:octicons-arrow-left-24: __Report an Issue__ on GitHub](../../how-to-guides/software-management/guidelines-for-reporting-issues.md) +- [:octicons-arrow-right-24: Astro __Software Support Process__](../../how-to-guides/software-management/software-support.md) + +
+ This page provides guidelines for creating a successful pull request. These guidelines are intended to promote a style of pull request that benefits both the creator of the pull request and the reviewer. ## PR Creators @@ -19,6 +26,11 @@ This page provides guidelines for creating a successful pull request. These gui - Ensure that your changes are accompanied by an entry in the changelog - Write tests to cover any functionality that is added or changed +----- +[:octicons-arrow-right-24: See Also: __Deprecation__](../../how-to-guides/software-management/deprecation.md) + +----- + ### When Creating the Pull Request @@ -40,24 +52,24 @@ Use the following checklist to ensure that your PR follows best practices that w This section describes best practices for the reviewers of incoming PRs. -### Code Review Checklist -The purpose of this checklist is to prompt discussion between the reviewer and submitter. Any questions or concerns that come from this checklist should be discussed during the code review. - - -* Does the code work? Does it perform its intended function, the logic is correct etc? -* Do the changes make sense (in terms of the big picture/ticket/etc.)? -* Did they complete their developer checklist? Double check their checklist? -* Does the code include tests? -* Does the code meet non-functional requirements (scalability, robustness, extensibility, modularity)? -* Does the code introduce new dependencies? If so, are they necessary? -* Is this code in the right place? (are the correct classes/apps handling these things, are they at the right level, does the order make sense) -* Is there unnecessary duplication in the code or duplication of any code in the repository? -* Does all this code need to exist? (e.g. extraneous mutators etc.) -* Are they adding [tech debt](https://www.agileweboperations.com/technical-debt)? -* Is the code easily understandable (i.e. [squint test](https://robertheaton.com/2014/06/20/code-review-without-your-eyes/))? -* Does the code handle potential exceptions, return values, invalid inputs...? -* Is the code needlessly complex? -* Is there low-hanging fruit that is easily refactorable? -* Do new classes/functions have well-defined, documented responsibilities? Are these responsibilities too broad? -* Are the API documentation and comments useful? Are comments explaining why? -* Are all style choices and changes appropriate? \ No newline at end of file +???+ abstract "Code Review Checklist" + + The purpose of this checklist is to prompt discussion between the reviewer and submitter. Any questions or concerns that come from this checklist should be discussed during the code review. + + - [ ] Does the code work? Does it perform its intended function, the logic is correct etc? + - [ ] Do the changes make sense (in terms of the big picture/ticket/etc.)? + - [ ] Did they complete their developer checklist? Double check their checklist? + - [ ] Does the code include tests? + - [ ] Does the code meet non-functional requirements (scalability, robustness, extensibility, modularity)? + - [ ] Does the code introduce new dependencies? If so, are they necessary? + - [ ] Is this code in the right place? (are the correct classes/apps handling these things, are they at the right level, does the order make sense) + - [ ] Is there unnecessary duplication in the code or duplication of any code in the repository? + - [ ] Does all this code need to exist? (e.g. extraneous mutators etc.) + - [ ] Are they adding [tech debt](https://www.agileweboperations.com/technical-debt)? + - [ ] Is the code easily understandable (i.e. [squint test](https://robertheaton.com/2014/06/20/code-review-without-your-eyes/))? + - [ ] Does the code handle potential exceptions, return values, invalid inputs...? + - [ ] Is the code needlessly complex? + - [ ] Is there low-hanging fruit that is easily refactorable? + - [ ] Do new classes/functions have well-defined, documented responsibilities? Are these responsibilities too broad? + - [ ] Are the API documentation and comments useful? Are comments explaining why? + - [ ] Are all style choices and changes appropriate? \ No newline at end of file diff --git a/docs/how-to-guides/software-management/guidelines-for-reporting-issues.md b/docs/how-to-guides/software-management/guidelines-for-reporting-issues.md index 8f8362a7..4ae1fef3 100644 --- a/docs/how-to-guides/software-management/guidelines-for-reporting-issues.md +++ b/docs/how-to-guides/software-management/guidelines-for-reporting-issues.md @@ -1,54 +1,75 @@ -# Guidelines +# Guidelines on Issues + +
+ +- [:octicons-arrow-right-24: Astro __Software Support Process__](../../how-to-guides/software-management/software-support.md) +- [:octicons-arrow-right-24: __Contribute Fixes__ with Pull Requests](../../how-to-guides/software-management/guidelines-for-pull-requests.md) + +
## Before you Report an Issue: - - Make sure you are running the most recent version of ISIS3. - - Search for existing issues similar issues to yours. If you find a + - **Is your ISIS up to date?** + Make sure you are running the most recent version of ISIS. + - **Has your issue already been reported?** + Search for existing issues similar issues to yours. If you find a pre-existing open issue, you may add a note with your new information or just indicate you are also experiencing this issue. If you find a pre-existing closed issue, please start a new issue and relate it to the old one. - - Use this issue tracking system to communicate with the ISIS Support + - **Use GitHub!** + Use GitHub's issue tracking system to communicate with the ISIS Support Team. If we receive direct emails we may ask you to post a new issue. +----- +???+ info "GitHub Issues Pages for some of Astro's Projects" + + [ISIS Issues](https://github.com/DOI-USGS/ISIS3/issues){ .md-button } + [ALE Issues](https://github.com/DOI-USGS/ale/issues){ .md-button } + [USGSCSM Issues](https://github.com/DOI-USGS/usgscsm/issues){ .md-button } + ## Step-by-step Issue Reporting: -1. Tell us if this is a Bug, a Feature Request, a Question, a +1. **Classify your Issue.** + Tell us if this is a Bug, a Feature Request, a Question, a Recommendation, a problem with Documentation, or a Crash that is stopping your work. -2. Provide a clear but concise subject for your new issue. Consider +1. **Title your Issue.** + Provide a clear but concise subject for your new issue. Consider including the program name (e.g., "destripe is missing reset icon in the toolbar"). -3. When describing your issue, provide a clear description of the +1. **Describe your Issue.** + When describing your issue, provide a clear description of the issue. We need as much information as possible to help us identify and fix the problem. Too much information is better than not enough. Feel free to use the markdown tools to better illustrate the issue. This is especially useful when quoting error messages or documentation. -4. Consider including these in your description: - - All the steps necessary to reproduce the problem +1. **Try to include these helpful details:** + - All steps necessary to reproduce the problem - Command line with the exact arguments you used - - Spacecraft and instrument names of the input files + - Spacecraft, instrument, and names of the input files - Is the issue consistently reproducible? - Your operating system or distribution name and version - - The exact error message. If possible, copy-paste the error + - The exact error message if you see one. If possible, copy-paste the error messages into the issue description. -5. Select the priority you feel this issues needs. -6. Select the appropriate Category. Usually you'll only want to use - Applications and Installation. Developers may need to report an API - or Infrastructure issue. -7. Include the ISIS software version you are working with. -8. Keep a close watch on your email for changes in the issue status and +1. **Version.** + Include the ISIS software version you are working with. +1. **Monitor the Issue.** + Keep a close watch on your email for changes in the issue status and for notes being added. If the support team needs additional information they will add a note to the issue with the request. ## Miscellaneous guidelines -1. If you have multiple problems, please create separate issues for +1. **Multiple Problems → Separate Issues.** + If you have multiple problems, please create separate issues for each one. -2. If a screenshot or text file is necessary to illustrate the issue, +1. **Post files when needed, but mind the file size.** + If a screenshot or text file is necessary to illustrate the issue, attach one to your post, but please keep the files as small as possible. -3. No advertising is allowed anywhere on the site. Any advertisements +1. **No Ads.** + No advertising is allowed anywhere on the site. Any advertisements will be deleted immediately. diff --git a/docs/how-to-guides/software-management/isis-release-schedule.md b/docs/how-to-guides/software-management/isis-release-schedule.md index e4fd7a9d..b7f57a7d 100644 --- a/docs/how-to-guides/software-management/isis-release-schedule.md +++ b/docs/how-to-guides/software-management/isis-release-schedule.md @@ -1,4 +1,12 @@ # ISIS Release Schedule + +
+ +- [:octicons-arrow-left-24: Astro __Software Support Process__](../../how-to-guides/software-management/software-support.md) +- [:octicons-arrow-right-24: Detailed __Release Process__](../../how-to-guides/software-management/public-release-process.md) + +
+ This document describes the cadence and schedule for ISIS releases. ## Release Cadence diff --git a/docs/how-to-guides/software-management/lts-release-process.md b/docs/how-to-guides/software-management/lts-release-process.md index cd5256fd..e4c6ba53 100644 --- a/docs/how-to-guides/software-management/lts-release-process.md +++ b/docs/how-to-guides/software-management/lts-release-process.md @@ -1,5 +1,12 @@ # LTS Release Process +
+ +- [:octicons-arrow-left-24: Detailed __Release Process__](../../how-to-guides/software-management/public-release-process.md) +- [:octicons-arrow-right-24: RFC8: ISIS __Long Term Support__](https://github.com/DOI-USGS/ISIS3/discussions/4691) + +
+ This page shows the steps on creating an LTS (Long Term Support) release and supporting older LTS versions. Quick rundown of what LTS entails: diff --git a/docs/how-to-guides/software-management/public-release-process.md b/docs/how-to-guides/software-management/public-release-process.md index 2b40d65f..c671c3fb 100644 --- a/docs/how-to-guides/software-management/public-release-process.md +++ b/docs/how-to-guides/software-management/public-release-process.md @@ -1,4 +1,12 @@ # Public Software Release Process Step-By-Step Instructions + +
+ +- [:octicons-arrow-left-24: ISIS __Release Schedule__](../../how-to-guides/software-management/isis-release-schedule.md) +- [:octicons-arrow-right-24: __LTS__ Release Process](../../how-to-guides/software-management/lts-release-process.md) + +
+ ------- #### Software Table of Contents diff --git a/docs/how-to-guides/software-management/software-support.md b/docs/how-to-guides/software-management/software-support.md index 6f523cb9..7c59c0ad 100644 --- a/docs/how-to-guides/software-management/software-support.md +++ b/docs/how-to-guides/software-management/software-support.md @@ -1,12 +1,19 @@ # Software Support +
+ +- [:octicons-arrow-left-24: __Contribute Fixes__ with Pull Requests](../../how-to-guides/software-management/guidelines-for-pull-requests.md) +- [:octicons-arrow-right-24: ISIS __Release Schedule__](../../how-to-guides/software-management/isis-release-schedule.md) + +
+ This document provides information about the software support process. That is, how our development team goes about addressing these issues. Including scheduling, project management tools and practices, issue soliciation, issue selection, and prioritization. !!! Note "How to Submit Issues" Our code is managed [via GitHub](https://github.com/DOI-USGS) - Any issues with our software portfolio should be tracked in our repos through [GitHub issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues). Links for some our more active repos: + Any issues with our software portfolio should be tracked in our repos through [GitHub issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues). See [Guidelines for Reporting Issues](../../how-to-guides/software-management/guidelines-for-reporting-issues.md). Here are links to the issue pages for some of our more active repos: * [ISIS](https://github.com/DOI-USGS/ISIS3/issues) * [ALE](https://github.com/DOI-USGS/ale/issues) diff --git a/mkdocs.yml b/mkdocs.yml index 250c3b22..e6fea0a6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -54,13 +54,13 @@ nav: - Demos and Workshops: getting-started/archive/isis-demos-and-workshops.md - How-To Guides: - Home: how-to-guides/index.md - - Environment Setup and Maintenance: - - Installing ISIS: how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md - - Setting up the ISIS Data Area: how-to-guides/environment-setup-and-maintenance/isis-data-area.md - - Using ISIS in other Conda Envs: how-to-guides/environment-setup-and-maintenance/using-isis-in-other-conda-envs.md - - Anaconda in a Network Environment: how-to-guides/environment-setup-and-maintenance/anaconda-in-a-network-environment.md - - SPICE Kernel Updates in ISIS: how-to-guides/environment-setup-and-maintenance/spice-kernel-updates-in-isis.md - - Adding USGSCSM Plugin to ISIS: how-to-guides/environment-setup-and-maintenance/adding-usgscsm-plugin-to-isis.md + - ISIS Environment Setup and Maintenance: + - 1. Installing ISIS: how-to-guides/environment-setup-and-maintenance/installing-isis-via-anaconda.md + - 2. Setting up the ISIS Data Area: how-to-guides/environment-setup-and-maintenance/isis-data-area.md + - 2a. SPICE Kernel Updates in ISIS: how-to-guides/environment-setup-and-maintenance/spice-kernel-updates-in-isis.md + - 3. Using ISIS in other Conda Envs: how-to-guides/environment-setup-and-maintenance/using-isis-in-other-conda-envs.md + - (ISIS ≤ 8.1 Only) The USGSCSM Plugin: how-to-guides/environment-setup-and-maintenance/adding-usgscsm-plugin-to-isis.md + - (Internal) USGS Networked Conda Envs: how-to-guides/environment-setup-and-maintenance/anaconda-in-a-network-environment.md - SPICE: - Creating Spice Config Files in SpiceQL: how-to-guides/SPICE/creating-spice-config-files-in-spiceql.md - Image Processing: @@ -71,25 +71,27 @@ nav: - ISIS Demos: - Interactive Online Demos: how-to-guides/demos/isis-demos.md - Software Management: - - LTS Release Process: how-to-guides/software-management/lts-release-process.md - - Deprecation: how-to-guides/software-management/deprecation.md - - Public Release Process: how-to-guides/software-management/public-release-process.md - - Software Support: how-to-guides/software-management/software-support.md - - Guidelines for Reporting Issues: how-to-guides/software-management/guidelines-for-reporting-issues.md - - Guidelines for Pull Requests: how-to-guides/software-management/guidelines-for-pull-requests.md - - ISIS Release Schedule: how-to-guides/software-management/isis-release-schedule.md + - 1. Guidelines for Reporting Issues: how-to-guides/software-management/guidelines-for-reporting-issues.md + - 2. Guidelines for Pull Requests: how-to-guides/software-management/guidelines-for-pull-requests.md + - 2a. Deprecation: how-to-guides/software-management/deprecation.md + - 3. Software Support: how-to-guides/software-management/software-support.md + - 4. ISIS Release Schedule: how-to-guides/software-management/isis-release-schedule.md + - 5. USGS ASC Release Processes (Internal): + - 5a. Public Release Process Step-By-Step: how-to-guides/software-management/public-release-process.md + - 5b. LTS Release Process: how-to-guides/software-management/lts-release-process.md - ISIS Developer Guides: - - Contributing to ISIS: how-to-guides/isis-developer-guides/contributing-to-isis.md - - Writing Tests with CTest and GTest: how-to-guides/isis-developer-guides/writing-isis-tests-with-ctest-and-gtest.md - - App Testing CookBook: how-to-guides/isis-developer-guides/app-testing-cookbook.md - - Doxygen Tag Class Requirement: how-to-guides/isis-developer-guides/class-requirements-for-using-doxygen-tags.md - - Developing ISIS3 with cmake: how-to-guides/isis-developer-guides/developing-isis3-with-cmake.md - - ISIS Development on ARM Macs: how-to-guides/isis-developer-guides/developing-mac-m1-arm-systems.md - - Building and Contributing to ISIS Tutorial: how-to-guides/isis-developer-guides/building-and-contributing-to-isis-tutorial.md - - ISIS Test Data: how-to-guides/isis-developer-guides/obtaining-maintaining-submitting-test-data.md - - ISIS Programming Exercises: - - Exercise 1: how-to-guides/isis-developer-guides/exercise-1.md - - Exercise 2: how-to-guides/isis-developer-guides/exercise-2.md + - 1. Developing ISIS3 with cmake: how-to-guides/isis-developer-guides/developing-isis3-with-cmake.md + - 1a. ISIS Development on ARM Macs: how-to-guides/isis-developer-guides/developing-mac-m1-arm-systems.md + - 2. ISIS Test Data: how-to-guides/isis-developer-guides/obtaining-maintaining-submitting-test-data.md + - 3. Contributing to ISIS - Overview: how-to-guides/isis-developer-guides/contributing-to-isis.md + - 4. Contributing to ISIS - Tutorial: how-to-guides/isis-developer-guides/building-and-contributing-to-isis-tutorial.md + - 5. Writing Tests with CTest and GTest: how-to-guides/isis-developer-guides/writing-isis-tests-with-ctest-and-gtest.md + - 6. Code Templates & Style: + - 6a. App Testing Templates: how-to-guides/isis-developer-guides/app-testing-cookbook.md + - 6b. Doxygen Tag Class Requirement: how-to-guides/isis-developer-guides/class-requirements-for-using-doxygen-tags.md + - 7. ISIS Programming Exercises: + - 7a. Exercise 1 - mirror: how-to-guides/isis-developer-guides/exercise-1.md + - 7b. Exercise 2 - diff: how-to-guides/isis-developer-guides/exercise-2.md - ALE Developer Guides: - Creating Ale Drivers: how-to-guides/ale-developer-guides/creating-ale-drivers.md