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 virtual environment named `feds_env` with venv 
$ python -m venv feds_env
$ source feds_env/bin/activate

# OR create a virtual environment with conda
$ conda create --name feds_env python=3.11
$ conda activate feds_env

# install required dependencies 
$ pip install -e . 

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

  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)

    $ pytest -v tests/

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

    Note

    Requires configured read access to s3://eis-fire-public to run locally. These tests can also be run manually with the pytest workflow on GitHub Actions, and will be run automatically on any PR or push to the main branch of the repository.

    $ 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.

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.