Contributing

Author

Zeb Becker

We follow a standard feature branch workflow, as described here.

Example workflow

  1. Setup:

    # clone repository 
$ git clone https://github.com/Earth-Information-System/fireatlas.git
$ cd fireatlas

# create and activate environment named `fire_env`
$ conda env create -f env.yml
$ conda activate fire_env

# install optional dev dependencies if needed 
$ pip install -e .[dev]

  2. Create a new branch and make your changes as needed. Name the branch {your initials}/{descriptive feature name}:

    $ git switch -c zb/add-noaa21 

# make changes 
$ git add fireatlas/my_changed_file.py
$ git commit -m "Add NOAA21 inputs"

  3. Run tests from fireatlas root dir (requires optional dependencies)

    $ pytest -v tests/

  4. OPTIONAL: run long-running (~15mins) integration tests

    $ pytest -v --runslow tests/

  5. Push to your branch on GitHub.

    # The first time you push your new branch, set upstream: 
$ git push -u origin zb/add-noaa21

# Subsequently, you can just do:
$ git push

  6. When you are ready, create a pull request to merge your branch into the main branch, conus-dps. Most substantive changes should be reviewed by another team member, and all changes must wait to be merged until the automated tests have passed.

Juptyer Notebooks

To use a Jupyter Notebook with the development environment:

# First, create conda environment following directions in Step 1 above 
# Then, from the fireatlasroot dir: 
$ pip install .[dev]
$ python -m ipykernel install --user --name fire_env --display-name "Python - FEDS development environment"
# wait 30 seconds or so, then launch a new notebook. You should see this environment as an option to choose from in the launcher.

This assumes you are using a JupyterLab interface such as the MAAP ADE.

Editing Docs

We use Quarto to build this website. Most of the source files are plaintext .qmd files written in Quarto markdown. You can edit them in any text editor, including with the MAAP ADE or even directly on GitHub. However, if you are making more extensive changes or using formatting, you should preview what the rendered website will look like.

Website formatting and page structure are defined in _quarto.yml.

You can use VSCode, Jupyter, RStudio, NeoVim, or any text editor + CLI to run Quarto. Info on getting started can be found in the Quarto docs here.

Below is a quick demo of how you can use VSCode on your local machine to preview the website and edit with a visual (WYSIWYG) editor.

  1. Download Quarto

  2. Install jupyter if needed (pip install jupyter)

  3. Install Quarto extension in VSCode

  4. Clone this repo and open it in VSCode.

  5. Make edits to .qmd, .md or .ipynb files, or _quarto.yml.

    Tip

    Open the Command Palette (cmd-shift-p on Mac) and select Quarto: Edit in Visual Mode for What You See Is What You Get editing. Select Quarto: Edit in Source Mode to go back.

  6. Preview website. Select the Preview icon in upper right, use the keyboard shortcut cmd-shift-k, or use the Quarto: Preview command from the Command Palette.

  7. Once everything looks good, commit your changes and push to GitHub. If you pushed directly to main, GitHub will automatically build and deploy the new website reflecting your changes. If you are working on a branch, GitHub will build and deploy your changes when you create a pull request and merge your branch into main.

Note

Most users should never need to do this. However: to rebuild the active GitHub Pages website from a branch other than the main branch, checkout that branch and run quarto publish gh-pages from within that directory. This will trigger a site rebuild based on the checked out branch. Note that it will be superseded as soon as another push is made to the main branch.