Skip to content

Contributing

Contributions welcome. The source code lives on GitHub — fork it, clone it, and send a pull request. Please open an issue first to discuss larger changes, or start a thread in GitHub Discussions.

Areas that need work:

  • More application integrations

Planned Enhancements

  • Window controls (maximize, minimize)
  • Dictation focus detection fix
  • Further GNOME integration for desktop control
  • Verbal help per section (say "help browser" for spoken commands)
  • Auto-discover installed apps for launcher
  • Clipboard commands (copy, paste)

Development

This project sports a Justfile to simplify all local development activities, and for running the same tasks in the CI pipeline.

just

just all

UV_PYTHON=3.14 just pytest -q -x

just clean

The setup uses uv under the hood, which transparently manages virtual environments and package installation. uv also allows you to install several Python versions on your computer in parallel. We use this to test against all supported Python versions.

Prerequisites

First install the system build dependencies (PortAudio, GCC, Python 3.10–3.14, …) as described under Install from source in the Installation guide — without them the build and run steps below will fail.

Then install uv and just, e.g.

python3 -m pip install uv

uv tool install rust-just

NixOS

Enter a development shell with all dependencies installed, or run the application directly:

nix develop

nix run

To run directly off GitHub, with no clone required:

nix run github:ctsdownloads/easyspeak

Packaging & Version Numbers

The packaging configuration is in pyproject.toml, supported by MANIFEST.in. Version numbers are generated automatically by setuptools-scm based on the latest Git tag and the distance from that tag in number of commits.

We create releases by drafting a new release from the GitHub Releases:

  1. Extend the CHANGELOG by a release entry (see steps 3 through 6 below for the content).
  2. Click on Draft a new release.
  3. Pick or enter the next suitable semantic version number in the tag selector (target: main).
  4. Enter a title, e.g. "<version> · <a-catchy-phrase> · <date>" (in GitHub Releases, leave out the date).
  5. Click on Generate release notes.
  6. Write a concise summary of one or two paragraphs at most.
  7. Commit the CHANGELOG, e.g. with a "Release <version>" commit message.
  8. Finally, press Publish Release (release label "Latest").