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/

1. Fork this project on Github.

   https://github.com/usgs/geomag-algorithms.git

2. Clone your fork

   git clone https://github.com/{YOUR_GITHUB_ACCOUNT}/geomag-algorithms.git
   cd geomag-algorithms
   git remote add upstream https://github.com/usgs/geomag-algorithms.git
   

3. Use branches to develop new features and submit pull requests.

Install Dependencies

• Using poetry https://github.com/python-poetry/poetry

  pyenv is also 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
  

Coding Standards

This project uses The Black Code Style https://black.readthedocs.io/en/stable/the_black_code_style.html

Developer Tools

• Code Formatting

  This project uses the black formatter, combined with pre-commit, to automatically format code before it is committed.

  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.

  You can also manually format all files in the project by running

  black .
  

• Unit tests

  Run unit tests using PyTest

  pytest
  

• Unit test coverage

  pytest --cov=geomagio
  

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.