Update contributing guide and CI workflows (#162)

* update rtd to ubuntu latest

* misc maintenance

* fix paths

Author: sappelhoff

.github/CONTRIBUTING.md

@@ -1,135 +1,58 @@
-# Table of Contents
-
-- [Pull request workflow](#pull-request-workflow)
-  * [Syncing your fork's `main` with `upstream main`](#syncing-your-fork-s--main--with--upstream-main-)
-  * [Working on a feature (and rebasing)](#working-on-a-feature--and-rebasing-)
-    + [Working on a feature](#working-on-a-feature)
-    + [Rebasing without conflicts](#rebasing-without-conflicts)
-    + [Rebasing WITH conflicts](#rebasing-with-conflicts)
-    + [Rebasing ... panic mode (or "the easy way")](#rebasing--panic-mode--or--the-easy-way--)
-- [Info about docs](#info-about-docs)
-- [Info about versioning](#info-about-versioning)
-- [How to make a release](#how-to-make-a-release)
-
-# Pull request workflow
-
-- assuming you are working with `git` from a command line
-- assuming your GitHub username is `username`
-- `github.com/sappelhoff/pyprep` is `upstream`
-- `github.com/username/pyprep` is `origin` (your *fork*)
-
-## Syncing your fork's `main` with `upstream main`
-
-- first, you start with *forking* `upstream`
-- then, you continue by *cloning* your fork: `git clone https://github.com/username/pyprep`
-    - you'll have your own `main` branch there
-- **you always want to make sure that your fork's `main` and `upstream main` are aligned**
-    - to do this, you work with *git remotes*
-    - Note: this also means that you NEVER work on `main` (unless you know
-      what you are doing) ... because you want to always be able to SYNC your
-      fork with `upstream`, which would mean losing your own work on `main`
-- use `git remote -v` to list your configured remotes
-    - initially this will only list `origin` ... a bit like this maybe:
-
-```Text
-origin	https://github.com/username/pyprep (fetch)
-origin	https://github.com/username/pyprep (push)
-```
-
-- Now you want to add `upstream` as a remote. Use
-  `git remote add upstream https://github.com/sappelhoff/pyprep`
-- again, do `git remote -v`, it should look like this:
-
-```Text
-origin	https://github.com/username/pyprep (fetch)
-origin	https://github.com/username/pyprep (push)
-upstream	https://github.com/sappelhoff/pyprep (fetch)
-upstream	https://github.com/sappelhoff/pyprep (push)
-
-```
-
-- Now you can use your `upstream` *remote* to make sure your fork's `main` is
-  up to date.
-    1.  `git checkout main` to make sure you are on your `main` branch
-    1. Make sure you do not have any changes on your `main`, because we will
-       discard them!
-    1. `git pull upstream main` SYNC your fork and `upstream`
-    1. sometimes there are issues, so to be safe, do:
-       `git reset --hard upstream/main` ... this makes sure that both
-       branches are really synced.
-    1. ensure with another `git pull upstream main` ... this should say
-       "already up to date"
+# Contributions
 
-## Working on a feature (and rebasing)
+Contributions are welcome in the form of feedback and discussion in issues,
+or pull requests for changes to the code.
 
-### Working on a feature
+Once the implementation of a piece of functionality is considered to be free of
+bugs and properly documented, it can be incorporated into the `main` branch.
 
-- before working on any feature: always do `git checkout main` and
-  `git pull upstream main`
-- then make your new branch to work on and check it out, for example
-  `git checkout -b my_feature`
-    - do your work
-    - submit a pull request
-    - hope you are lucky and nobody did work in between
-- however IF somebody did work in between, we need to *rebase*. Just follow the
-  steps below
+To help developing `pyprep`,
+you will need a few adjustments to your installation as shown below.
 
-### Rebasing without conflicts
+## Install the development version
 
-1. sync `main` through: `git checkout main` and `git pull upstream main`
-1. go back to your branch and rebase it: `git checkout my_feature` and then
-   `git rebase main`
+First make a fork of the repository under your `USERNAME` GitHub account.
+Then, in your Python environment follow these steps:
 
-Now it could be that you are lucky and there no conflicts ... in that case, the
-rebase just works and you can then finish up by *force pushing* your rebased
-branch: `git push -f my_feature` ... you need to force it, because rebasing
-changed the history of your branch. But don't worry, if rebasing "just worked"
-without any conflicts, this should be very safe.
-
-### Rebasing WITH conflicts
+```Shell
+git clone https://github.com/USERNAME/pyprep
+cd pyprep
+git fetch --tags --prune --prune-tags
+python -m pip install -e ".[dev]"
+pre-commit install
+```
 
-In case you are unlucky, there are conflicts and you'll have to resolve them
-step by step ... `git` will be in *rebase* mode and try to rebase one commit
-after another ... for each commit where conflicts are detected, it'll stop.
+You may also clone the repository via ssh, depending on your preferred workflow
+(`git clone [email protected]:USERNAME/pyprep.git`).
 
-Then you have to do: `git status` to see conflicting files ... then edit these
-files to resolve conflicts ... then `git add <filename>` ... and then
-`git rebase --continue` to go on to the next commit, rinse and repeat.
+Note that we are working with "pre-commit hooks".
+See https://pre-commit.com/ for more information.
 
-**NOTE: the conflict resolution part is the dangerous part that can get very
-messy and where you can actually lose stuff ... so make backups of your branch
-before.**
+## Running tests and coverage
 
-After everything is resolved, you can again do `git push -f my_feature`.
+If you have followed the steps to get the development version,
+you can run tests as follows.
+From the project root, call:
 
-If you screw up **during** rebasing and you panic, you can do
-`git rebase --abort` and start again.
+- `pytest` to run tests and coverage
+- `pre-commit run -a` to run style checks (Ruff and some additional hooks)
 
-### Rebasing ... panic mode
+## Building the documentation
 
-If nothing helps and you just don't know how to resolve the issues and
-conflicts that arise during rebasing, just make a new branch:
-    1. `git checkout main`
-    1. `git pull upstream main`
-    1. `git checkout -b my_feature_2nd_attempt`
+The documentation can be built using [Sphinx](https://www.sphinx-doc.org).
 
-... and apply your changes manually.
+The publicly accessible documentation is built and hosted by
+[Read the Docs](https://readthedocs.org/).
+Credentials for Read the Docs are currently held by:
 
-This method is not really a `git` workflow, ... but in cases where there are
-only few changes, this is often a practical solution.
+- [@sappelhoff](https://github.com/sappelhoff/)
 
-# Info about versioning
+## Info about versioning
 
 We follow a [semantic versioning scheme](https://semver.org/).
 This is implemented via [hatch-vcs](https://github.com/ofek/hatch-vcs).
 
-# Info about docs
-
-The documentation is build and hosted by [https://readthedocs.org/](https://readthedocs.org/).
-
-Admin credentials are needed to access the setup.
-
-# How to make a release
+## Making a release on GitHub, PyPi, and Conda-Forge
 
 - needs admin rights
 - we are using [semver](https://semver.org/) (see section on versioning)

.github/dependabot.yml

@@ -5,9 +5,9 @@ updates:
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      interval: "monthly"
+      interval: "weekly"
 
   - package-ecosystem: "gitsubmodule"
     directory: "/"
     schedule:
-      interval: "monthly"
+      interval: "weekly"

.github/workflows/python_build.yml

@@ -1,5 +1,9 @@
 name: Python build
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
+  cancel-in-progress: true
+
 on:
   push:
     branches: [ main ]
@@ -25,7 +29,7 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
-    - name: Update pip et al.
+    - name: Update pip etc.
       run: |
         python -m pip install --upgrade pip
         python -m pip install --upgrade build twine
@@ -40,13 +44,13 @@ jobs:
     - name: Check sdist
       run: twine check --strict dist/*
     - name: Install sdist
-      run: pip install ./dist/pyprep-*
+      run: python -m pip install ./dist/pyprep-*
     - name: Clean up working directory
       run: rm -rf ./*
     - name: Try importing pyprep
       run: python -c 'import pyprep; print(pyprep.__version__)'
     - name: Remove sdist install
-      run: pip uninstall -y pyprep
+      run: python -m pip uninstall -y pyprep
 
     - uses: actions/checkout@v4
       with:
@@ -58,10 +62,10 @@ jobs:
     - name: Check wheel
       run: twine check --strict dist/*
     - name: Install wheel
-      run: pip install ./dist/pyprep-*.whl
+      run: python -m pip install ./dist/pyprep-*.whl
     - name: Clean up working directory
       run: rm -rf ./*
     - name: Try importing pyprep
       run: python -c 'import pyprep; print(pyprep.__version__)'
     - name: Remove wheel install
-      run: pip uninstall -y pyprep
+      run: python -m pip uninstall -y pyprep

.github/workflows/python_tests.yml

@@ -1,5 +1,9 @@
 name: Python tests
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.number }}-${{ github.event.ref }}
+  cancel-in-progress: true
+
 on:
   push:
     branches: [ main ]
@@ -49,21 +53,25 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -e ".[dev]"
+        python -m pip install -e ".[dev]"
 
     - name: Install MNE-Python (development version)
       if: matrix.mne-version == 'mne-main'
       run: |
-        pip install --upgrade https://github.com/mne-tools/mne-python/archive/refs/heads/main.zip
+        python -m pip install --upgrade https://github.com/mne-tools/mne-python/archive/refs/heads/main.zip
 
-    - name: Check installed versions
+    - name: Display versions and environment information
       run: |
+        echo $TZ
+        date
+        python --version
+        which python
         mne sys_info
 
     - name: Check formatting
       if: matrix.platform == 'ubuntu-latest'
       run: |
-        pre-commit run --all-files || ( git status --short ; git diff ; exit 1 )
+        pre-commit run --all-files
 
     - name: Test with pytest
       # Options defined in pyproject.toml
@@ -74,7 +82,7 @@ jobs:
         make -C docs/ clean
         make -C docs/ html
 
-    - name: Upload artifacts
+    - name: Upload docs build artifacts
       if: ${{ matrix.platform == 'ubuntu-latest' && matrix.mne-version == 'mne-stable' }}
       uses: actions/upload-artifact@v4
       with:

.github/workflows/release.yml

@@ -1,6 +1,6 @@
 # Upload a Python Package using Twine when a release is created
 
-name: build
+name: release
 on:  # yamllint disable-line rule:truthy
   release:
     types: [published]

.readthedocs.yml

@@ -1,23 +1,19 @@
-# .readthedocs.yml
-# Read the Docs configuration file
+# Read the Docs configuration file for Sphinx projects
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
-# Required
 version: 2
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-lts-latest
   tools:
     python: "3.12"
 
-# Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/conf.py
 
-# Optionally set the version of Python and requirements required to build your docs
 python:
   install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - docs
+  - method: pip
+    path: .
+    extra_requirements:
+      - docs

README.rst

@@ -12,8 +12,7 @@
 
 .. image:: https://codecov.io/gh/sappelhoff/pyprep/branch/main/graph/badge.svg
    :target: https://codecov.io/gh/sappelhoff/pyprep
-   :alt: codecov
-
+   :alt: Test coverage
 
 .. image:: https://readthedocs.org/projects/pyprep/badge/?version=latest
    :target: https://pyprep.readthedocs.io/en/latest/?badge=latest
@@ -49,57 +48,42 @@ for EEG data, working with `MNE-Python <https://mne.tools>`_.
 Installation
 ============
 
-``pyprep`` requires Python version ``3.9`` or higher to run properly.
+``pyprep`` runs on Python version 3.9 or higher.
+
 We recommend to run ``pyprep`` in a dedicated virtual environment
 (for example using `conda <https://docs.conda.io/en/latest/miniconda.html>`_).
 
 For installing the **stable** version of ``pyprep``, call:
 
 .. code-block:: Text
 
-   pip install pyprep
+   python -m pip install --upgrade pyprep
 
-or, as an alternative to ``pip``, call:
+or if you use `conda <https://docs.conda.io/en/latest/miniconda.html>`_:
 
 .. code-block:: Text
 
-   conda install -c conda-forge pyprep
+   conda install --channel conda-forge pyprep
 
 For installing the **latest (development)** version of ``pyprep``, call:
 
 .. code-block:: Text
 
-   pip install --upgrade https://github.com/sappelhoff/pyprep/archive/refs/heads/main.zip
+   python -m pip install --upgrade https://github.com/sappelhoff/pyprep/archive/refs/heads/main.zip
 
 Both the *stable* and the *latest* installation will additionally install
 all required dependencies automatically.
 The dependencies are defined in the ``pyproject.toml`` file under the
 ``dependencies`` and ``project.optional-dependencies`` sections.
 
-Contributions
-=============
-
-**We are actively looking for contributors!**
-
-Please chime in with your ideas on how to improve this software by opening
-a GitHub issue, or submitting a pull request.
-
-See also our `CONTRIBUTING.md <https://github.com/sappelhoff/pyprep/blob/main/.github/CONTRIBUTING.md>`_
-file for help with submitting a pull request.
-
-Potential contributors should install ``pyprep`` in the following way:
-
-#. First they should fork ``pyprep`` to their own GitHub account.
-#. Then they should run the following commands,
-   adequately replacing ``<gh-username>`` with their GitHub username.
+Contributing
+============
 
-.. code-block:: Text
+The development of ``pyprep`` is taking place on
+`GitHub <https://github.com/sappelhoff/pyprep>`_.
 
-   git clone https://github.com/<gh-username>/pyprep
-   cd pyprep
-   git fetch --tags --prune --prune-tags
-   pip install -e ".[dev]"
-   pre-commit install
+For more information, please see
+`CONTRIBUTING.md <https://github.com/sappelhoff/pyprep/blob/main/.github/CONTRIBUTING.md>`_.
 
 Citing
 ======