Merge pull request #80 from predict-idlab/maintenance

🧹 some necessary maintenance

.github/workflows/lint.yml

@@ -0,0 +1,34 @@
+name: Lint
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        lfs: true
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v2
+      with:
+        python-version: '3.10'
+    - name: Install Poetry
+      uses: snok/install-poetry@v1
+    - name: Cache poetry
+      id: cached-poetry-dependencies
+      uses: actions/cache@v2
+      with:
+        path: ~/.cache/pypoetry/virtualenvs
+        key: ${{ runner.os }}-poetry-${{ hashFiles('poetry.lock') }}-python-${{ matrix.python-version }}
+    - run: poetry --version
+    - name: Install dependencies
+      run: poetry install
+      # Do not use caching (anymore)
+#      if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+    - name: Lint
+      run: make lint

.github/workflows/test.yml

@@ -40,12 +40,6 @@ jobs:
       # Do not use caching (anymore)
 #      if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
 
-#     - name: Lint with flake8
-#       run: |
-#         # stop the build if there are Python syntax errors or undefined names
-#         flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-#         # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-#         flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
     - name: Test with pytest
       run: |
         poetry run pytest --cov=tsflex --junitxml=junit/test-results-${{ matrix.python-version }}.xml --cov-report=xml tests

CONTRIBUTING.md

@@ -1,127 +1,105 @@
-# How to contribute
+# Contributing to `tsflex`
 
 First of all, thank you for considering contributing to `tsflex`.<br>
-It's people like you that will help make `tsflex` a great toolkit.
+It's people like you that will help make `tsflex` a great toolkit! 🤝
 
-As usual, contributions are managed through GitHub Issues and Pull Requests.
+As usual, contributions are managed through GitHub Issues and Pull Requests.  
+We invite you to use GitHub's [Issues](https://github.com/predict-idlab/tsflex/issues) to report bugs, request features, or ask questions about the project. To ask use-specific questions, please use the [Discussions](https://github.com/predict-idlab/tsflex/discussions) instead.
 
-We are welcoming contributions in the following forms:
-* **Bug reports**: when filing an issue to report a bug, please use the search tool to ensure the bug hasn't been reported yet;
-* **New feature suggestions**: if you think `tsflex` should include a new , please open an issue to ask for it (of course, you should always check that the feature has not been asked for yet :). Think about linking to a pdf version of the paper that first proposed the method when suggesting a new algorithm. 
-* **Bugfixes and new feature implementations**: if you feel you can fix a reported bug/implement a suggested feature yourself, do not hesitate to:
-  1. fork the project;
-  2. implement your bugfix;
-  3. submit a pull request referencing the ID of the issue in which the bug was reported / the feature was suggested;
-
-When submitting code, please think about code quality, adding proper docstrings including doctests with high code coverage.
+If you are new to GitHub, you can read more about how to contribute [here](https://docs.github.com/en/get-started/quickstart/contributing-to-projects).
 
-## More details on Pull requests
+## How to develop locally
 
-The preferred workflow for contributing to tsflex is to fork the
-[main repository](https://github.com/predict-idlab/tsflex) on
-GitHub, clone, and develop on a branch. Steps:
+*Note: this guide is tailored to developers using linux*
 
-1. Fork the [project repository](https://github.com/predict-idlab/tsflex)
-   by clicking on the 'Fork' button near the top right of the page. This creates
-   a copy of the code under your GitHub user account. For more details on
-   how to fork a repository see [this guide](https://help.github.com/articles/fork-a-repo/).
+The following steps assume that your console is at the root folder of this repository.
 
-2. Clone your fork of the tsflex repo from your GitHub account to your local disk:
+### Create a new (poetry) Python environment
 
-   ```bash
-   $ git clone [email protected]:YourLogin/tsflex.git
-   $ cd tsflex
-   ```
+It is best practice to use a new Python environment when starting on a new project.
 
-3. Create a ``feature`` branch to hold your development changes:
+We describe two options; 
 
-   ```bash
-   $ git checkout -b my-feature
-   ```
+<details>
+<summary><i>Advised option</i>: using <code>poetry shell</code></summary>
+For dependency management we use poetry (read more below).<br>
+Hence, we advise to use poetry shell to create a Python environment for this project.
 
-   Always use a ``feature`` branch. It's good practice to never work on the ``master`` branch!
+1. Install poetry: https://python-poetry.org/docs/#installation <br>
+   (If necessary add poetry to the PATH)
+2. Create & activate a new python environment: <code>poetry shell</code>
 
-4. Develop the feature on your feature branch. Add changed files using ``git add`` and then ``git commit`` files:
+After the poetry shell command your python environment is activated.
+</details>
 
-   ```bash
-   $ git add modified_files
-   $ git commit
-   ```
+<details>
+<summary><i>Alternative option</i>: using <code>python-venv</code></summary>
+As alternative option, you can create a Python environment by using python-venv
 
-   to record your changes in Git, then push the changes to your GitHub account with:
+1. Create a new Python environment: <code>python -m venv venv</code>
+2. Activate this environment; <code>source venv/bin/activate</code>
+</details>
 
-   ```bash
-   $ git push -u origin my-feature
-   ```
+Make sure that this environment is activated when developing (e.g., installing dependencies, running tests).
 
-5. Follow [these instructions](https://help.github.com/articles/creating-a-pull-request-from-a-fork)
-to create a pull request from your fork. This will send an email to the committers.
+### Installing & building the dependencies
 
-(If any of the above seems like magic to you, please look up the
-[Git documentation](https://git-scm.com/documentation) on the web, or ask a friend or another contributor for help.)
+We use [`poetry`](https://python-poetry.org/) as dependency manager for this project. 
+- The dependencies for installation & development are written in the [`pyproject.toml`](pyproject.toml) file (which is quite similar to a requirements.txt file). 
+- To ensure that package versions are consistent with everyone who works on this project poetry uses a [`poetry.lock`](poetry.lock) file (read more [here](https://python-poetry.org/docs/basic-usage/#installing-with-poetrylock)).
 
-### Pull Request Checklist
+To install the requirements
+```sh
+pip install poetry  # install poetry (if you do use the venv option)
+poetry install      # install all the dependencies
+poetry build        # build the underlying C code
+```
+
+### Formatting the code
 
-We recommended that your contribution complies with the
-following rules before you submit a pull request:
+We use [`black`](https://github.com/psf/black) and [`isort`](https://github.com/PyCQA/isort) to format the code.
+
+To format the code, run the following command (more details in the [`Makefile`](Makefile)):
+```sh
+make format
+```
 
--  Follow the PEP8 Guidelines.
+### Checking the linting
 
--  If your pull request addresses an issue, please use the pull request title
-   to describe the issue and mention the issue number in the pull request description. 
-   This will make sure a link back to the original issue is created.
+We use [`ruff`](https://github.com/charliermarsh/ruff) to check the linting.
 
--  All public methods should have informative *numpy* docstrings with sample
-   usage presented as doctests when appropriate. Validate whether the generated 
-   documentation is properly formatted (see below). 
+To check the linting, run the following command (more details in the [`Makefile`](Makefile)):
+```sh
+make lint
+```
 
--  Please prefix the title of your pull request with `[MRG]` (Ready for
-   Merge), if the contribution is complete and ready for a detailed review.
-   An incomplete contribution -- where you expect to do more work before
-   receiving a full review -- should be prefixed `[WIP]` (to indicate a work
-   in progress) and changed to `[MRG]` when it matures. WIPs may be useful
-   to: indicate you are working on something to avoid duplicated work,
-   request broad review of functionality or API, or seek collaborators.
-   WIPs often benefit from the inclusion of a
-   [task list](https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments)
-   in the PR description.
+### Running the tests (& code coverage)
 
--  When adding additional functionality, provide at least one
-   example notebook in the ``tsflex/examples/`` folder or add the functionality in an 
-   existing noteboo. Have a look at other examples for reference. 
-   Examples should demonstrate why the new functionality is useful in practice and, 
-   if possible, benchmark/integrate with other packages.
+You can run the tests with the following code (more details in the [`Makefile`](Makefile)):
 
--  Documentation and high-coverage tests are necessary for enhancements to be
-   accepted. Bug-fixes or new features should be provided with 
-   [non-regression tests](https://en.wikipedia.org/wiki/Non-regression_testing).
-   These tests verify the correct behavior of the fix or feature. In this
-   manner, further modifications on the code base are granted to be consistent
-   with the desired behavior.
-   For the Bug-fixes case, at the time of the PR, this tests should fail for
-   the code base in master and pass for the PR code.
+```sh
+make test
+```
 
-You can also check for common programming errors with the following
-tools:
+## Documentation
 
-- Check whether the hosted-documentation will look fine:
+We use [`pdoc`](https://pdoc3.github.io/pdoc/) to generate the documentation.
 
+To generate the documentation and view it locally, run the following command:
 ```bash
 $ pdoc3 --template-dir docs/pdoc_template/ --http :8181 tsflex/
 # you will be able to see the documentation locally on localhost:8181
 ```
 
-- Validate tests & Code coverage:
+---
 
-```bash
- $ pytest tests --cov-report term-missing --cov=tsflex tests
-```
+## Bonus points
 
-Bonus points for contributions that include a performance analysis with
-a benchmark script and profiling output (please report on the mailing
-list or on the GitHub issue).
+Bonus points for contributions that include a performance analysis with a benchmark script and profiling output 👀
 
-our favored profiling tool is [VizTracer](https://github.com/gaogaotiantian/viztracer)
+<details>
+<summary><i>Details on how we profiled <code>tsflex</code></i> </summary>
+Our favored profiling tool is <a href="https://github.com/gaogaotiantian/viztracer"><code>VizTracer</code></a> 
 which can be used as:
 
 ```python
@@ -138,3 +116,4 @@ with VizTracer(
     # the code that is improved in either memory usage / speed
     ...
 ```
+</details>

Makefile

@@ -0,0 +1,26 @@
+black = black tsflex tests
+isort = isort tsflex tests
+
+.PHONY: format
+format:
+	$(isort)
+	$(black)
+
+.PHONY: lint
+lint:
+	poetry run ruff tsflex tests
+	poetry run $(isort) --check-only --df
+	poetry run $(black) --check --diff
+
+.PHONY: test
+test:
+	poetry run pytest --cov-report term-missing --cov=tsflex tests
+
+.PHONY: clean
+clean:
+	rm -rf `find . -name __pycache__`
+	rm -rf .cache
+	rm -rf .pytest_cache
+	rm -rf *.egg-info
+	rm -rf .ruff_cache
+	rm -f .coverage

README.md

@@ -4,7 +4,6 @@
 [![Conda Latest Release](https://img.shields.io/conda/vn/conda-forge/tsflex?label=conda)](https://anaconda.org/conda-forge/tsflex)
 [![support-version](https://img.shields.io/pypi/pyversions/tsflex)](https://img.shields.io/pypi/pyversions/tsflex)
 [![codecov](https://img.shields.io/codecov/c/github/predict-idlab/tsflex?logo=codecov)](https://codecov.io/gh/predict-idlab/tsflex)
-[![Code quality](https://img.shields.io/lgtm/grade/python/github/predict-idlab/tsflex?label=code%20quality&logo=lgtm)](https://lgtm.com/projects/g/predict-idlab/tsflex/context:python)
 [![Downloads](https://pepy.tech/badge/tsflex)](https://pepy.tech/project/tsflex)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?)](http://makeapullrequest.com)
 [![Documentation](https://github.com/predict-idlab/tsflex/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/predict-idlab/tsflex/actions/workflows/deploy-docs.yml)