docs: Add CONTRIBUTING (#253)

* block isort

* block isort

* add vscode ext notes

* updating instructions (not complete)

* in progress

* add video test embed

* change video image

* play icon

* video play button

* play button

* cleanup

* cleanup

---------

Co-authored-by: Michael Mann <mmann1123@gmail.com>

.pre-commit-config.yaml

@@ -20,3 +20,9 @@ repos:
     rev: 6.0.0
     hooks:
     - id: flake8
+  # - repo: https://github.com/pycqa/isort
+  #   rev: 5.11.2
+  #   hooks:
+  #     - id: isort
+  #       name: isort (python)
+  #       args: [--settings-path=pyproject.toml]

CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contibuting to Geowombat
+
+We have two methods for contribution:
+
+1. Local install
+2. Docker-based debugging
+
+## 1. Local Install
+
+### Install GeoWombat
+
+#### Clone the latest repo
+
+```commandline
+git clone https://github.com/jgrss/geowombat.git
+```
+
+#### Create a virtual environment
+
+Modify the Python version (i.e., 3.8.15) as needed
+
+```commandline
+pyenv virtualenv 3.8.15 venv.gw
+```
+
+#### Activate the virtual environment
+
+```commandline
+pyenv activate venv.gw
+```
+
+#### Install pre-commit
+
+```commandline
+(venv.gw) pip install pre-commit
+(venv.gw) pre-commit install
+```
+
+#### Install GeoWombat
+
+Install other extras from `setup.cfg` as needed.
+
+```commandline
+(venv.gw) cd geowombat/
+(venv.gw) pip install -e .[tests]
+```
+
+### Create a new branch for your contribution
+
+```commandline
+(venv.gw) git checkout -b new_branch_name
+```
+
+### After making changes, run tests
+
+```commandline
+(venv.gw) cd tests/
+(venv.gw) python -m unittest
+```
+
+## 2. Docker debugging
+
+### Prerequisites
+
+- [Visual Studio Code](https://code.visualstudio.com/download)
+- [Docker VSCode Extension](https://code.visualstudio.com/docs/containers/overview)
+- [Docker Desktop](https://docs.docker.com/desktop/)
+
+1. Build `geowombat/dockerfiles/gw_docker_debug` by right clicking and hit `Build Image...`
+    - This will take a long time the first time only
+    - Give the image a name like `gw_debug`, hit Enter
+2. Click on dock extension tab on left panel of vscode
+3. Under Images click on `gw_debug` right click on `latest`, hit `Run Interactive`
+4. Under Individual Containers, right click on your running `gw_debug` instance, hit `Attach Visual Studio Code`
+5. Once opened make sure the `python` and `ipython` vscode extensions are installed in your attached vscode server
+6. Go to `geowombat/src/debug_script.py` run top cell.
+7. Add code and run `debug cell`
+
+View Example Video here: [![Debug Docker](https://github.com/jgrss/geowombat/blob/jgrss/features_precommit/data/resume.png?raw=true)](https://youtu.be/hBIE4qmOsgA "Debug Docker")
+
+### Create a Pull Request
+
+#### Commit and push changes
+
+```commandline
+git add .
+git commit -m 'your commit message'
+git push origin new_branch_name
+```
+
+#### GitHub Pull Request
+
+1. Go to 'Pull Requests' tab
+2. Go to 'New Pull Request'
+3. Choose 'base:main' and 'compare:new_branch_name'
+4. 'Create pull request'

dockerfiles/gw_docker_debug

@@ -24,30 +24,37 @@ RUN apt update -y && apt upgrade -y && \
     libgl1 \
     python-is-python3 \
     git -y \
+    curl -y \
     && apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 
 RUN pip install -U pip setuptools wheel
-RUN pip install -U --no-cache-dir "setuptools<=58.*"
-RUN pip install -U --no-cache-dir cython>=0.29.*
-RUN pip install -U --no-cache-dir numpy>=1.21.0
+RUN pip install -U --no-cache-dir "setuptools<=58.*" \
+    cython>=0.29.* \
+    numpy>=1.21.0 \
+    pip-tools \
+    rtree \
+    ipykernel \
+    black 
 
 
-RUN git clone https://github.com/jgrss/geowombat.git --branch jgrss/#242
+# install VS Code (code-server)
+RUN curl -fsSL https://code-server.dev/install.sh | sh
 
-RUN cd geowombat && pip install --user -e .[stac,time,perf,ml,zarr,coreg,tests,docs] 
-
-RUN pip install  pip-tools rtree ipykernel
-
-RUN pip install git+https://github.com/jgrss/sklearn-xarray
 
+# install geowombat or a branch using --branch option
+RUN git clone https://github.com/jgrss/geowombat.git #--branch jgrss/features_citests
+# install cloned geowombat 
+RUN cd geowombat && pip install --user -e .[stac,time,perf,ml,zarr,coreg,tests,docs] 
 
-RUN echo ' # %% \n\ 
+# add script to debug from
+RUN echo ' #%% \n\ 
     import sys \n\  
     sys.path.append("/") \n\ 
     sys.path.append("/geowombat") \n\ 
-    import geowombat as gw \n # %%' > ./geowombat/src/debug_script.py
+    import geowombat as gw \n #%%' > ./geowombat/src/debug_script.py
 
+# add debug profile
 RUN cd geowombat && mkdir -p .vscode 
 RUN  echo '{ \
     "version": "0.2.0", \
@@ -63,4 +70,12 @@ RUN  echo '{ \
     ] \
     }'> ./geowombat/.vscode/launch.json
 
-CMD cd geowombat/tests/ && python -m unittest &&  bash
+# install VS Code extensions
+RUN code-server    --install-extension ms-python.python \
+    --install-extension HoangKimLai.ipython
+
+# start from bash command line
+CMD /usr/bin/bash  
+
+# to run debug tests simply run:
+# cd geowombat/tests/ && python -m unittest  

pyproject.toml

@@ -24,3 +24,11 @@ exclude = '''
   | dist
 )/
 '''
+
+[tool.isort]
+line_length = 79
+multi_line_output = 3
+include_trailing_comma = true
+force_grid_wrap = 0
+use_parentheses = true
+ensure_newline_before_comments = true