Contributing

Report bugs and submit feedback at https://github.com/hainegroup/oceanspy/issues.
Don’t forget to add yourself to the list of People contributing to OceanSpy!

Using Git and GitHub

Git is the distributed version control system used to develop OceanSpy, while GitHub is the website hosting the oceanspy/ repository.

Go to GitHub:

  1. If you don’t have an account yet, Sign up. Otherwise, Sign in.

  2. Go to the OceanSpy GitHub repository, then fork the project using the fork button.

Move to your terminal:

  1. Set your GitHub username and email address using the following commands:

    $ git config --global user.email "you@example.com"
    $ git config --global user.name "Your Name"
    
  2. Create a local clone:

    $ git clone https://github.com/your_username_here/oceanspy.git
    
  3. Move into your local clone directory, then set up a remote that points to the original:

    $ cd oceanspy
    $ git remote add upstream https://github.com/hainegroup/oceanspy.git
    
  4. Make a new branch from upstream/main:

    $ git fetch upstream
    $ git checkout -b name_of_your_new_branch
    
  5. Make sure that your new branch is up-to-date:

    $ git merge upstream/main
    
  6. Edit and/or add new files:

  7. To stage files ready for a commit, use the following command:

    $ git add .
    
  8. To save changes, use the following command:

$ git commit -m "Message describing your edits"

You can repeat git add and git commit multiple times before pushing the branch online.

  1. To push the branch online, use the following command:

$ git push -u origin name_of_your_branch
  1. Go to your OceanSpy fork on GitHub (https://github.com/your_username_here/oceanspy) and click on Compare and Pull.

  2. Finally, click on Send pull request button to finish creating the pull request.

Contributing to the Documentation

Documentation link: Documentation

The documentation is built with Sphinx and hosted by Read the Docs. It is written in reStructuredText.

  1. First, you need a local clone of oceanspy and a branch (follow the instruction in Using Git and GitHub).

  2. Move into the directory containing the documentation:

    $ cd oceanspy/docs
    
  3. In order to build the documentation, you need to create a Conda environment:

    $ conda config --set channel_priority strict
    $ conda config --prepend channels conda-forge
    $ conda env create -f environment.yml
    
  4. Activate the ospy_docs environment:

    $ conda activate ospy_docs
    
  1. Edit and/or add new files.

  2. To build the documentation, use the following command:

    $ make html
    

    If you want to start from a clean build, run make clean before make html.

  3. You can find the HTML output in oceanspy/docs/_build/html.

  4. Use git to add, commit, and push as explained in Using Git and GitHub.

Contributing to the Code

Continuous Integration and Test Coverage links: CI Coverage

  1. First, you need a local clone of oceanspy and a branch (follow the instructions in Using Git and GitHub).

  2. If you are not already into your local clone directory, move there:

    $ cd oceanspy
    
  3. Create a test environment:

    $ conda config --set channel_priority strict
    $ conda config --prepend channels conda-forge
    $ conda env create -f ci/environment.yml
    
  4. Activate the test environment:

    $ conda activate ospy_tests
    
  5. Install OceanSpy in development mode:

    $ pip install -e .
    
  6. Edit and/or add new files.

  7. Use git to add, commit, and push as explained in Using Git and GitHub.

  8. Make sure that the code is well tested by adding or improving tests in the oceanspy/tests repository. The python package used to test OceanSpy is pytest. Use the following command to run the test and measure the code coverage:

    $ py.test oceanspy -v --cov=oceanspy --cov-config .coveragerc --cov-report term-missing
    
  9. You can install and use pytest-html to produce a test report in html format.

  10. Make sure that the code follows the style guide using the following commands:

$ conda install -c conda-forge pre-commit
$ pre-commit run --all

Note

Run the following command to automatically run black and flake8 each time git commit is used:

$ pre-commit install

Deploying

PyPI conda-forge

  1. Update HISTORY.rst

  2. Issue a new release on GitHub

  3. The release on PyPI is done automatically

  4. Merge the oceanspy-feedstock PR automatically opened by conda-forge