misc maintenance

.github/CONTRIBUTING.md

@@ -20,7 +20,8 @@ Then, in your Python environment follow these steps:
 ```Shell
 git clone https://github.com/USERNAME/pybv
 cd pybv
-pip install -e ".[dev]"
+git fetch --tags --prune --prune-tags
+python -m pip install -e ".[dev]"
 pre-commit install
 ```
 
@@ -56,6 +57,9 @@ Credentials for Read the Docs are currently held by:
 - [@sappelhoff](https://github.com/sappelhoff/)
 - [@choldgraf](https://github.com/choldgraf/)
 
+## Info about versioning
+
+We follow a [semantic versioning scheme](https://semver.org/).
 
 ## Making a release on GitHub, PyPi, and Conda-Forge
 
@@ -67,64 +71,48 @@ and [Conda-Forge](https://anaconda.org/conda-forge/pybv).
 Credentials are currently held by:
 
 - GitHub
-    - Admin
-      - any admin of the [bids-standard GitHub organization](https://github.com/bids-standard)
-      - [@sappelhoff](https://github.com/sappelhoff/)
-      - [@choldgraf](https://github.com/choldgraf/)
-      - [@cbrnr](https://github.com/cbrnr/)
-    - Write
-      - [@hoechenberger](https://github.com/hoechenberger/)
+  - Admin
+    - any admin of the [bids-standard GitHub organization](https://github.com/bids-standard)
+    - [@sappelhoff](https://github.com/sappelhoff/)
+    - [@choldgraf](https://github.com/choldgraf/)
+    - [@cbrnr](https://github.com/cbrnr/)
+  - Write
+    - [@hoechenberger](https://github.com/hoechenberger/)
 - PyPi
-    - Owner
-        - [@sappelhoff](https://github.com/sappelhoff/)
-        - [@choldgraf](https://github.com/choldgraf/)
-    - Maintainer
-        - [@cbrnr](https://github.com/cbrnr/)
+  - Owner
+    - [@sappelhoff](https://github.com/sappelhoff/)
+    - [@choldgraf](https://github.com/choldgraf/)
+  - Maintainer
+    - [@cbrnr](https://github.com/cbrnr/)
 - Conda-Forge
-    - see: https://github.com/conda-forge/pybv-feedstock#feedstock-maintainers
+  - see: https://github.com/conda-forge/pybv-feedstock#feedstock-maintainers
 
 Releasing on GitHub will automatically trigger a release on PyPi via a GitHub Action
-(The credentials for PyPi are stored as "GitHub Secrets").
+(see `.github/workflows/release.yml`).
 A release on PyPi in turn will automatically trigger a release on Conda-Forge.
-Thus, the release protocol can be briefly described as follows:
+The release protocol can be briefly described as follows:
 
-1. You will need admin rights for the `pybv` GitHub repository.
-1. Go to your Python environment for `pybv`.
+1. Activate your Python environment for `pybv`.
 1. Make sure all tests pass and the docs are built cleanly.
-1. Update the `__version__` variable in `__init__.py`:
-    - Remove the `.devN` suffix.
-    - If the version preceding the `.devN` suffix is not the version to be
-      released, update the version as well according to
-      [semantic versioning](https://semver.org/) with its `major.minor.patch`
-      style.
 1. If applicable, append new authors to the author metadata in the `CITATION.cff` file.
-1. Update `docs/changelog.rst`, renaming the "current" headline to the new
-   version and (if applicable) extending the "Authors" section of the document.
-    - "Authors" are all people who committed code or in other ways contributed
-      to `pybv` (e.g., by extensively reviewing PRs).
-1. Commit the change and git push to `main` (or make a pull request and merge it).
+1. Update `docs/changes.rst`, renaming the "current" headline to the new
+   version
+1. Commit the change and git push to upstream `main`.
    Include "REL" in your commit message.
-1. Then, make an annotated tag `git tag -a -m "v1.2.3" v1.2.3 upstream/main` (This
-   assumes that you have a git remote configured with the name "upstream" and
-   pointing to https://github.com/bids-standard/pybv). Note also that the
-   version from `__init__.py` is preprended with a `v`: `1.2.3` --> `v1.2.3`
+1. Then, make an annotated tag, for example for the version `1.2.3`:
+   `git tag -a -m "1.2.3" 1.2.3 upstream/main`
+   (This assumes that you have a git remote configured with the name "upstream" and
+   pointing to https://github.com/bids-standard/pybv).
    **NOTE: Make sure you have your `main` branch up to date for this step!**
 1. `git push --follow-tags upstream`
 1. Make a [release on GitHub](https://help.github.com/en/articles/creating-releases),
-   using the git tag from the previous step (e.g., `v1.2.3`).
+   using the git tag from the previous step (e.g., `1.2.3`).
    Fill the tag name into the "Release title" field, and fill the "Description" field
    as you see fit.
 1. This will trigger a GitHub Action that will build the package and release it to PyPi.
-1. The PyPi release will trigger a release on Conda-Forge.
 
 Then the release is done and `main` has to be prepared for development of
 the next release:
 
-1. Update the `__version__` variable in `__init__.py`:
-    - Bump up the `major.minor.patch` version according to
-      [semantic versioning](https://semver.org/) so that the version will be
-      the version that is planned to be released next (e.g., `1.3.0`).
-    - Append `.dev0` to the version (e.g., `1.3.0.dev0`).
-        - (if you had a version like `1.3.0.dev0` before, release `1.3.0.dev1` instead, etc.)
-1. Add a "Current (unreleased)" headline to `docs/changelog.rst`.
+1. Add a "Current (unreleased)" headline to `docs/changes.rst`.
 1. Commit the changes and git push to `main` (or make a pull request).

.github/workflows/python_build.yml

@@ -6,11 +6,11 @@ concurrency:
 
 on:
   push:
-    branches: [main]
+    branches: [ main ]
   pull_request:
-    branches: [main]
+    branches: [ main ]
   schedule:
-    - cron: "0 4 1 * *"
+    - cron: "0 4 * * MON"
 
 jobs:
   build:
@@ -19,38 +19,51 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: ["3.10", "3.11", "3.12"]
+        python-version: ["3.12"]
+    env:
+      TZ: Europe/Berlin
+      FORCE_COLOR: true
     steps:
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
 
-    - name: Install dependencies
+    - name: Update pip etc.
       run: |
         python -m pip install --upgrade pip
-        python -m pip install --upgrade setuptools wheel build
+        python -m pip install --upgrade setuptools wheel build twine
 
     - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        fetch-tags: true
     - name: Build sdist
       run: python -m build --sdist
+    - name: Check sdist
+      run: twine check --strict dist/*
     - name: Install sdist
-      run: pip install ./dist/pybv-*
+      run: python -m pip install ./dist/pybv-*
     - name: Clean up working directory
       run: rm -rf ./*
     - name: Try importing pybv
       run: python -c 'import pybv; print(pybv.__version__)'
     - name: Remove sdist install
-      run: pip uninstall -y pybv
+      run: python -m pip uninstall -y pybv
 
     - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        fetch-tags: true
     - name: Build wheel
       run: python -m build --wheel
+    - name: Check wheel
+      run: twine check --strict dist/*
     - name: Install wheel
-      run: pip install ./dist/pybv-*.whl
+      run: python -m pip install ./dist/pybv-*.whl
     - name: Clean up working directory
       run: rm -rf ./*
     - name: Try importing pybv
       run: python -c 'import pybv; print(pybv.__version__)'
     - name: Remove wheel install
-      run: pip uninstall -y pybv
+      run: python -m pip uninstall -y pybv

.github/workflows/python_tests.yml

@@ -6,11 +6,11 @@ concurrency:
 
 on:
   push:
-    branches: [main]
+    branches: [ main ]
   pull_request:
-    branches: [main]
+    branches: [ main ]
   schedule:
-    - cron: "0 4 1 * *"
+    - cron: "0 4 * * MON"
 
 
 jobs:
@@ -29,29 +29,36 @@ jobs:
             python-version: "3.12"
             mne-version: mne-main
 
+    runs-on: ${{ matrix.platform }}
+
     env:
       TZ: Europe/Berlin
       FORCE_COLOR: true
-
-    runs-on: ${{ matrix.platform }}
-
     steps:
     - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+        fetch-tags: true
 
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
 
+    - uses: actions/cache@v4
+      with:
+        path: ${{ env.pythonLocation }}
+        key: v-0-${{ env.pythonLocation }}-${{ hashFiles('pyproject.toml') }}
+
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        python -m pip install -e .[dev]
+        python -m pip install -e ".[dev]"
 
-    - name: install MNE-Python main
+    - name: Install MNE-Python main (development version)
       if: matrix.mne-version == 'mne-main'
       run: |
-        pip install -U https://github.com/mne-tools/mne-python/archive/refs/heads/main.zip
+        python -m pip install -U https://github.com/mne-tools/mne-python/archive/refs/heads/main.zip
 
     - name: Display versions and environment information
       run: |
@@ -62,6 +69,7 @@ jobs:
         mne sys_info
 
     - name: Check formatting
+      if: matrix.platform == 'ubuntu-latest'
       run: |
         make check-manifest
         pre-commit run --all-files

.gitignore

@@ -14,3 +14,4 @@ htmlcov/
 .vscode/
 .venv
 .idea
+.ruff_cache

README.rst

@@ -1,14 +1,18 @@
 .. image:: https://github.com/bids-standard/pybv/workflows/Python%20build/badge.svg
    :target: https://github.com/bids-standard/pybv/actions?query=workflow%3A%22Python+build%22
-   :alt: GitHub Actions Python build
+   :alt: Python build
 
 .. image:: https://github.com/bids-standard/pybv/workflows/Python%20tests/badge.svg
    :target: https://github.com/bids-standard/pybv/actions?query=workflow%3A%22Python+tests%22
-   :alt: GitHub Actions Python tests
+   :alt: Python tests
 
 .. image:: https://codecov.io/gh/bids-standard/pybv/branch/main/graph/badge.svg
    :target: https://codecov.io/gh/bids-standard/pybv
-   :alt: Codecov
+   :alt: Test coverage
+
+.. image:: https://readthedocs.org/projects/pybv/badge/?version=stable
+   :target: https://pybv.readthedocs.io/en/stable/?badge=stable
+   :alt: Documentation Status
 
 .. image:: https://badge.fury.io/py/pybv.svg
    :target: https://badge.fury.io/py/pybv
@@ -18,10 +22,6 @@
    :target: https://anaconda.org/conda-forge/pybv
    :alt: Conda version
 
-.. image:: https://readthedocs.org/projects/pybv/badge/?version=stable
-   :target: https://pybv.readthedocs.io/en/stable/?badge=stable
-   :alt: Documentation Status
-
 .. image:: https://zenodo.org/badge/157434681.svg
    :target: https://zenodo.org/badge/latestdoi/157434681
    :alt: Zenodo archive
@@ -30,16 +30,17 @@
 pybv
 ====
 
-``pybv`` is a lightweight I/O utility for the BrainVision data format.
+For documentation, see the:
 
-The BrainVision data format is a recommended data format for use in the
-`Brain Imaging Data Structure <https://bids.neuroimaging.io>`_.
+- `stable documentation <https://pybv.rtfd.io/en/stable/>`_
+- `latest (development) documentation <https://pybv.rtfd.io/en/latest/>`_
 
+.. docs_readme_include_label
 
-The documentation can be found under the following links:
+``pybv`` is a lightweight I/O utility for the BrainVision data format.
 
-- for the `stable release <https://pybv.rtfd.io/en/stable/>`_
-- for the `latest (development) version <https://pybv.rtfd.io/en/latest/>`_
+The BrainVision data format is a recommended data format for use in the
+`Brain Imaging Data Structure <https://bids.neuroimaging.io>`_.
 
 About the BrainVision data format
 =================================
@@ -73,7 +74,6 @@ A documentation for the BrainVision file format is provided by Brain Products.
 You can `view the specification <https://www.brainproducts.com/support-resources/brainvision-core-data-format-1-0/>`_
 as hosted by Brain Products.
 
-
 Installation
 ============
 
@@ -87,11 +87,26 @@ After you have a working installation of MNE-Python (or only ``numpy`` if you
 do not want to read data and only write it), you can install ``pybv`` through
 the following:
 
-- ``pip install --upgrade pybv``
+.. code-block:: Text
+
+   python -m pip install --upgrade pybv
 
 or if you use `conda <https://docs.conda.io/en/latest/miniconda.html>`_:
 
-- ``conda install --channel conda-forge pybv``
+.. code-block:: Text
+
+   conda install --channel conda-forge pybv
+
+For installing the **latest (development)** version of ``pyprep``, call:
+
+.. code-block:: Text
+
+   python -m pip install --upgrade https://github.com/bids-standard/pybv/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.
 
 Contributing
 ============
@@ -100,7 +115,13 @@ The development of ``pybv`` is taking place on
 `GitHub <https://github.com/bids-standard/pybv>`_.
 
 For more information, please see
-`CONTRIBUTING.md <https://github.com/bids-standard/pybv/blob/main/.github/CONTRIBUTING.md>`_
+`CONTRIBUTING.md <https://github.com/bids-standard/pybv/blob/main/.github/CONTRIBUTING.md>`_.
+
+Citing
+======
+
+If you use this software in academic work, please cite it using the `Zenodo entry <https://zenodo.org/badge/latestdoi/157434681>`_.
+Metadata is encoded in the `CITATION.cff` file.
 
 Usage
 =====

docs/index.rst

@@ -1,4 +1,9 @@
+====
+pybv
+====
+
 .. include:: ../README.rst
+    :start-after: .. docs_readme_include_label
 
 .. toctree::
    :hidden: