diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..2f8deb1 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,49 @@ +# Workflow template from https://github.com/tox-dev/tox-gh +name: Formatting, Linting and Testing +on: + push: + branches: main + pull_request: + branches: main + +concurrency: + group: check-${{ github.ref }} + cancel-in-progress: true + +jobs: + test: + name: test with ${{ matrix.py }} on ${{ matrix.os }} + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + py: + - "3.12" + - "3.11" + - "3.10" + - "3.9" + - "3.8" + os: + - ubuntu-latest + - macos-latest + - windows-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup python for test ${{ matrix.py }} + uses: actions/setup-python@v4 + with: + python-version: ${{ matrix.py }} + + - name: Install tox + run: python -m pip install tox-gh>=1.2 + + - name: Setup test suite + run: tox --notest + + - name: Run test suite + env: + TOKEN: ${{ secrets.TOKEN }} + run: tox --skip-pkg-install diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4d4df25 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,115 @@ +# Contributing + +All contributions are welcome and appreciated! Credits will be given in the changelog file. + +## Types of Contributions + +### Report Bugs + +Bugs can come from Oceans 3.0 API (backend) or the onc library. When reporting an issue, please include some descriptions (code snippet, expected behavior, actual behavior, etc.) to help us reproduce the bug. + +Bugs from the backend can also be reported at [Oceans 3.0 Data Portal](https://data.oceannetworks.ca/DataPreview) from the request support form located in the top-right corner. + +### Fix Bugs / Implement Features + +These are issues labeled with "bug" / "enhancement". Any issue that has no assignee is open to whoever wants to implement it. + +### Write Documentation + +Documentations are important for users to understand the library. You are welcome to raise an issue if you find something that is outdated or can be improved. + +For docstring, [numpy style](https://numpydoc.readthedocs.io/en/latest/format.html) is used. + +### Commit + +We use [conventional commits](https://www.conventionalcommits.org/) for commit messages. Most of the time it is as simple as adding a type before the message. + +The general format is as follows: + +```text +[optional scope]: short description + +[optional body: long description] + +[optional footer] +``` + +Types can be _fix, feat (short for feature), refactor, style, docs, test, etc_. Some examples are: + +```text +feat: allow users to cancel a running data product + +test: add tests for cancelling a running data product + +docs: add docstrings for discovery methods +``` + +Check [py-pkgs open source book](https://py-pkgs.org/07-releasing-versioning#automatic-version-bumping) for an introduction. + +--- + +## Set up a development environment + +Here is a setup for the local development. + +### Creating a virtual environment + +Make sure the python version meets the minimum version requirement defined in pyproject.toml. This step can be simplified if you are using [VS Code](https://code.visualstudio.com/docs/python/environments) or [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html#python_create_virtual_env). + +```shell +# Create a virtual environment +$ python -m venv .venv + +# Activate the venv +$ source .venv/bin/activate +# For Windows, use .venv\Scripts\activate.ps1 for powershell or .venv\Scripts\activate.bat for cmd.exe + +# Install onc library in editable mode +$ pip install -e . + +# Install dependencies (TODO: Change it to use pyproject optional dependencies) +$ pip install -r requirements-dev.txt +``` + +### Running the test + +See README.md in the tests folder. + +Or use tox + +```shell +$ tox -e py310 # py38, py39, py311, py312. Make sure the specified python version is installed. +``` + +### Formatter + +Code is formatted using [black](https://black.readthedocs.io/en/stable/) and [isort](https://pycqa.github.io/isort/). + +```shell +$ black onc tests +$ isort onc tests +``` + +Or use tox + +```shell +$ tox -e format +``` + +### Linter + +[Ruff](https://docs.astral.sh/ruff/) is used for linting. + +```shell +$ ruff check onc +``` + +Or use tox + +```shell +$ tox -e lint +``` + +## Set up a development environment for documentation + +WIP. diff --git a/pyproject.toml b/pyproject.toml index 8836578..f5723b9 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -33,7 +33,6 @@ Source = "https://github.com/OceanNetworksCanada/api-python-client" [tool.isort] profile = "black" -src_paths = ["onc", "tests"] [tool.ruff] # Reference for the rules https://docs.astral.sh/ruff/rules/ diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..5dca57c --- /dev/null +++ b/tox.ini @@ -0,0 +1,49 @@ +[tox] +min_version = 4.0 +env_list = + py{38,39,310,311,312} + format-check + lint +isolated_build = True + +[testenv] +description = run unit tests +deps = + robotframework + python-dotenv +passenv = TOKEN +commands = + robot tests/suites + +[testenv:format] +description = run black and isort +skip_install = true +deps = + black + isort +commands = black src tests + isort src tests + +[testenv:format-check] +description = run black and isort check +skip_install = true +deps = + black + isort +commands = black --check --diff src tests + isort --check --diff src tests + +[testenv:lint] +description = run ruff +skip_install = true +deps = + ruff +commands = ruff check {posargs:src} + +[gh] +python = + 3.8 = py38 + 3.9 = py39 + 3.10 = py310, format-check, lint + 3.11 = py311 + 3.12 = py312