CONTRIBUTING.rst

Contributing

Report bugs and submit feedback at https://github.com/hainegroup/oceanspy/issues.

Don't forget to add yourself to the list of :ref:`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:

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

   $ git config --global user.email "[email protected]"
   $ git config --global user.name "Your Name"

4. Create a local clone:

   $ git clone https://github.com/your_username_here/oceanspy.git

5. 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

6. Make a new branch from upstream/main:

   $ git fetch upstream
   $ git checkout -b name_of_your_new_branch

7. Make sure that your new branch is up-to-date:

   $ git merge upstream/main

8. Edit and/or add new files:

   • :ref:`documentation`
   • :ref:`code`

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

   $ git add .

10. 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.

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

$ git push -u origin name_of_your_branch

12. Go to your OceanSpy fork on GitHub (https://github.com/your_username_here/oceanspy) and click on Compare and Pull.
13. Finally, click on Send pull request button to finish creating the pull request.

Contributing to the Documentation

Documentation link:

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 :ref:`using_git`).

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

4. Edit and/or add new files.

5. 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.

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

7. Use git to add, commit, and push as explained in :ref:`using_git`.

Contributing to the Code

Continuous Integration and Test Coverage links:

1. First, you need a local clone of oceanspy and a branch (follow the instructions in :ref:`using_git`).

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 :ref:`using_git`.

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

Python Package Index (PyPI) link:

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)