Contributing

This document outlines the guide for contributing to the PARA-ATM Research Collection. This repository is intended to showcase a collection of examples, demonstrations, and use cases for the national airspace safety and prognostics.

Organization

The Research Collection is organized using a directory structure that groups "modules" by topic area. At the top-level, there are directories associated with several general topic areas such as human-machine-integration and risk-mitigation-planning. Each topic directory is intended to hold a collection of related "modules", where each module showcases a particular analysis within that topic area. Individual modules may contain code examples, related data, and Jupyter notebooks for interactive demonstration.

Steps for Contributing

The basic steps for submitting a contribution to the Research Collection are as follows:

1. Get added as a contributor. NASA ULI team members can contact their PI to get added as a project contributor. Others are welcome to submit contributions using a pull request.
2. Identify the directory that your contribution falls under. In some cases, there may be overlap (a contribution may be related to multiple topics), but we suggest simply choosing the topic that is the most representative. Modules can always be moved later if needed.
3. Choose a name for your module. This will be the name of the sub-directory that you create under the topic directory. The module name should be short and descriptive if possible. Refer to some of the examples, such as vcas, svm-text-classifier, etc. As a convention, prefer to use dashes instead of underscores in the module name.
4. Prepare the files that you would like to submit, and place them into the appropriately named directory on your computer. More discussion of the types of files and content to submit is given below.
5. Commit the files directly to the master branch. This can be done a couple of different ways:
   • Using your web browser, got to the main project page and navigate into the topic directory where your contribution should go. Then drag-and-drop your directory from your computer onto the webpage. Write a short commit message about what you are adding, and you are done. Make sure that before you drag-and-drop, your directory includes only those files that you want to submit.
   • Alternatively, you can use the Git command line client. This is recommended if you intend to keep a local copy of the Research Collection on your computer that is synchronized with the version on GitHub. You will need to first clone the repository to your computer and then use the Git command line client to "add" your files, "commit" them, and finally "push" them to the remote GitHub repository. Unlike when working with the paraatm Python package, it is not necessary to worry about forks, pull requests, or branches.
6. Create a README.md file to describe your module. This file acts like a web page for you to provide an introduction to and description of your module and provide any relevant information about it. This can easily be done through the web interface by navigating into your module's directory, clicking "Add file", naming the file "README.md", and then editing the file online in markdown syntax. GitHub provides a "Preview Changes" button so that you can see how the file will be rendered. Once completed, this file will automatically be displayed when someone navigates into your directory through the GitHub web interface.

What to add

The Research Collection is intended to be flexible. Most of the project work is being done in Python, so it is anticipated that contributions will involve sample Python code and/or related data sets. Please be cognizant of file size and try to avoid submitting large data files (e.g., hundreds of megabytes). Please also make sure not to submit proprietary or other data that should not be made public.

Consider creating a Jupyter notebook as a way to showcase your module. The notebook can include formatted text to provide a description, together with code input and output. Notebook files are rendered by GitHub (for example, see paraatm-demo.ipynb) so that anyone can review them without installing or running the code. They can also be downloaded and used interactively. Information about installing and using Jupyter notebooks is here.