From c2d8c4c45dd4c340a8ad435fe29551222637e629 Mon Sep 17 00:00:00 2001 From: jpl-jengelke Date: Mon, 8 Jan 2024 05:32:38 -0800 Subject: [PATCH] Slim Infusion: Add baseline SLIM templates with core information. ... --- .github/ISSUE_TEMPLATE/bug_report.md | 43 ++ .github/ISSUE_TEMPLATE/feature_request.md | 34 ++ .github/PULL_REQUEST_TEMPLATE.md | 2 +- CHANGELOG.md | 547 +--------------------- CODE_OF_CONDUCT.md | 28 +- CONTRIBUTING.md | 377 ++++++--------- LICENSE | 39 +- 7 files changed, 274 insertions(+), 796 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..c44e609d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,43 @@ +--- +name: Bug Report +about: Report a bug to help us improve +title: '[Bug]: ' +labels: 'bug' +assignees: '' + +--- + +**Checked for duplicates** + +> Have you checked for duplicate issue tickets? + +- Ex. Yes - I've already checked +- Ex. No - I haven't checked + +**Describe the bug** + +> A clear and concise description of what the bug is. Plain-text snippets preferred but screenshots welcome. + +Ex. When I did [...] action, I noticed [...] + +**What did you expect?** + +> A clear and concise description of what you expect to happen + +Ex. I expected [...] + +**Reproducible steps** + +> How would we reproduce this bug? Please walk us through it step by step. Plain-text snippets preferred but screenshots welcome. + +1. +2. +3. + +**What is your environment?** + +> Include any computer hardware, operating system, framework, browser, time-of-day or other contextual information related to your issue + +- Ex. Version of this software [e.g. vX.Y.Z] +- Ex. Operating System: [e.g. MacOSX with Docker Desktop vX.Y] +- ... diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..0b74a7aa --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,34 @@ +--- +name: New Feature +about: Suggest a new feature for us to implement +title: '[New Feature]: ' +labels: 'enhancement' +assignees: '' + +--- + +**Checked for duplicates** + +> Have you checked for duplicate issue tickets? + +- Ex. Yes - I've already checked +- Ex. No - I haven't checked + +**Alternatives considered** + +> Have you considered alternative solutions to your feature request? + +- Ex. Yes - and alternatives don't suffice +- Ex. No - I haven't considered + +**Related problems** + +> Is your feature request related to any problems? Please help us understand if so, including linking to any other issue tickets. + +Ex. I'm frustrated when [...] happens as documented in issue-XYZ + +**Describe the feature request** + +> A clear and concise description of your request. + +Ex. I need or want [...] diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 161ffc86..8ef73bbc 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -10,4 +10,4 @@ ## Testing - Provide some proof you've tested your changes - Example: test results available at ... -- Example: tested on operating system ... \ No newline at end of file +- Example: tested on operating system ... diff --git a/CHANGELOG.md b/CHANGELOG.md index 5813d37e..fb130d61 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,534 +1,13 @@ -# MMGIS Changelog - -## 2.9.0 - -_Sept 5, 2023_ - -#### Summary - -This release makes Layer IDs based on UUIDs instead of their layer names, greatly improves support for the dimension of time, adds property templates and group editing to DrawTool files, adds ability to link features together, upgrades our tiling scripts, and streamlines installations among other things. - -#### Added - -- Examples of wrapping MMGIS in an IFrame under `/examples` -- A full features TimeUI/Timeline Scrubber -- The InfoTool scans for and makes clickable url links -- Support for Composite Time Tiles that merge tiles across a time range on-the-fly on the backend -- Configurable Context Menu actions -- Polygons can have right-click context menu actions and form links with their WKT strings -- A GitHub workflow now builds [MMGIS docker images](https://github.com/NASA-AMMOS/MMGIS/pkgs/container/mmgis) -- The ability to pair features from one layer to another and render those paired targets in the Photosphere view. -- Optional Websocket verification to the configure page to notify of concurrent users. -- Ability to export the "working" configuration JSON from the configure page -- GET `/api/configure/missions` now supports the `full` parameter to return all configuration objects as well -- DrawTool users can enforce property template on their files -- Adds a `MAIN_MISSION` ENV that skips the landing page even if there are many missions -- Grouping editing for DrawTool files -- All endpoints can use longtermtokens -- The LegendTool can optionally be exposed as a togglable popup as well as other improvements -- Various additions to the `mmgisAPI` -- Upgraded gdal2customtiles to use gdal 3.5.2 and to support tiling in any projection -- GeoJSON validation on layers. -- GeoJSON data can be an empty [] -- Clicking intersects all features making impossible-to-reach features accessible through the InfoTool -- The DrawTool is integrated with time. - -#### Changed - -- Layers use UUIDs and identifiers instead of their layer names (backwards-compatibility still maintained) -- The ENV `PUBLIC_URL` is deprecated in fovar of the new `ROOT_PATH`. Unlike `PUBLIC_URL`, `ROOT_PATH` can fully be changed at runtime -- Database and POSTGIS extension are automatically created if they don't exist -- Upgraded the configure page's jquery from `1.11.1` to `3.6.1` - -#### Fixed - -- `ENABLE_MMGIS_WEBSOCKETS` name in sample.env -- Websockets try to reconnect and with exponential backoff -- Various issues regarding time layers -- Various issues regarding WMS layers -- MMGIS can now work with NodeJS 18+ -- Bug where initially on annotations features have no click events -- Bug where having the cursor over an annotation on the Map prevented pans and zooms -- Fixed the `angleUnit` property for image layer attachments -- Cloning a layer in the configure page -- Issue where logging in with AUTH=local would infinitely reload - ---- - -## 2.8.0 - -_Nov 14, 2022_ - -#### Summary - -#### Added - -- The Viewer Panel supports gltf models -- The configuration raw variable `markerAttachment.model` now has a `mtlProp` parameter for relative obj material files and can support multiple models per layer -- The DrawTool now supports drawing Circles and Rectangles -- The entire Configuration object has an API and can be updated via curl commands. See [ConfigureAPI](https://nasa-ammos.github.io/MMGIS/apis/configure) -- The MeasureTool now supports multiple DEMs -- Many additions to the `mmgisAPI`. See [JavaScriptAPI](https://nasa-ammos.github.io/MMGIS/apis/javascript) -- Adds an extended GeoJSON format to support per coordinate properties. See [Enhanced GeoJSON](https://nasa-ammos.github.io/MMGIS/configure/formats/enhanced-geojson) -- Deep Links now stores the layer order (if users rearranged them) -- The ability to define a primary coordinate system through a reworked [Coordinates Tab](https://nasa-ammos.github.io/MMGIS/configure/tabs/coordinates) -- DrawTool Layers can be added as regular layers by using a url of the form `api:drawn:` -- The ViewshedTool supports target heights -- The MeasureTool include line-of-sight -- Users can individually hide features through the InfoTool -- Layers can now be tagged and assigned a markdown description. Users can filter layers based on these fields as well. -- Added websockets that can notify users in real-time that a configuration has updated. Enabled with the env: `ENABLE_MMGIS_SOCKETS=true` -- Automatic labels can be rendered on features by configuring a raw variables `layerAttachments.labels` -- Added a `gdal2tiles_3.5.2.py` script to tile dem tiles with multi-processing support and tiling on top of an existing tileset -- The colorize Data Shader can now exclude up to three no data values -- Tilesets served from the MMGIS Missions directory now accept an optional `{t}` path directory to search and served tiles based on time -- The TimeUI and the bottom of the screen has been significantly reworked - -#### Changed - -- Increase GeoJSON math and export precision from `6` to `10` decimal places -- The DrawTool's tagging system has been expanded and it UI resembles folder structures -- Photosphere has better damping and rotates with "panning" directions. - -#### Fixed - -- Dragging a header in the LayersTool now drags the entire group -- Various fixes to how Time works (through the mmgisAPI, in parameterizing WMS layers, ...) -- Error if Data Layers had a space in their name -- Various mmgisAPI function fixes - ---- - -## 2.7.0 - -_Jun 9, 2022_ - -#### Summary - -This release adds geologic mapping to the DrawTool, layer reordering to the LayersTool and 3D annotations to the Globe. - -#### Added - -- [FGDC](https://ngmdb.usgs.gov/fgdc_gds/geolsymstd/download.php) Geologic patterns, linework and symbols in the DrawTool -- Annotation in the Globe View for both standard layers and drawn layers -- Ability for users to reorder layers in the LayersTool -- The Globe has 3d controls once again -- Visibility ranges can be added per feature with `minZoom` and `maxZoom` attributes under a feature's `properties.style` -- A true documentation site at https://nasa-ammos.github.io/MMGIS/ - -#### Changed - -- The vector layer `Visibility Cutoff` configuration has been deprecated (though it still works) in favor of `Minimum Zoom` and `Maximum Zoom` -- Improved the screenshot function -- Layer color indicators are more muted -- Default color scheme is a lighter black -- Lithosphere 1.3.0 => 1.5.1 - [See LithoSphere Releases](https://github.com/NASA-AMMOS/LithoSphere/releases) - -#### Fixed - -- Issue where `onLoaded` would fire multiple times -- Default MMGIS login fields are now removed from the DOM when not in use (merely hiding caused some annoyances with password extensions) -- Issue where deep link didn't position the camera in the Globe correctly -- Issue where some vector points the use DivIcons were not clickable - ---- - -## 2.6.0 - -_Mar 16, 2022_ - -#### New Requirements - -- Node.js >= v14.9.0 - -#### Summary - -This release adds a webhook manager to the configure page and improves documentation, the mmgisAPI, projection support, as well as synchronicity between the Map and Globe. - -#### Added - -- Configurable webhook manager. -- Access to a settings modal in the bottom left toolbar to toggle various UI elements' visibilities as well as the radius of tiles to query for the 3D Globe -- Raster effects (brightness, contrast, saturation, blend-mode) now apply in 3D as well -- Controlled layers can now utilized sublayers/marker-attachments -- Marker attachments, such as uncertainty ellipses, properly work for any projection -- 3D uncertainty ellipses -- Documentation for using remote virtual layers via GDAL -- PUBLIC_URL can be specified at build now in the Dockerfile -- mmgisAPI functions apply to the 3D Globe too now -- mmgisAPI can trim LineString features at the coordinates level - -#### Changed - -- LithoSphere 1.1.0 => 1.3.0 - [See LithoSphere Releases](https://github.com/NASA-AMMOS/LithoSphere/releases) -- Users can now pan the map while in the DrawTool's draw mode without placing a point -- Time controlled layers can now default to the current time for initial queries - -#### Fixed - -- Some media paths in the /configure path not working when MMGIS is served under a subdomain with PUBLIC_URL - ---- - -## 2.5.0 - -_Jan 10, 2022_ - -#### Summary - -This release contains the IsochroneTool, revives the Model layer type and includes a new Query layer type. Each vector layer can now be filtered by the user through the LayersTool, leads in the DrawTool can now draw and publish arrows and annotations, and the MeasureTool finally supports continuous elevation profiles. - -#### Added - -- Isochrone Tool! -- Model layer type! -- Query layer type! -- User filterable layers! -- More mmgisAPI functions -- Deep linking 'centerPin' parameter -- DrawTool lead Map file -- DrawTool text rotation -- Annotation and Arrows are now supported in regular (non-DrawTool) geojson -- Configurable bearings, uncertainty ellipses, models and underlaid images for vector points -- MeasureTool now supports a continuous profile -- MeasureTool csv export includes 3D distance as well -- LayersTool support sublayer visibility toggles within a layer's settings menu -- Python3 version of gdal2customtiles.py -- More Coordinates configurations -- Option in great_circle_calculator to calculate distance between points with Vincenty's formulae -- CHANGELOG.md -- Raw Variables Link has a new 'replace' section for modifying property values before injecting into a url - -#### Changed - -- LithoSphere 1.0.1 => 1.1.0 - [See LithoSphere Releases](https://github.com/NASA-AMMOS/LithoSphere/releases) -- LayersTool, LegendTool and InfoTool panels are wider -- The MMGIS M logo is now an svg -- bulk_tiles.py's colormap is now optional -- DrawTool's compile includes an inward buffer to allow for smaller drawn features to pass checks -- InfoTool now lists all intersected polygons of a layer under a mouse click - -#### Fixed - -- Viewsheds play nicely with polar maps -- Various improvements to the top search bar -- Legend items wrap to new line instead of extending off screen -- `colors` package fix -- `globeLon` deep link not working -- Uses `asHTML` for IdentifierTool again -- `apt-get update` in Dockerfile now uses -y (yes to all) flag - -#### Removed - -- Excess Globe feature highlighting - -## 2.4.0 - -_Aug 06, 2021_ - -#### Summary - -This release adds in the Viewshed Tool, time enabled layers, [LithoSphere](https://github.com/NASA-AMMOS/LithoSphere), WMS support, data layers, a JavaScript API, and more. - -#### Added - -- The Viewshed Tool! -- Time enabled layers, configurations and a time UI component. -- Full support for WMS layers and projections in 2D and 3D. -- Data layer colorize shader enabling dynamic rendering of data. -- An extensive window.mmgisAPI for interacting with MMGIS through an iframe. -- Configuration for point marker shape. -- Support for serving MMGIS at a subpath with the PUBLIC_URL environment variable. -- bulk_tiles.py auxiliary script. -- Features can be dehighlighted by clicking off on the map. -- Measure Tool supports measurements in kilometers. -- Ability to type in and go to a coordinate. -- Elevation values on mouse over. -- Configurable coordinates. -- Draw Tool features behave like regular layer features when the Draw Tool is closed. - -#### Changed - -- The Globe has been refactored and made standalone in the npm library LithoSphere. -- The Waypoint Kind now uses a top-down image of Perseverance. -- Migrated from Python2 to Python3. - -#### Fixed - -- Documentation uses only relative links for resources now. -- Issue with auth=none not working. -- Draw Tool drawings now work at the meter level. -- Draw Tool drawings now properly respect 0 valued styles. -- Data layer names now support spaces. - -#### Removed - -- All PHP dependencies. - ---- - -## 2.3.1 - -_Apr 22, 2021_ - -#### Summary - -A point release to address bug fixes. - -#### Fixed - -- WMS layers now work for full polar projections -- Raster layers obey order even if they're initially off -- Draw Tool truly accepts .json files - ---- - -## 2.3.0 - -_Apr 14, 2021_ - -#### Summary - -The Draw Tool gets its own tag filtering system. The Measure Tool now uses great arcs and is way more accurate and the map now fully supports WMS layers! - -#### Migration Details - -- The DrawTool tagging system change ideally needs more space in the `file_description` column. To increase it and not hit a tag or file description limit in drawing files, back-up the MMGIS database and run the SQL command: - -``` -ALTER TABLE user_files ALTER COLUMN file_description TYPE VARCHAR(10000); -``` - -#### Added - -- Draw Tool files can now be search for by user defined tags/keyword -- Draw Tool file options modal has been upgraded -- Admins can pin preferred tags -- Measure Tool now uses great arcs to compute measurements as well as for rendering lines -- A docker-compose.yml -- Fully functional WMS Map layers - -#### Removed - -#### Changed - -- Draw Tool requires a user to enter a file name before creating a file. (Instead of adding one as "New File") -- Draw Tool now accepts uploads of .json geojson files. (From just .geojson and .shp) -- Tools plugins are captured at build time! (You do not need to run `npm start` before building anymore) -- Info Tool contents are condensed - -#### Fixed - -- Screenshot widget no longer captures the faint bottom bar in its images -- Deep links to selected feature can now activate their info in the Info Tool -- AUTH=local allows users to sign in again -- Measure Tool profile download data is now accurate - ---- - -## 2.0.0 - -_Jan 14, 2021_ - -#### Migration Details - -- The environment variable `ALLOW_EMBED` has been replaced with `FRAME_ANCESTORS` -- `npm install` is only needed in the root directory and not in the /API directory any more -- Instead of `npm start`, use `npm run build` and then afterwards `npm run start:prod` to run the application. - _You will still need to run `npm start` before building the first time_ - -#### Added - -- Webpack! -- Production level builds -- Babel -- React support -- Icons as markers -- Configurable vector highlight color -- Graticules -- Configure page help buttons to docs - -#### Removed - -- Require.js -- Unused libraries, tools and code -- Swap widget -- FORCE_CONFIGCONFIG environment variable removed - -#### Changed - -- Info Tool upgraded! -- Measure Tool upgraded! -- Top bar search -- The environment variable ALLOW_EMBED has been replaced with FRAME_ANCESTORS -- MMGIS2 splash screen -- Various small UI changes -- Improved configure look tab -- Development logging is friendlier - -#### Fixed - -- Configure save warns of bad json -- Removed unused configure globe projection option -- Configure look tab colors work properly - ---- - -## 1.3.5 - -_Oct 19, 2020_ - -#### Added - -- ALLOW_EMBED environment variable -- DISABLE_LINK_SHORTENER environment variable - -#### Fixed - -- Tweaked various UI elements -- The Configure page Look tab now correctly reads in any existing `logourl` and `helpurl` -- Configure page now warns of invalid raw variable JSON -- Raw variable `info` values don't break when there's no text to replace in them -- Configuration endpoints no longer assume SQL output is ordered - ---- - -## 1.3.4 - -_Oct 06, 2020_ - -#### Added: - -- WMS tile support for the Map (does not yet work on the Globe). -- `AUTH` env can be set to "off" to disable user login entirely. -- gdal2customtiles.py for tiling datasets with custom projections. - ---- - -## 1.3.3 - -_Aug 07, 2020_ - -#### Added: - -- Example docker-compose - -#### Fixed: - -- 3D Globe was rendering layers in depth order instead of breadth order -- Draw Tool publishing sometimes undid the last Lead Map edits -- Draw Tool styling options sometimes hidden in FireFox - -#### Changed: - -- New short URLs are one character longer -- Draw Tool publish overlap tolerance increased - ---- - -## 1.3.2 - -_Jul 06, 2020_ - -#### Fixed - -- Draw Tool history sql commands assumed rows would be returned in order which could completely break the tool. -- Draw Tool layers would get stuck due to automatic toggling when copying to files or turning the file you're drawing in off. -- The waypoint image links on the Test mission have been fixed. - ---- - -## 1.3.1 - -_May 13, 2020_ - -#### Fixed - -- Additional authorization headers prevented access to the configure login page. - ---- - -## 1.3.0 - -_Apr 16, 2020_ - -#### New Requirements - -- Node.js >= v10.10 - -#### New Features - -- Export vector layers as geojson from the Layers Tool -- Info Tool uses a JSON viewer -- Users can now split and merge features in the Draw Tool -- Rich application logging -- ENVs that end with \_HOST are pinged at start to test connections -- Ability to configure deep links to other sites based on properties of a selected feature -- Users can upload much larger files in the Draw Tool -- Missions can be configured to use any map projection -- Globe level of detail -- Globe space themed skysphere -- Tools and Backends are included by scanning a directory for setup files instead of editing code -- The Legend Tool supports color scales -- CSV files can be uploaded as datasets and can be queried on feature click -- Early API tokens that allow .csvs to be uploaded programmatically -- An optional top bar with search functionality -- Configurable page name and logo -- On screen Globe controls -- Support both TMS and WMS tilesets -- Layer Kinds for specialized interactions -- Better documentation in /docs -- Resources cache properly - -#### Fixed - -- All tables are properly created with just one start -- Failed layers no longer crash the application -- Infinite login bug -- Vectors disappearing with string weights -- Some endpoint calls began with home slashes that broke certain setups - ---- - -## 1.2 - -_Nov 06, 2019_ - -#### Added - -- Limit access to the entire site with .env's `AUTH=local` -- Vector Tile Layers -- Store features within Postgres by uploading them with /configure's `Manage Geodatasets`. Point to them by setting the layer URL to `geodatasets:{name}`. Can serve both geojson and vector tiles. - ---- - -## 1.1.1 - -_Oct 25, 2019_ - -#### Fixed - -- Creating a new mission on the 'configure' page failed to make the appropriate mission directories (e.g. Layers). - ---- - -## 1.1 - -_Oct 02, 2019_ - -#### Summary - -MMGIS update with the Campaign Analysis Mapping and Planning (CAMP) tool. The software now runs fully in a node environment. Various other bug fixes and minor updates have been made to the code. - ---- - -## Open Source Release - -_Jun 06, 2019_ - -#### Summary - -This represents the initial release of the Multi-Mission Geographic Information System (MMGIS) software, developed under NASA-AMMOS. - -Dr. Fred J, Calef III & Tariq K. Soliman -NASA-JPL/Caltech +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [X.Y.Z](https://github.com/NASA-AMMOS//releases/tag/X.Y.Z) - 2023-MM-DD + +### Added + +- + diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index c59d01bf..211738d9 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,4 +1,5 @@ -# Contributor Covenant Code of Conduct + +# Code of Conduct ## Our Pledge @@ -17,23 +18,23 @@ diverse, inclusive, and healthy community. Examples of behavior that contributes to a positive environment for our community include: -- Demonstrating empathy and kindness toward other people -- Being respectful of differing opinions, viewpoints, and experiences -- Giving and gracefully accepting constructive feedback -- Accepting responsibility and apologizing to those affected by our mistakes, +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience -- Focusing on what is best not just for us as individuals, but for the overall +* Focusing on what is best not just for us as individuals, but for the overall community Examples of unacceptable behavior include: -- The use of sexualized language or imagery, and sexual attention or advances of +* The use of sexualized language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Publishing others' private information, such as a physical or email address, +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, without their explicit permission -- Other conduct which could reasonably be considered inappropriate in a +* Other conduct which could reasonably be considered inappropriate in a professional setting ## Enforcement Responsibilities @@ -59,7 +60,10 @@ representative at an online or offline event. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at (see contact links): https://github.com/riverma. +reported to the community administrators responsible for enforcement at +[@NikJPL (Aniwat.Nik.Sheurpukdi@jpl.nasa.gov)](https://github.com/NikJPL), +[@snnjpl (Shawn.N.Nguyen@jpl.nasa.gov)](https://github.com/snnjpl) or +[@sharimayer — Configuration Manager](https://github.com/sharimayer). All complaints will be reviewed and investigated promptly and fairly. All community leaders are obligated to respect the privacy and security of the diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c0ac20de..8fa01827 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,37 +1,24 @@ -# Contributing to MMGIS +# Contributing to MGViz Thanks for taking the time to consider contributing! We very much appreciate your time and effort. This document outlines the many ways you can contribute to our project, and provides detailed guidance on best practices. We look forward to your help! -## Introduction - -MMGIS (Multi-Mission Geographical Information System) is a highly-configurable, cross-mission web-based and open-source mapping application. It's been used on MSL, InSight, Mars 2020, EMIT, MAIA, Lunar VIPER, ... to name a few. And we would much appreciate your help! Here are the basics on contributing: - -- Anyone can contribute! -- You can contribute at any time -- You can contribute in any way (code, documentation, discussion topics, issue ticket discussions, etc.) - -Our team adapts to our stakeholders' processes and schedules and develops any and **all feature requests to be as mission-agnostic and reusable as possible.** - -Since we're an open source project, we also accept and encourage ad-hoc contributions at any time - just note it may take some time to review / decide whether to incorporate. - -### Quickstart to Contributing - -1. See our open list of [issue tickets](https://github.com/NASA-AMMOS/MMGIS/issues) and pick a ticket(s) you're interested in, or write your own! -1. Fork the `development` branch -1. Make a feature branch -1. Make your changes -1. Include the issue number as `#{issue_number}` in both your commit messages and PR title. -1. Submit a PR - -Feel free to reach out and ask questions! +## Prerequisites -#### Contributing Any Other Time +Before you begin contributing to our project, it'll be a good idea to ensure you've satisfied the below pre-requisites. -See our [Ways to Contribute](#ways-to-contribute) section. +### Developer Certificate of Origin (DCO) -## Prerequisites +To accept your contributions for any kind of patch, you'll want to: +1. Understand what a Developer Certificate of Origin is. See [this](https://wiki.linuxfoundation.org/dco) guide. +2. Read and agree to the [terms](https://developercertificate.org) of the Developer Certificate of Origin. +3. Remember to add your Sign-Off for each patch contribution you submit to our project via either: + 1. By using the `-s` flag if using Git. See [these](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt--s) instructions. + 2. By including the following text in your patch contributions (i.e. pull requests) + ``` + Signed-off-by: Full Name + ``` -Before you begin contributing to our project, it'll be a good idea to ensure you've satisfied the below pre-requisites. +Reviewers reviewing your patch will look for the sign-off before deciding to accept your contribution. ### License @@ -39,30 +26,32 @@ Our project has our licensing terms, including rules governing redistribution, d ### Code of Conduct -Our Code of Conduct helps facilitate a positive interaction environment for everyone involved with the team, and provides guidance on what to do if you experience problematic behavior. Read more in our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and make sure you agree to its terms. +Our Code of Conduct helps facilitate a positive interaction environment for everyone involved with the team, and provides guidance on what to do if you experience problematic behavior. Read more in our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), and make sure you agree to its terms. + +### Governance Model + +Our Governance model helps outline our project's decision making and roles-based expectations. Read more in our [GOVERNANCE.md](GOVERNANCE.md). ### Developer Environment -For patch contributions, see our Developer Documentation (TBD) for more details on how to set up your local environment, to best contribute to our project. +For patch contributions, see our [Developer Documentation](https://github.com/NASA-AMMOS/MGViz/wiki) for more details on how to set up your local environment, to best contribute to our project. At a minimum however to submit patches (if using Git), you'll want to ensure you have: - 1. An account on the Version Control System our project uses (i.e. GitHub). 2. The Version Control System client (i.e. Git) installed on your local machine. -3. The ability to edit, build, and test our project on your local machine. Again, see our `README.md` or detailed developer guide for more details +3. The ability to edit, build, and test our project on your local machine. Again, see our [README.md](README.md) or detailed developer guide for more details ### Communication Channels Before contributing changes to our project, it's a great idea to be familiar with our communication channels and to socialize your potential contributions to get feedback early. This will help give you context for your contributions, no matter their form. Our communication channels are: - -- [Issue tracking system](https://github.com/NASA-AMMOS/MMGIS/issues) - a regularly monitored area to report issues with our software or propose changes -- [Discussion board](https://github.com/NASA-AMMOS/MMGIS/discussions) - an permanently archived place to hold conversations related to our project, and to propose as well as show+tell topics to the contributor team. This resource can be searched for old discussions. +- [Issue tracking system](https://github.com/NASA-AMMOS/MGViz/issues) - a regularly monitored area to report issues with our software or propose changes +- [Discussion board](https://github.com/NASA-AMMOS/MGViz/discussions) - a permanently archived place to hold conversations related to our project, and to propose as well as show+tell topics to the contributor team. This resource can be searched for old discussions. ## Our Development Process -Our project integrates contributions from many people, and so we'd like to outline a process you can use to visualize how your contributions may be integrated if you provide something. +Our project integrates contributions from many people, and so we'd like to outline a process you can use to visualize how your contributions may be integrated if you provide something. ```mermaid flowchart TD @@ -75,22 +64,19 @@ flowchart TD ### Fork our Repository -Forking our repository, as opposed to directly committing to a branch is the preferred way to propose changes. +Forking our repository, as opposed to directly committing to a branch is the preferred way to propose changes. See [this GitHub guide](https://docs.github.com/en/get-started/quickstart/fork-a-repo) on forking for information specific to GitHub.com #### Find or File an Issue -Make sure people are aware you're working on a patch! Check out our [issue tracking system](https://github.com/NASA-AMMOS/MMGIS/issues) and find an open issue you'd like to work against, or alternatively file a new issue and mention you're working on a patch. +Make sure people are aware you're working on a patch! Check out our [issue tracking system](https://github.com/NASA-AMMOS/MGViz/issues) and find an open issue you'd like to work against, or alternatively file a new issue and mention you're working on a patch. #### Choose the Right Branch to Fork Our project typically has the following branches available, make sure to fork either the default branch or a branch someone else already tagged with a particular issue ticket you're working with. - -- `master` - default branch, and contains the latest MMGIS release -- `development` - active development area for MMGIS deliverables, and typically ahead of `master`. **This is the branch you want to fork from.** - -_Note: Some customers prefer the latest features of the `development` branch at the expense of stability. All changes pulled into `development` should be considered operational with a reasonable degree of confidence._ +- `develop` — default branch, used for new code development +- `main` — release branch ### Make your Modifications @@ -98,31 +84,32 @@ Within your local development environment, this is the stage at which you'll pro #### Commit Messages -Commit messages to version control should reference a ticket in their Issue Number - title / summary line: +Commit messages to version control should reference a ticket in their title / summary line: ``` -#248 - Show an example commit message title +Issue #248 - Show an example commit message title ``` This makes sure that tickets are updated on GitHub with references to commits that are related to them. Commit should always be atomic. Keep solutions isolated whenever possible. Filler commits such as "clean up white space" or "fix typo" should be merged together before making a pull request, and significant sub-feature branches should be [rebased](https://www.youtube.com/results?search_query=git+rebase) to preserve commit history. Please ensure your commit history is clean and meaningful! +Additionally, remember to "Sign-Off" on your commits to align with our [Developer Certificate of Origin (DCO) policy](#developer-certificate-of-origin-dco). + ### Submit a Pull Request -Pull requests are the core way our project will receive your patch contributions. Navigate to your branch on your own fork within the version control system, and submit a pull request or submit the patch text to our project. +Pull requests are the core way our project will receive your patch contributions. Navigate to your branch on your own fork within the version control system, and submit a pull request or submit the patch text to our project. -Please make sure to provide a meaningful text description to your pull requests, whenever submitted. Our pull-request template will be auto-generated for you when you create your pull-request. See the template [here](.github/PULL_REQUEST_TEMPLATE.md). +Please make sure to provide a meaningful text description to your pull requests, whenever submitted. Our pull-request template will be auto-generated for you when you create your pull-request. See the template [here](.github/PULL_REQUEST_TEMPLATE.md). **Working on your first Pull Request?** See guide: [How to Contribute to an Open Source Project on GitHub](https://kcd.im/pull-request) ### Reviewing your Pull Request Reviewing pull-requests, or any kinds of proposed patch changes, is an art. That being said, we follow the following best practices: - - **Intent** - is the purpose of your pull-request clearly stated? - **Solution** - is your pull-request doing what you want it to? -- **Correctness** - is your pull-request doing what you want it to _correctly_? +- **Correctness** - is your pull-request doing what you want it to *correctly*? - **Small Patches** - is your patch of a level of complexity and brevity that it can actually be reviewed by a human being? Or is does it involve too much content for one pull request? - **Coding best practices** - are you following best practices in the coding / contribution language being used? - **Readability** - is your patch readable, and ultimately maintainable, by others? @@ -133,20 +120,19 @@ Reviewing pull-requests, or any kinds of proposed patch changes, is an art. That ### ⚠️ Issue Tickets -> _Do you like to talk about new features, changes, requests?_ +> *Do you like to talk about new features, changes, requests?* -Issue tickets are a very simple way to get involved in our project. It also helps new contributors get an understanding of the project more comprehensively. This is a great place to get started with the project if you're not sure where to start. +Issue tickets are a very simple way to get involved in our project. It also helps new contributors get an understanding of the project more comprehensively. This is a great place to get started with the project if you're not sure where to start. -See our list of issues at: https://github.com/NASA-AMMOS/MMGIS/issues +See our list of issues at: https://github.com/NASA-AMMOS/MGViz/issues #### Cleaning up Duplicate Issues -Often we receive duplicate issues that can confuse project members on _which_ issue ticket to hold conversations upon. +Often we receive duplicate issues that can confuse project members on *which* issue ticket to hold conversations upon. Here's how you can help: - -1. Scan the list of _open_ issue tickets for duplicate titles, or internal wording -2. If you find duplicates, copy / paste the below message on the conversation thread of the issue ticket _that has less participants_ involved +1. Scan the list of *open* issue tickets for duplicate titles, or internal wording +2. If you find duplicates, copy / paste the below message on the conversation thread of the issue ticket *that has less participants* involved ``` This is a duplicate issue. Please migrate conversations over to [issue-XYZ](hyperlink to issue) @@ -154,13 +140,13 @@ This is a duplicate issue. Please migrate conversations over to [issue-XYZ](hype #### Good First Issues -Issue tickets can vary in complexity, and issues labeled with `good first issue` labels are often a great way to get started with the project as a newcomer. +Issue tickets can vary in complexity, and issues labeled with `good first issue` labels are often a great way to get started with the project as a newcomer. -Take a look at our [issue tracking system](https://github.com/NASA-AMMOS/MMGIS/issues), and filter by `good first issue` for issues that are low-complexity, and that will help you get familiar with our issue tracking and patch submission process. +Take a look at our [issue tracking system](https://github.com/NASA-AMMOS/MGViz/issues), and filter by `good first issue` for issues that are low-complexity, and that will help you get familiar with our issue tracking and patch submission process. #### Suggesting New Issue Labels -Labels within our [issue tracking system](https://github.com/NASA-AMMOS/MMGIS/issues) are a great way to quickly sort through tickets. The project may not yet have labels to cover the full variety of issue tickets. Take a look through our list of issues, and if you notice a set of issue tickets that seem similar but are not categorized with an existing label, go ahead submit a request within one of the issues you've looked at with the following text: +Labels within our [issue tracking system](https://github.com/NASA-AMMOS/MGViz/issues) are a great way to quickly sort through tickets. The project may not yet have labels to cover the full variety of issue tickets. Take a look through our list of issues, and if you notice a set of issue tickets that seem similar but are not categorized with an existing label, go ahead submit a request within one of the issues you've looked at with the following text: ``` I've noticed several other issues that are of the same category as this issue. Shall we make a new label for these types of issues? @@ -169,133 +155,185 @@ I've noticed several other issues that are of the same category as this issue. S #### Submitting Bug Issues Resolving bugs is a priority for our project. We welcome bug reports. However, please make sure to do the following prior to submitting a bug report: - -- **Check for duplicates** - there may be a bug report already describing your issue, so check the [issue tracking system](https://github.com/NASA-AMMOS/MMGIS/issues) first. +- **Check for duplicates** - there may be a bug report already describing your issue, so check the [issue tracking system](https://github.com/NASA-AMMOS/MGViz/issues) first. Here's some guidance on submitting a bug issue: - -1. Navigate to our [issue tracking system](https://github.com/NASA-AMMOS/MMGIS/issues) and file a new issue +1. Navigate to our [issue tracking system](https://github.com/NASA-AMMOS/MGViz/issues) and file a new issue 2. Select a bug template (if available) for your issue 1. Fill out the template fields to the best of your ability, including output snippets or screenshots where applicable 3. Follow the general guidelines below for extra information about your bug 1. Include a code snippet if you have it showcasing the bug 2. Provide reproducible steps of how to recreate the bug - 3. If the bug triggers an exception or error message, include the _full message_ or _stacktrace_ + 3. If the bug triggers an exception or error message, include the *full message* or *stacktrace* 4. Provide information about your operating system and the version of our project you're using +#### Submitting New Feature Issues + +We welcome new feature requests to help grow our project. However, please make sure to do the following prior to submitting a new feature request: +- **Check for duplicates** - there may be a new feature issue already describing your issue, so check the [issue tracking system](https://github.com/NASA-AMMOS/MGViz/issues) first +- **Consider alternatives** - is your feature really needed? Or is there a feature within our project or with a third-party that may help you achieve what you want? + +Here's some guidance on submitting a new feature issue: +1. Navigate to our [issue tracking system](https://github.com/NASA-AMMOS/MGViz/issues) and file a new issue +2. Select a new feature template (if available) for your issue + 1. Fill out the template fields to the best of your ability + #### Submitting Security Vulnerability Issues Security vulnerabilities should **not** be filed to the regular issue tracking system. -Report your security vulnerabilities to (see contact links): https://github.com/tariqksoliman +Report your security vulnerabilities to (see contact links): [@jl-0](https://github.com/jl-0) or [@jeffreypon](https://github.com/jeffreypon) Please be sure to: - -- Indicate the severity of the vulnerability -- Provide any workarounds, if you know them -- Provide return-contact information to follow-up with you if needed +* Indicate the severity of the vulnerability +* Provide any workarounds, if you know them +* Provide return-contact information to follow-up with you if needed #### Reviewing Pull Requests -Reviewing others' contributions is a great way to learn about best practices in both contributions as well as software. - -Take a look at our [pull requests tracking system](https://github.com/NASA-AMMOS/MMGIS/pulls), and try the following options for providing a review: +Reviewing others' contributions is a great way to learn about best practices in both contributions as well as software. +Take a look at our [pull requests tracking system](https://github.com/NASA-AMMOS/MGViz/pulls), and try the following options for providing a review: 1. Read the code / patch associated with the pull-request, and take note of any coding, bug, or documentation issues if found 2. Try to recreate the pull-request patch on your local machine, and report if it has issues with your system in particular 3. Scan over suggested feedback from other contributors, and provide feedback if necessary -### 📖 Documentation +### 💻 Code -Documentation is the core way our users and contributors learn about the project. We place a high value on the quality, thoroughness, and readability of our documentation. Writing or editing documentation is an excellent way to contribute to our project without performing active coding. +⚠️ It's **highly** advised that you take a look at our [issue tracking system](https://github.com/NASA-AMMOS/MGViz/issues) before considering any code contributions. Here's some guidelines: +1. Check if any duplicate issues exist that cover your code contribution idea / task, and add comments to those tickets with your thoughts. +2. If no duplicates exist, create a new issue ticket and get a conversation started before making code changes using our [communication channels](#communication-channels). -⚠️ It's **highly** advised that you take a look at our [issue-tracking system](https://github.com/NASA-AMMOS/MMGIS/issues) before considering any documentation contributions. Here's some guidelines: +Once you have a solid issue ticket in hand and are ready to work on code, you'll want to: +1. Ensure you have development [prerequisites](#prerequisites) cleared. +2. Have your [development environment](#developer-environment) set up properly. +3. Go through our [development process](#our-development-process), including proposing changes to our project. + +Some guidelines for code-specific contributions: +- **Do your homework** - read-up on necessary documentation, like `README.md`s, developer documentation, and pre-existing code to see the intention and context necessary to make your contribution a success. It's important to _communicate_ what you're working on through our project [communication channels](#communication-channels) and get buy-in from frequent contributors - this will help the project be more receptive to your contributions! +- **Ask questions** - its important to ask questions while you work on your contributions, to check-in with frequent contributors on the style and the set of expectations to make your code contribution work well with pre-existing project code. Use our [communication channels](#communication-channels) +- **Keep positive** - code contributions, by their nature, have direct impacts on the output and functionality of the project. Keep a positive spirit as your code is reviewed, and take it in stride if core contributors take time to review, give you suggestions for your code or respectfully decline your contribution. This is all part of the process for quality open source development. +- **Comments** - include *useful* comments throughout your code that explain the intention of a code block, not a step-by-step analysis. See our [inline code documentation](#inline-code-documentation) section for specifics. + + +### 📖 Documentation +Documentation is the core way our users and contributors learn about the project. We place a high value on the quality, thoroughness, and readability of our documentation. Writing or editing documentation is an excellent way to contribute to our project without performing active coding. + +⚠️ It's **highly** advised that you take a look at our [issue-tracking system](https://github.com/NASA-AMMOS/MGViz/issues) before considering any documentation contributions. Here's some guidelines: 1. Check if any duplicate issues exist that cover your documentation contribution idea / task, and add comments to those tickets with your thoughts. 2. If no duplicates exist, create a new issue ticket and get a conversation started before making documentation changes. Some guidelines for documentation best practices (summarized from Google's [excellent documentation guide](https://google.github.io/styleguide/docguide/best_practices.html)): - -- **Minimum viable docs** - don't do less documentation than your readers need, but also don't do more -- **Changed best practice use cases = changed docs** - if your best practice use cases have changed, remember to update your documentation +- **Minimum viable docs** - don't do less documentation than your users / developers need, but also don't do more +- **Changed code = changed docs** - if your code has changed, remember to update your documentation - **Delete old docs** - continually clean your documentation tree, and remove outdated docs regularly #### Documentation Organization The overall structure of our project documentation is as follows: +- Source-controlled documentation + - [README.md](README.md) - top-level information about how to run, build, and contribute to the project + - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - best practices and guidance on how to work well with other people in the project, and suggestions on dealing with interpersonal issues + - [CONTRIBUTING.md](CONTRIBUTING.md) - guidance on contributing to the project + - `*.java` - inline documentation available inside code files +- Hosted documentation + - [Wiki Main-page](https://github.com/NASA-AMMOS/MGViz/wiki) +- Discussion Boards + - [Discussions](https://github.com/NASA-AMMOS/MGViz/discussions) + For directions on contributing to our source-controlled documentation: - 1. Ensure you have development [prerequisites](#prerequisites) cleared. 2. Have your [development environment](#developer-environment) set up properly. 3. Go through our [development process](#our-development-process), including proposing changes to our project. -#### MMGIS Configuration Documentation + #### Writing Style To ensure documentation is readable and consistent by newcomers and experts alike, here are some suggestions on writing style for English: +- Use gender neutral pronouns (they/their/them) instead of he/she/his/her +- Avoid qualifiers that minimize the difficulty of a task at hand, e.g. avoid words like “easily”, “simply”, “just”, “merely”, “straightforward”, etc. Readers' expertise may not match your own, and qualifying complexity may deter some readers if the task does not match their level of experience. That being said, if a particular task is difficult or complex, do mention that. -- Use gender neutral pronouns (they/their/them) instead of he/she/his/her -- Avoid qualifiers that minimize the difficulty of a task at hand, e.g. avoid words like "easily", "simply", "just", "merely", "straightforward", etc. Readers' expertise may not match your own, and qualifying complexity may deter some readers if the task does not match their level of experience. That being said, if a particular task is difficult or complex, do mention that. - -#### Common Wording +#### Common Wording Below are some commonly used words you'll want to leverage in your documentation contributions: - -- **GitHub** - one word, and capitalization of the 'G' and the 'H' -- **MMGIS** - one word, all capitalized +- **AMMOS** - Advanced Multi-Mission Operations System tool set. +- **Artifactory** - Lab-based artifact repository that stores compiled builds for reuse. +- **GitHub** - One word with capitalization of the 'G' and 'H'. +- **Jenkins** - Continuous Integration (CI) server that hosts many Lab builds. +- **MIPL** - Multimission Instrument Processing Lab which hosts the project containing this repository. +- **VICAR Java Build** - The build system that collects and compiles related code. #### Inline Code Documentation -For language-specific guidance on code documentation, including style guides, see [Google's list of language style guides](https://google.github.io/styleguide/) for a variety of languages. +For language-specific guidance on code documentation, including style guides, see [Google's list of language style guides](https://google.github.io/styleguide/) for a variety of languages. -Additionally, take a look at Google's recommendations on [inline code documentation](https://google.github.io/styleguide/docguide/best_practices.html#documentation-is-the-story-of-your-code) for best practices. +Additionally, take a look at Google's recommendations on [inline code documentation](https://google.github.io/styleguide/docguide/best_practices.html#documentation-is-the-story-of-your-code) for best practices. #### Media -Media, such as such as images, videos, sound files, etc., are an excellent way to explain documentation to a wider audience more easily. Include media in your contributions as often as possible. +Media, such as images, videos, sound files, etc., are an excellent way to explain documentation to a wider audience more easily. Include media in your contributions as often as possible. When including media into our version-control system, it is recommended to use formats such as: - - Diagrams: [Mermaid](https://mermaid-js.github.io/mermaid/#/) format - Images: JPEG format - Videos: H264 MPEG format - Sounds: MP3 format + ### ❓ Questions -Answering questions is an excellent way to learn more about our project, as well as get better known in our project community. +Answering questions is an excellent way to learn more about our project, as well as get better known in our project community. Here are just a few ways you can help answer questions for our project: - -- Answer open questions in our [discussion forum](https://github.com/NASA-AMMOS/MMGIS/discussions/categories/q-a) -- Answer open questions mentioned in our [issue tracking system](https://github.com/NASA-AMMOS/MMGIS/issues) +- Answer open questions in our [discussion forum](https://github.com/NASA-AMMOS/MGViz/discussions) +- Answer open questions mentioned in our [issue tracking system](https://github.com/NASA-AMMOS/MGViz/issues) + When answering questions, keep the following in mind: - - Be polite and friendly. See our [Code of Conduct](CODE_OF_CONDUCT.md) recommendations as you interact with others in the team. - Repeat the specific question you are answering, followed by your suggestion. - If suggesting code, repeat the line of code that needs to be altered, followed by your alteration -- Include any post-steps or checks to verify your answer can be reproduced +- Include any post-steps or checks to verify your answer can be reproduced ### 🎨 Design Design files can help to guide new features and new areas of expansion for our project. We welcome these kinds of contributions. Here are just a few ways you can help provide design recommendations for our project: - - Create visual mockups or diagrams to increase usability of our project applications. This can apply to user interfaces, documentation structuring, or even code architecture diagrams. - Conduct user research to understand user needs better. Save your findings within spreadsheets that the project team / contributors can review. - Create art, such as logos or icons, to support the user experience for the project @@ -305,143 +343,8 @@ Each of the above can be contributed directly to repository code, and you should ### 🎟️ Meetups A great way to contribute towards our project goals is to socialize and encourage people to meet and learn more about each other. Consider ideas like: - - Propose workshops or meetups regarding some topic within our project - Help point project contributors and community members to conferences and publications where they may socialize their unique innovations - Schedule in-person or virtual happy-hours to help create a more social atmosphere within the project community -For the above ideas, use our [communication channels](#communication-channels) to propose get-togethers. - ---- - -# Larger Coding Contributions - -MMGIS supports pluginable backend APIs and frontend Tools. - -## Developing A New Tool - -### Setup - -New tools are automatically found and included on start. - -1. Go to `src/essence/Tools` - - 1. Create a new directory here with the name of your new tool - 1. Copy and paste `New Tool Template.js` into your new directory - 1. Rename the pasted file to `[Your Tool's Name]Tool.js` - 1. Add a `config.json` file so that MMGIS can find it. Do look at the existing tools' `config.json` but here's a template: - - ```javascript - { - "defaultIcon": "a material design icon https://pictogrammers.com/library/mdi/ identifier", - "description": "A quick description of the tool's capabilities.", - "descriptionFull": { - "title": "A longer description of the tool's capabilities.", - "example": { - "A example object of the configuration variables the tool accepts": "value" - } - }, - "hasVars": true, - "name": "{toolName}", - "toolbarPriority": 3, - "paths": { - "{toolName}Tool": "essence/Tools/{toolName}/{toolName}Tool" - }, - "expandable": false - } - - ``` - -1. Restart the server with `npm start` - -1. Use the `/configure` page to enable the tool in your development environment - -### Developing - -#### Overview - -Ideally all the code for a tool will be in its `[Tool's Name]Tool.js` and built off of the `New Tool Template.js`. - -- All tools must return an object with `make` and `destroy` functions. - - `make` is called when the user clicks on the tool's icon while `destroy` is called when the user clicks on any other tool's icon. -- Tools should work independently of one another. -- Tools should only change the `#tools` div or something in the viewer, map and/or globe. -- Use `width` or `height` entries to set the tool div's dimensions. - -### Notes - -- There are private repos with pluginable tools that are not visible to the public. If you would like to include your own private tool, place it in a `/src/essence/MMGIS-Private-Tools` directory. - -## Developing A New Backend - -### Setup - -New backends are automatically found and included on start. - -1. Go to `API/Backend` - 1. Create a new directory here with the name of your new backend - 1. Copy and paste `setupTemplate.js` into your new directory - 1. Rename the pasted file to `setup.js` - 1. Edit `setup.js` based on the development guide below -1. Restart the server with `npm start` - -### Developing - -#### Overview - -All the code for a backend must stay in its `API/Backend/[name]` directory. - -- Backends should work independently of one another. -- Use the existing backends as a reference point. - -#### Template Walkthrough - -```javascript -const router = require("./routes/your_router"); -``` - -Write scripts within you backend directory and import them. Most backends follow the directory structure: - -- API/Backend/[name] - - models/ - - routes/ - - setup.js - -``` -let setup = { - //Once the app initializes - onceInit: s => {}, - //Once the server starts - onceStarted: s => {}, - //Once all tables sync - onceSynced: s => {}, - envs: [{ name: "ENV_VAR", description: "", required: false, private: false }] -}; -``` - -onceInit() is called immediately on `npm start` -onceStarted() is called once the http server starts up -onceSynced() is called once all table are created/has their existence verified. - -The s parameter is an object containing the app and middleware. A common form to attach an API within a `setup.js` is to fill onceInit() with: - -```javascript -onceInit: (s) => { - s.app.use( - "/API/example", - s.ensureUser(), - s.checkHeadersCodeInjection, - s.setContentType, - s.stopGuests, - importedRouter - ); -}; -``` - -`envs` help document which environment values the backend uses and logs errors if required environment variables aren't set. Variables that end with `_HOST` are for URLs and upon start up they'll be pinged and there status will be logged. - -Please refer to the existing backend directories for further examples. - ---- - -_CONTRIBUTING.md template by [NASA SLIM](https://github.com/nasa-ammos/slim)_ +For the above ideas, use our [communication channels](#communication-channels) to propose get-togethers. diff --git a/LICENSE b/LICENSE index ffd05827..17c357d7 100644 --- a/LICENSE +++ b/LICENSE @@ -175,18 +175,33 @@ END OF TERMS AND CONDITIONS - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright 2020 California Institute of Technology + Copyright (c) 2022 California Institute of Technology ("Caltech"). + U.S. Government sponsorship acknowledged. + + All rights reserved. + + Redistribution and use in source and binary forms, with or without modification, are permitted provided + that the following conditions are met: + * Redistributions of source code must retain the above copyright notice, this list of conditions and + the following disclaimer. + * Redistributions in binary form must reproduce the above copyright notice, this list of conditions + and the following disclaimer in the documentation and/or other materials provided with the + distribution. + * Neither the name of Caltech nor its operating division, the Jet Propulsion Laboratory, nor the + names of its contributors may be used to endorse or promote products derived from this software + without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS + IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, + THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR + PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR + CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; + OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, + WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR + OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF + ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.