Contributing

Report bugs and submit feedback at https://github.com/malmans2/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/malmans2/oceanspy.git
    
  4. Make a new branch from upstream/master:

    $ 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/master
    
  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

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

  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 (substituting pyxx with one of the available python versions):

    $ conda config --set channel_priority strict
    $ conda config --prepend channels conda-forge
    $ conda env create -f ci/environment-pyxx.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 PEP 8 style guide using the following command:

$ pycodestyle oceanspy

Deploying

A reminder for the maintainers on how to deploy.

  1. Download and install bump2version

    $ pip install --upgrade bump2version
    
  2. Update HISTORY.rst

  3. Use git to add and commit changes

  4. Update version number

    $ bump2version patch # possible: major / minor / patch
    
  5. Release on PyPI by uploading both sdist and wheel:

    $ python setup.py sdist upload
    $ python setup.py bdist_wheel upload
    
  6. Use git to push

  7. Push tags

    $ git push --tags
    
  8. Add the release’s notes on the releases’ page (copy and paste from HISTORY.rst)