Going further

Installation with github and poetry

Note

We have made a tutorial on Github if you are starting with it

In this section we give you the instructions to install our toolkit from github using the poetry tool:

  1. First clone our Github project repository

git clone https://github.com/Project-OSmOSE/osmose-toolkit.git

  1. Create and activate a Conda virtual environment in python 3.10 with the name you want (here osmose_dev)

conda create --name osmose_dev python=3.10 -y
conda activate osmose_dev

  1. Install poetry and use it to install our toolkit

conda install poetry
poetry install

Note

poetry install will use the file pyproject.toml so be sure to execute this command from its directory. Besides, if poetry install fails with the message ImportError: cannot import name 'PyProjectException', run this line instead:

conda install -c conda-forge poetry==1.3.2

The toolkit is now installed in editable mode! You can call it just like any regular python package as long as you are in its conda environment

import OSmOSE as osm
dataset = osm.Dataset()

Note that on the contrary of the installation procedure given in Getting started, the OSmOSE toolkit is now installed in editable mode, meaning that any change made to the package’s file will be reflected immediately on the environment, without needing to reload it.

Contribute

Here is the general workflow for contributing to our project:

  1. Install our toolkit in local following instructions in Installation with github and poetry ;

  2. To be able to push/pull codes to/from github, add remote to your origin folder

git remote add origin git@github.com:Project-OSmOSE/osmose-toolkit.git

  1. Review our Github issues : find an open issue to tackle and /or ask if you can help write a new feature (follow standard procedures such as: short description, assignees, status, label…) ;

  2. Develop and validate your contribution in local using a branch checkout from our main branch and dedicated to your issue. As is often the case, no pushes are accepted on our main branch. Note that after creating your issue, under Development in the right panel, you can directly “Create a branch for this issue or link a pull request.” that willl provide you a command of the form

git fetch origin
git checkout 112-create-a-double-fs-spectrogram-concatenated-horizontally

  1. (Optional) If intended to be deployed on Datarmor, you will have to also validate your contribution on it (see section On Datarmor for details) ;

  2. You can suggest changing in the version of the toolkit through the parameter version in pyproject.toml, depending on the importance of the changes:

    • small patch : change patch version (x.x.X)

    • non breaking changes : change minor version (x.X.x)

    • breaking changes : change major version (X.x.x)

  3. Do not forget to format your codes with the Black package as follows (otherwise your contribution will fail its integration on Github anyway) :

poetry run black .

  1. Similarly, it is better you run locally the OSEkit pytest suite prior to push your contribution (otherwise your contribution will fail its integration on Github anyway) :

pytest tests/

To execute a specific test run the following line (the -s allows you to see print output in console):

pytest -s tests/test_spectrogram.py::test_number_image_matrix

  1. Push your branch to our Github project and create a pull-request so it can be properly peer-reviewed ;

  2. Once your PR merged, use poetry build and upload generated files (present locally in the folder /dist) in the corresponding package version on github here

Note

Beyond this workflow, you can find in this guide a more exhaustive list of possible contributions for an open source project, do not hesite to make us original propositions. This document provides a more detailed step-by-step guide on how to make contributinons on github, and this one is a guideline of best practices on github.