From 1a788ab6af109da033ac37c60c8272807c61b1e2 Mon Sep 17 00:00:00 2001
From: "E. Joshua Rigler" <erigler@usgs.gov>
Date: Wed, 28 Feb 2024 12:53:54 -0700
Subject: [PATCH] Major update to develop.md

- update advice on 'forking workflow' since this is only valid for
  those with a code.usgs.gov account
- emphsize `pyproject.toml` and `poetry` as dependency tracking tools
- update `Developer Tools` section to describe how `poetry` and
  poetthepoet are used to run linting, unit tests, and audits
---
 docs/develop.md | 70 ++++++++++++++++++++++++++++---------------------
 1 file changed, 40 insertions(+), 30 deletions(-)

diff --git a/docs/develop.md b/docs/develop.md
index f492c545..0bae5356 100644
--- a/docs/develop.md
+++ b/docs/develop.md
@@ -5,8 +5,12 @@ code for this project, but may also be used to run a local copy of the code.
 
 ## Clone Project
 
-This project uses a forking workflow.
-https://guides.github.com/activities/forking/
+This project uses a forking workflow (https://guides.github.com/activities/forking/).
+An account on https://code.usgs.gov/ is required to do this. "Collaborator" accounts can 
+be requested for vetted regular contributors without an account already. Issues can be
+reported, including small patches, through our
+["service desk"](mailto:<gs_gitlab_servicedesk%2bghsc-geomag-geomag-algorithms-3963-issue-@usgs.gov>)
+(no account required)
 
 1.  Fork this project from code.usgs.gov.
 
@@ -14,61 +18,67 @@ https://guides.github.com/activities/forking/
 
 2.  Clone your fork
 
-        git clone https://code.usgs.gov/ghsc/{YOUR_GITHUB_ACCOUNT}/geomag-algorithms.git
+        git clone https://code.usgs.gov/{YOUR_ACCOUNT}/geomag-algorithms.git
         cd geomag-algorithms
         git remote add upstream https://code.usgs.gov/ghsc/geomag/geomag-algorithms.git
 
 3.  Use branches to develop new features and submit pull requests.
 
 ## Install Dependencies
+This project maintains a pyproject.toml file, and uses the `poetry` package
+(https://github.com/python-poetry/poetry) to manage its python-only dependencies
+in project-specific virtual environements.
 
-- Using `poetry`
-  https://github.com/python-poetry/poetry
+    cd geomag-algorithms
+    poetry install
+    poetry shell
 
-  > `pyenv` is also useful for installing specific/multiple versions of python
+  > `pyenv` is useful for installing specific/multiple versions of python
   >
   > - https://github.com/pyenv/pyenv
   > - https://github.com/pyenv-win/pyenv-win
 
-      poetry install
-      poetry shell
-
-- Or, using Miniconda/Anaconda
-  https://conda.io/miniconda.html
-
-      conda config --add channels conda-forge
-      conda create --name geomagenv obspy pycurl black pre-commit pytest pytest-cov webtest
-      conda activate geomagenv
 
+  > Miniconda/Anaconda is no longer supported, but it can be used to create
+  > development environments.
+  >
+  > - https://conda.io/miniconda.html
+  
 ## Coding Standards
 
-This project uses _The Black Code Style_
-https://black.readthedocs.io/en/stable/the_black_code_style.html
+This project follows _The Black Code Style_
+https://black.readthedocs.io/en/stable/the_black_code_style
 
 ## Developer Tools
 
 - **Code Formatting**
 
-  This project uses the `black` formatter, combined with `pre-commit`, to
-  automatically format code before it is committed.
+  To check formatting compliance, and assuming `poetry` was used as described
+  above, simply change to the project's top folder and type
 
-  VSCode ( https://code.visualstudio.com/ ), with the `Python` extension,
-  can be configured to automatically format using `black` when files are saved.
-  The `Formatting Toggle` extension is also useful.
+      poetry run poe lint
+  
+  > Also, if installed, the project works with `pre-commit`
+  > (https://pypi.org/project/pre-commit/)
+  > to reformat all code on git commits.
 
-  You can also manually format all files in the project by running
-
-      black .
+  > Finally, VSCode (https://code.visualstudio.com/), with the `Python` 
+  > extension, can automatically format using `black` when files are saved.
+  > The `Formatting Toggle` extension is also useful.
 
 - **Unit tests**
 
-  Run unit tests using PyTest
+  To run unit tests and generate coverage reports with `pytest`, simply change
+  to the project's top folder and type
+
+      poetry run poe test
 
-      pytest
+- **Vulnerabilities**
 
-- **Unit test coverage**
+  To check for package dependency vulnerabilities and updates useing `safety`,
+  simply change to the project's top folder and type
 
-      pytest --cov=geomagio
+      poetry run poe audit
 
 ## Routine Git Updates
 
@@ -92,5 +102,5 @@ https://black.readthedocs.io/en/stable/the_black_code_style.html
       git rebase master
 
   Resolve any rebase conflicts.
-  If you have already pushed this branch to your fork, you may need to force push
+  If you have already pushed this branch to your fork, you *may* need to force push
   because branch history has changed.
-- 
GitLab