develop.md

# Development Dependencies

These instructions only need to be completed if you plan on developing new
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/).
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.

    https://code.usgs.gov/ghsc/geomag/geomag-algorithms.git

2.  Clone your fork

        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.

    cd geomag-algorithms
    poetry install
    poetry run command-in-env

 ...or...

    cd geomag-algorithms
    poetry install
    poetry shell
    (shell-inside-env) > command-in-env

  > `pyenv` is useful for installing specific/multiple versions of python
  >
  > - https://github.com/pyenv/pyenv
  > - https://github.com/pyenv-win/pyenv-win


  > Miniconda/Anaconda is no longer supported, but it can be used to create
  > development environments.
  >
  > - https://conda.io/miniconda.html
  
## Coding Standards

This project follows _The Black Code Style_
https://black.readthedocs.io/en/stable/the_black_code_style

## Developer Tools

- **Code Formatting**

  To check formatting compliance, and assuming `poetry` was used as described
  above, simply change to the project's top folder and type

      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.

  > 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**

  To run unit tests and generate coverage reports with `pytest`, simply change
  to the project's top folder and type

      poetry run poe test

- **Vulnerabilities**

  To check for package dependency vulnerabilities and updates useing `safety`,
  simply change to the project's top folder and type

      poetry run poe audit

## Routine Git Updates

- **Pulling new changes**

  When starting a new branch, or before putting in a pull request, make sure
  you have the latest changes from the `upstream` repository.

  > The local master branch should only be used for synchonization with the
  > `upstream` repository, and we recommend always using the `--ff-only` option.

      git checkout master
      git pull --ff-only upstream master

- **Rebase an existing branch**

  After downloading updates into the master branch, feature branches need to be
  rebased so they include any already merged changes.

      git checkout FEATURE-BRANCH
      git rebase master

  Resolve any rebase conflicts.
  If you have already pushed this branch to your fork, you *may* need to force push
  because branch history has changed.