diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 2d286f1..62827d9 100644 --- a/.github/CONTRIBUTING.md +++ b/.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). diff --git a/.github/workflows/python_build.yml b/.github/workflows/python_build.yml index 65d7d34..e2de531 100644 --- a/.github/workflows/python_build.yml +++ b/.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 diff --git a/.github/workflows/python_tests.yml b/.github/workflows/python_tests.yml index faadc82..56c7b12 100644 --- a/.github/workflows/python_tests.yml +++ b/.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 diff --git a/.gitignore b/.gitignore index e324adf..e9c0566 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,4 @@ htmlcov/ .vscode/ .venv .idea +.ruff_cache diff --git a/README.rst b/README.rst index 79f156f..06ac7b7 100644 --- a/README.rst +++ b/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 `_. +- `stable documentation `_ +- `latest (development) documentation `_ +.. 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 `_ -- for the `latest (development) version `_ +The BrainVision data format is a recommended data format for use in the +`Brain Imaging Data Structure `_. 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 `_ 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 `_: -- ``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 `_. For more information, please see -`CONTRIBUTING.md `_ +`CONTRIBUTING.md `_. + +Citing +====== + +If you use this software in academic work, please cite it using the `Zenodo entry `_. +Metadata is encoded in the `CITATION.cff` file. Usage ===== diff --git a/docs/index.rst b/docs/index.rst index 10e6ce9..1220764 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,9 @@ +==== +pybv +==== + .. include:: ../README.rst + :start-after: .. docs_readme_include_label .. toctree:: :hidden: