Improve 2.1 RC visibility in README and docs

Author: rossant

README.md

@@ -6,127 +6,177 @@
 [![GitHub release](https://img.shields.io/github/release/cortex-lab/phy.svg)](https://github.com/cortex-lab/phy/releases/latest)
 [![PyPI release](https://img.shields.io/pypi/v/phy.svg)](https://pypi.python.org/pypi/phy)
 
+[**phy**](https://github.com/cortex-lab/phy) is an open-source Python library providing a graphical user interface for visualization and manual curation of large-scale electrophysiological data. It is optimized for high-density multielectrode arrays containing hundreds to thousands of recording sites, especially Neuropixels recordings.
 
-[**phy**](https://github.com/cortex-lab/phy) is an open-source Python library providing a graphical user interface for visualization and manual curation of large-scale electrophysiological data. It is optimized for high-density multielectrode arrays containing hundreds to thousands of recording sites (mostly [Neuropixels probes](https://www.ucl.ac.uk/neuropixels/)).
+> **Release candidate available:** `phy 2.1.0rc1` is available for testing on PyPI. This maintenance-focused release candidate aims to improve installation and GUI reliability on current systems. See the [release notes](https://phy.readthedocs.io/en/latest/release/) for installation instructions, compatibility notes, and testing guidance.
 
-Phy provides two GUIs:
+[![phy 2.1.0rc1 screenshot](https://user-images.githubusercontent.com/1942359/74028054-c284b880-49a9-11ea-8815-1b7e727a8644.png)](https://user-images.githubusercontent.com/1942359/74028054-c284b880-49a9-11ea-8815-1b7e727a8644.png)
 
-* **Template GUI** (recommended): for datasets sorted with KiloSort and Spyking Circus,
-* **Kwik GUI** (legacy): for datasets sorted with klusta and klustakwik2.
+## Current status
 
+As of March 2026, `phy 2.1.0rc1` is a maintenance-focused release candidate for the current 2.x line.
 
-[![phy 2.0b1 screenshot](https://user-images.githubusercontent.com/1942359/74028054-c284b880-49a9-11ea-8815-1b7e727a8644.png)](https://user-images.githubusercontent.com/1942359/74028054-c284b880-49a9-11ea-8815-1b7e727a8644.png)
+The main goals of this release are:
 
+* dependency and packaging modernization
+* replacing a fragile legacy web-based GUI component with a Qt-native implementation
+* improving display reliability on modern systems
+* collecting feedback from beta testers before a final `2.1.0` release
 
-## What's new
-* [5 June 2024] phy 2.0 beta 6, bug fixes, install work, fixing some deprecations
-* [7 Sep 2021] Release of phy 2.0 beta 5, with some install and bug fixes
-* [7 Feb 2020] Release of phy 2.0 beta 1, with many new views, new features, various improvements and bug fixes...
+Dataset formats are unchanged. Some plugins that relied on internal HTML or web-based GUI components may need updates.
 
+If you would like to test this release candidate, install it in a fresh Python 3.10+ environment:
 
-## Links
+```bash
+python -m pip install --upgrade pip
+pip install "phy==2.1.0rc1"
+```
 
-* [Documentation](http://phy.readthedocs.org/en/latest/)
-* [Mailing list](https://groups.google.com/forum/#!forum/phy-users)
+Please report any issues or compatibility regressions on [GitHub issues](https://github.com/cortex-lab/phy/issues).
 
+## Supported workflows
 
-## Hardware requirements
+phy currently provides three main entry points:
 
-It is recommended to store the data on a SSD for performance reasons.
+* **Template GUI**: the main and recommended workflow for datasets sorted with KiloSort and Spyking Circus
+* **Kwik GUI**: a legacy workflow for datasets sorted with klusta and klustakwik2
+* **Trace GUI**: an experimental raw-data viewer for opening continuous electrophysiology recordings directly
 
-There are no specific GPU requirements as long as relatively recent graphics and OpenGL drivers are installed on the system.
+Current testing and maintenance work is focused on modern Linux, macOS, and Windows environments. Linux is still the best-covered platform, but cross-platform testing is active during the `2.1.0rc1` cycle.
 
+## Installation
 
-## Installation instructions
+Install phy in a fresh Python 3.10+ environment:
 
-Run the following commands in a terminal (currently working for Linux machines):
+```bash
+python -m pip install --upgrade pip
+pip install phy
+```
 
-1. Create a new conda environment with the conda dependencies:
+This installs the GUI runtime dependencies as part of the main package.
 
-    ```
-    conda create -n phy2 -y python=3.11 cython dask h5py joblib matplotlib numpy pillow pip pyopengl pyqt pyqtwebengine pytest python qtconsole requests responses scikit-learn scipy traitlets
-    ```
+If you plan to use the legacy Kwik GUI, also install:
 
-2. Activate the new conda environment with `conda activate phy2`
+```bash
+pip install klusta klustakwik2
+```
 
-3. Install the development version of phy: `pip install git+https://github.com/cortex-lab/phy.git`
+For release-candidate testing specifically, install the exact RC version instead:
 
-4. [OPTIONAL] If you plan to use the Kwik GUI, type `pip install klusta klustakwik2`
+```bash
+pip install "phy==2.1.0rc1"
+```
 
-5. Phy should now be installed. Open the GUI on a dataset as follows (the phy2 environment should still be activated):
+## Quick start
+
+Open the Template GUI on a spike sorting output directory containing `params.py`:
 
 ```bash
 cd path/to/my/spikesorting/output
 phy template-gui params.py
 ```
 
-6. If there are problems with this method we also have an `environment.yml` file which allows for
-automatic install of the necessary packages. Give that a try.
+Other useful commands:
 
+```bash
+phy template-describe params.py
+phy kwik-gui path/to/file.kwik
+phy trace-gui path/to/raw.bin --sample-rate 30000 --dtype int16 --n-channels 384
+```
 
-### Dealing with the error `ModuleNotFoundError: No module named 'PyQt5.QtWebEngineWidget`
+## Available GUIs and commands
 
-In some environments, you might get an error message related to QtWebEngineWidget. Run the command `pip install PyQtWebEngine` and try launching phy again. This command should not run if the error message doesn't appear, as it could break the PyQt5 installation.
+### Template GUI
 
+Use the Template GUI for current template-based workflows such as KiloSort and Spyking Circus.
 
-### Upgrading from phy 1 to phy 2
+```bash
+phy template-gui params.py
+```
 
-* Do not install phy 1 and phy 2 in the same Python environment.
-* It is recommended to delete `~/.phy/*GUI/state.json` when upgrading.
+To inspect a dataset from the terminal without launching the GUI:
 
+```bash
+phy template-describe params.py
+```
 
-### Developer instructions (and instructions for some Windows machines)
+### Kwik GUI
 
-To install the development version of phy in a fresh environment, do:
+The Kwik GUI is still available for legacy kwik datasets, but it is no longer the primary workflow.
 
 ```bash
-git clone git@github.com:cortex-lab/phy.git
-cd phy
-pip install -r requirements.txt
-pip install -r requirements-dev.txt
-pip install -e .
-cd ..
-git clone git@github.com:cortex-lab/phylib.git
-cd phylib
-pip install -e . --upgrade
+phy kwik-gui path/to/file.kwik
 ```
 
-### Mac Install
+### Trace GUI
 
-Since the switch to M-series chips Mac install for Phy is not being officially supported.
-Rarely people are able to hack together a version with old versions of python etc.
+The Trace GUI is still experimental and opens raw electrophysiology recordings directly.
 
-### Troubleshooting
+```bash
+phy trace-gui path/to/raw.bin --sample-rate 30000 --dtype int16 --n-channels 384
+```
 
-* [See a list of common issues.](https://phy.readthedocs.io/en/latest/troubleshooting/)
-* [Raise a GitHub issue.](https://github.com/cortex-lab/phy/issues)
+## Running phy from Python
 
+You can also launch phy from Python or IPython, which can be useful for debugging or profiling:
 
-## Running phy from a Python script
+```python
+from phy.apps.template import template_gui
 
-In addition to launching phy from the terminal with the `phy` command, you can also launch it from a Python script or an IPython terminal. This may be useful when debugging or profiling. Here's a code example to copy-paste in a new `launch.py` text file within your data directory:
+template_gui("params.py")
+```
 
+## Developer setup
+
+To work on phy itself in a fresh checkout:
+
+```bash
+git clone git@github.com:cortex-lab/phy.git
+cd phy
+uv sync --dev
 ```
-from phy.apps.template import template_gui
-template_gui("params.py")
+
+If you are working on phy together with a local checkout of `phylib`, install that checkout in editable mode:
+
+```bash
+git clone git@github.com:cortex-lab/phylib.git
+cd phylib
+pip install -e . --upgrade
 ```
 
+## Troubleshooting and docs
+
+* [Documentation](https://phy.readthedocs.io/en/latest/)
+* [Release notes](https://phy.readthedocs.io/en/latest/release/)
+* [Troubleshooting](https://phy.readthedocs.io/en/latest/troubleshooting/)
+* [GitHub issues](https://github.com/cortex-lab/phy/issues)
+* [Mailing list](https://groups.google.com/forum/#!forum/phy-users)
 
 ## Credits
 
 **phy** is developed and maintained by [Cyrille Rossant](https://cyrille.rossant.net).
 
 * [International Brain Laboratory](https://internationalbrainlab.org)
-* [Cortex Lab (UCL)](https://www.ucl.ac.uk/cortexlab/) ([Kenneth Harris](https://www.ucl.ac.uk/biosciences/people/harris-kenneth) and [Matteo Carandini](https://www.carandinilab.net/)).
+* [Cortex Lab (UCL)](https://www.ucl.ac.uk/cortexlab/) ([Kenneth Harris](https://www.ucl.ac.uk/biosciences/people/harris-kenneth) and [Matteo Carandini](https://www.carandinilab.net/))
 
 Contributors to the repository are:
 
+* Maxime Beau
 * [Alessio Buccino](https://github.com/alejoe91)
+* Thad Czuba
 * [Michael Economo](https://github.com/mswallac)
+* Einsied
 * [Cedric Gestes](https://github.com/cgestes)
-* [Dan Goodman](http://thesamovar.net/)
+* Yaroslav Halchenko
 * [Max Hunter](https://iris.ucl.ac.uk/iris/browse/profile?upi=MLDHU99)
 * [Shabnam Kadir](https://iris.ucl.ac.uk/iris/browse/profile?upi=SKADI56)
+* [Zach McKenzie](https://github.com/zm711)
+* Sam Minkowicz
 * [Christopher Nolan](https://github.com/crnolan)
+* [Jesús Peñaloza](https://github.com/jpenalozaa)
+* [Luke Shaheen](https://github.com/LukeShaheen)
 * [Martin Spacek](http://mspacek.github.io/)
 * [Nick Steinmetz](http://www.nicksteinmetz.com/)
+* Olivier Winter
+* szapp
+* ycanerol

docs/announcement_2.1.0rc1.md

@@ -0,0 +1,45 @@
+# phy 2.1.0rc1 announcement text
+
+Short copy-paste announcement text for the `2.1.0rc1` release candidate.
+
+For installation, upgrade, compatibility, and testing details, point people to the live release notes page:
+https://phy.readthedocs.io/en/latest/release/
+
+## Copy-paste announcement for mailing list
+
+Subject:
+
+```text
+phy 2.1.0rc1 release candidate available for testing
+```
+
+Body:
+
+```text
+Dear phy users,
+
+phy 2.1.0rc1 is now available on PyPI for testing. This is a release candidate for a maintenance release of the current 2.x line, focused on fixing several long-standing issues that have built up over recent years while the project had very limited maintenance.
+
+This release does not aim to introduce major new features. The goal is to make phy easier to install and more reliable again on current systems, especially for users who have run into packaging or GUI problems.
+
+If you still use phy, testing and feedback would be very helpful before the final 2.1.0 release.
+
+Release notes and compatibility notes:
+https://phy.readthedocs.io/en/latest/release/
+
+Please report issues here:
+https://github.com/cortex-lab/phy/issues
+```
+
+## Copy-paste announcement for GitHub release notes
+
+```text
+phy 2.1.0rc1 is now available on PyPI for testing.
+
+This is a release candidate for a maintenance release of the current 2.x line, focused on fixing several long-standing issues that have accumulated over recent years.
+
+The goal of this release is not to add major new features, but to make phy easier to install and more reliable again on current systems.
+
+For release notes, compatibility notes, and testing guidance, see:
+https://phy.readthedocs.io/en/latest/release/
+```

docs/index.md

@@ -2,22 +2,22 @@
 
 [**phy**](https://github.com/cortex-lab/phy) is an open-source Python library providing a graphical user interface for visualization and manual curation of large-scale electrophysiological data. It is optimized for high-density multielectrode arrays containing hundreds to thousands of recording sites (mostly [Neuropixels probes](https://www.ucl.ac.uk/neuropixels/)).
 
-[![phy 2.0b1 screenshot](https://user-images.githubusercontent.com/1942359/74028054-c284b880-49a9-11ea-8815-1b7e727a8644.png)](https://user-images.githubusercontent.com/1942359/74028054-c284b880-49a9-11ea-8815-1b7e727a8644.png)
+> **Current release candidate:** [phy 2.1.0rc1](release.md) is available for testing on PyPI. This maintenance-focused release candidate aims to improve installation and GUI reliability on current systems. See the [release notes](release.md) for installation instructions, compatibility notes, and testing guidance.
 
+[![phy 2.1.0rc1 screenshot](https://user-images.githubusercontent.com/1942359/74028054-c284b880-49a9-11ea-8815-1b7e727a8644.png)](https://user-images.githubusercontent.com/1942359/74028054-c284b880-49a9-11ea-8815-1b7e727a8644.png)
 
 ## Spike sorting programs
 
 phy can open datasets spike-sorted with the following programs:
 
-* [KiloSort](https://github.com/MouseLand/Kilosort2/)
+* [KiloSort](https://github.com/MouseLand/Kilosort)
 * [SpykingCircus](https://spyking-circus.readthedocs.io/en/latest/)
-* [klusta](http://klusta.readthedocs.org/en/latest/)
+* [klusta](https://klusta.readthedocs.io/en/latest/)
 
-KiloSort and SpykingCircus are spike sorting programs based on template matching. They use a file format based on `.npy` ([NumPy binary arrays](https://docs.scipy.org/doc/numpy-1.14.2/neps/npy-format.html)) and `.tsv` files (tab-separated files).
+KiloSort and SpykingCircus are spike sorting programs based on template matching. They use a file format based on `.npy` ([NumPy binary arrays](https://numpy.org/doc/stable/reference/generated/numpy.lib.format.html)) and `.tsv` files (tab-separated files).
 
 klusta is a legacy spike sorting program based on an automatic clustering algorithm. It uses the [kwik format](https://klusta.readthedocs.io/en/latest/kwik/#kwik-format) based on HDF5. While klusta and the kwik format are still supported by phy, they are no longer actively maintained.
 
-
 ## Installation instructions
 
-[Go to the GitHub repository](https://github.com/cortex-lab/phy/) to see the installation instructions.
+See the [GitHub repository](https://github.com/cortex-lab/phy/) for stable-install instructions, or go to the [release notes](release.md) for the `2.1.0rc1` release-candidate install and testing instructions.