From dd291d130aba81e378f7ffd6ace873c3dfea4ddb Mon Sep 17 00:00:00 2001 From: ZFordDev Date: Thu, 20 Aug 2026 20:47:12 +1000 Subject: [PATCH] glint docs update --- CHANGELOG.md | 34 +++++++++++++ CONTRIBUTING.md | 78 ++++++++++++++++++++++++++++ PRIVACY.md | 34 +++++++++++++ README.md | 131 ++++++++++++++++++++++++++++-------------------- SECURITY.md | 34 +++++++++++++ 5 files changed, 258 insertions(+), 53 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 PRIVACY.md create mode 100644 SECURITY.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..a1bd90a --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,34 @@ +# Changelog + +All notable user-facing changes to Glint are recorded here. + +## v1.0.0 (2026-08-20) + +Glint's first stable release turns the original Windows prototype into a tested, cross-platform desktop monitor. + +### Added + +- Cross-platform application and system tray support for Windows, macOS, and Linux +- CPU, RAM, disk, GPU usage, GPU temperature, and live network widgets +- Portable sensor collection through `psutil`, optional Windows WMI, and `nvidia-smi` +- Independent Settings window with live refresh interval, opacity, and theme controls +- Default and Midnight themes +- Versioned JSON preferences, persistent HUD position, and editable widget layouts +- Native autostart entries for Windows, macOS, and freedesktop Linux desktops +- Tests and formatting checks across all three supported operating systems +- Automated native GitHub Release archives and SHA-256 checksums + +### Fixed + +- Restored HUD dragging, including compositor-assisted movement on Wayland +- Prevented Settings from behaving like a panel attached to the frameless HUD +- Made unavailable hardware readings fail gracefully instead of blocking startup +- Corrected Python packaging, console entry points, dependencies, and macOS application bundles + +### Changed + +- Consolidated project dependencies in `pyproject.toml` +- Replaced the old Windows-only implementation with shared platform-aware modules +- Adopted GitHub Releases as the only official distribution channel + +[v1.0.0 release](https://github.com/ZFordDev/Glint/releases/tag/v1.0.0) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6790aab --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,78 @@ +# Contributing to Glint + +Thank you for helping improve Glint. Bug reports, platform testing, documentation, design feedback, and focused code contributions are all welcome. + +Please report security vulnerabilities through the private process in [SECURITY.md](SECURITY.md). Glint also follows the broader [ZFordDev project standards](https://github.com/ZFordDev/ZFordDev/blob/main/STANDARDS.md). + +## Before you begin + +- Search the [issue tracker](https://github.com/ZFordDev/Glint/issues) for an existing report. +- Open an issue before starting a substantial feature or architectural change. +- Keep changes aligned with Glint's lightweight, local-only system-monitoring role. +- Never include private machine information, usernames, hostnames, or unrelated logs in a report. + +## Development setup + +Glint requires Python 3.10 or later and a graphical desktop session. + +```bash +git clone https://github.com/YOUR-USERNAME/Glint.git +cd Glint +python -m venv .venv +# Windows: .venv\Scripts\activate +# macOS/Linux: source .venv/bin/activate +python -m pip install -e ".[dev]" +python main.py +``` + +Create a focused branch from the latest `main` branch: + +```bash +git switch -c fix/short-description +``` + +## Making changes + +- Keep pull requests limited to one logical change. +- Preserve graceful fallbacks when a metric, platform feature, or system tray is unavailable. +- Keep platform-specific imports and behavior isolated behind runtime checks. +- Avoid heavy dependencies unless the benefit clearly justifies the download and maintenance cost. +- Keep drawing logic in the UI layer and sensor collection in `src/core/`. +- Update the README and DocsHub pages when behavior, packaging, or platform support changes. +- Do not turn sensor readings into persistent history, telemetry, or network traffic without prior discussion. + +## Testing + +Run the automated checks before opening a pull request: + +```bash +ruff format --check . +ruff check . +python -m pytest +``` + +Also launch Glint and manually exercise the changed workflow. Platform-sensitive changes should be tested on Windows, macOS, and Linux when possible. If you cannot test a platform, say so clearly in the pull request. + +For UI changes, check HUD dragging, the independent Settings window, tray restoration, opacity, both built-in themes, and behavior when optional sensor values are unavailable. For release changes, use the GitHub Release workflow's non-publishing rehearsal mode or run the equivalent release-script validation locally. + +## Pull requests + +1. Push your branch and open a pull request against `main`. +2. Explain what changed, why it changed, and how it was tested. +3. Link related issues with a keyword such as `Fixes #123` when appropriate. +4. Include screenshots for visible HUD or Settings changes. +5. Keep unrelated formatting and refactoring out of the pull request. + +Clear, present-tense commit messages are appreciated. + +## Good bug reports + +Please include: + +- Glint version and whether it came from a release archive or source +- Operating system, version, architecture, desktop environment, and display server where relevant +- CPU/GPU model and driver when the problem involves sensors +- Clear reproduction steps and expected versus actual behavior +- Relevant logs or screenshots with personal information removed + +Thank you for contributing to Glint. diff --git a/PRIVACY.md b/PRIVACY.md new file mode 100644 index 0000000..97ecc05 --- /dev/null +++ b/PRIVACY.md @@ -0,0 +1,34 @@ +# Glint Privacy Statement + +**Effective date:** v1.0.0 (August 2026) + +## Local-only monitoring + +Glint is a local desktop system monitor. It reads operating-system and hardware metrics to render the HUD on your device. Glint does not upload, synchronise, sell, or otherwise transmit those readings. + +## What Glint reads + +- CPU and memory utilisation +- Mounted-disk labels and utilisation +- Network byte counters used to calculate current upload and download rates +- Temperature and GPU utilisation when exposed by the operating system, driver, WMI, or `nvidia-smi` + +These readings are held only long enough to update the display. Glint does not maintain a monitoring history or write sensor values to disk. + +## What Glint stores + +Glint stores a small local configuration containing the refresh interval, opacity, selected theme, layout name, and HUD position. It also stores JSON layout files describing the HUD size and widget placement. These files remain in the operating system's application configuration directory. + +Glint has: + +- no accounts or sign-in; +- no analytics or telemetry; +- no advertising or tracking; +- no cloud storage or synchronisation; and +- no built-in network update checker. + +Updates are downloaded manually from [GitHub Releases](https://github.com/ZFordDev/Glint/releases). Visiting GitHub is governed by GitHub's own privacy terms; the Glint application itself does not contact GitHub. + +## Questions + +For privacy questions, open an issue at [github.com/ZFordDev/Glint/issues](https://github.com/ZFordDev/Glint/issues) or inspect the source code in this repository. diff --git a/README.md b/README.md index c30e1af..068bab6 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,80 @@ +
+ +Glint icon + # Glint -Glint is a lightweight, painter-rendered desktop system monitor for Windows, macOS, and Linux. It displays CPU, memory, disk, GPU, temperature, and live network metrics without a browser or Electron runtime. +### A lightweight system-monitor HUD for Windows, macOS, and Linux + +[Documentation](https://docs.zford.dev/zforddev/glint/) · [Downloads](https://github.com/ZFordDev/Glint/releases/latest) · [Report a bug](https://github.com/ZFordDev/Glint/issues/new) + +[![Release](https://img.shields.io/github/v/release/ZFordDev/Glint?label=release)](https://github.com/ZFordDev/Glint/releases/latest) +[![Checks](https://github.com/ZFordDev/Glint/actions/workflows/python-app.yml/badge.svg)](https://github.com/ZFordDev/Glint/actions/workflows/python-app.yml) +![Platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-6b8afd) +[![License](https://img.shields.io/github/license/ZFordDev/Glint)](LICENSE) + +
+ +Glint keeps essential system information visible in a compact, translucent desktop HUD. It is built with PyQt 6 and drawn directly with `QPainter`, keeping the application small and avoiding a browser or Electron runtime. + +CPU, memory, disk, GPU, temperature, and network readings are collected locally. Hardware-specific readings degrade gracefully: when a sensor is not exposed by the operating system or driver, Glint shows it as unavailable and continues running. ## Highlights -- Native PyQt 6 HUD and system tray -- Portable CPU, RAM, disk, temperature, and network sensors through `psutil` -- NVIDIA GPU usage and temperature through `nvidia-smi`, with graceful fallback on other hardware -- JSON-backed settings and user-defined widget layouts -- Built-in themes and serializable painter-rendered widgets +- Native, frameless PyQt 6 HUD with persistent positioning +- CPU, RAM, disk, GPU, temperature, upload, and download widgets +- Independent Settings window with live refresh-rate, opacity, and theme controls +- Default and Midnight themes with JSON-backed custom layouts +- System tray controls for showing Glint, opening Settings, autostart, and exit - Native autostart entries for Windows, macOS, and freedesktop Linux desktops +- Standalone GitHub Release archives that do not require Python + +## Download + +Download the archive for your system from the [latest GitHub Release](https://github.com/ZFordDev/Glint/releases/latest): -Unavailable hardware metrics display as “Unavailable”; they do not prevent Glint from starting. +| Platform | Release asset | +| --- | --- | +| Windows x86-64 | `glint-windows-x86_64.zip` | +| macOS Apple silicon | `glint-macos-arm64.zip` | +| macOS Intel | `glint-macos-x86_64.zip` | +| Linux x86-64 | `glint-linux-x86_64.tar.gz` | -## Requirements +Extract the archive and launch `Glint` (`Glint.exe` on Windows). Release checksums are published in `SHA256SUMS`. + +> [!NOTE] +> Glint's standalone archives are currently unsigned. Windows SmartScreen or macOS Gatekeeper may ask you to confirm that you trust the download. Official builds are published only through this repository's GitHub Releases. + +## Use Glint + +| Action | Result | +| --- | --- | +| Left-click and drag the HUD | Move it and remember the new position | +| Right-click the HUD | Open Settings or exit Glint | +| Double-click the tray icon | Show and raise the HUD | +| Open the tray menu | Show Glint, open Settings, manage autostart, or exit | + +Settings and layouts are stored in the operating system's application configuration directory. The generated `default_layout.json` can be edited to change the HUD size, widget order, positions, and disk selection. See the [Glint documentation](https://docs.zford.dev/zforddev/glint/) for examples and platform notes. + +## Sensor support + +| Metric | Windows | macOS | Linux | +| --- | --- | --- | --- | +| CPU, RAM, disk, network | `psutil` | `psutil` | `psutil` | +| CPU temperature | WMI when exposed | `psutil` when exposed | hwmon through `psutil` | +| NVIDIA GPU usage and temperature | `nvidia-smi` | `nvidia-smi` when supported | `nvidia-smi` | +| AMD/Intel GPU usage | Windows performance counters | Unavailable fallback | Unavailable fallback | +| Other GPU temperatures | Platform sensor when exposed | Platform sensor when exposed | hwmon when exposed | -- Python 3.10 or later -- Windows 10+, a current macOS release, or a Linux desktop with a system tray -- A graphical desktop session +Temperature and GPU availability varies by hardware, driver, permissions, and operating system. Wayland compositors may also prevent applications from forcing the HUD below other windows; Glint remains frameless and usable when that hint is ignored. -Linux packages may require Qt system libraries supplied by the distribution. Wayland desktop-shell rules can prevent applications from forcing a window below every other window; the HUD remains frameless and behaves normally in that case. +## Run from source -## Install and run +Glint requires Python 3.10 or later and a graphical desktop session. ```bash +git clone https://github.com/ZFordDev/Glint.git +cd Glint python -m venv .venv # Windows: .venv\Scripts\activate # macOS/Linux: source .venv/bin/activate @@ -35,57 +86,31 @@ For development: ```bash python -m pip install -e ".[dev]" -python -m pytest +ruff format --check . ruff check . +python -m pytest python main.py ``` -## Controls +The test workflow runs on Windows, macOS, and Linux for every pull request and push to `main`. -- Left-click and drag moves the HUD. -- Right-click opens Settings or exits. -- Double-clicking the tray icon restores the HUD. -- The tray menu controls autostart. +## Data and privacy -Settings and layouts use the operating system's application configuration directory. A generated `default_layout.json` can contain multiple disk widgets; set each widget's `disk` field to its device label. +Glint has no accounts, analytics, telemetry, advertising, or cloud service. System readings are displayed locally and are not written to history or transmitted. Only preferences, the HUD position, and layout files are saved on the device. Read the full [privacy statement](PRIVACY.md). -## Sensor support +## Project status -| Metric | Windows | macOS | Linux | -| --- | --- | --- | --- | -| CPU, RAM, disk, network | `psutil` | `psutil` | `psutil` | -| CPU temperature | WMI when exposed | `psutil` when exposed | hwmon through `psutil` | -| GPU usage | `nvidia-smi`, then WMI for AMD/Intel | `nvidia-smi` when supported | `nvidia-smi` | -| Other GPU temperature | unavailable fallback | platform sensor when exposed | hwmon when exposed | +Glint v1.0.0 is the first stable, cross-platform release. Distribution is intentionally minimal and GitHub-exclusive: there are no Microsoft Store, Mac App Store, Snap Store, or other store packages, and the legacy `glasshub-updater` prototype is not a supported update path. -Hardware and driver vendors expose sensors inconsistently, so temperature and GPU metrics are optional by design. +Releases are built by GitHub Actions from matching `v*` tags. The workflow verifies formatting, lint, tests, and version consistency before creating native archives and SHA-256 checksums. Maintainer details are documented in [architecture and maintenance notes](https://docs.zford.dev/zforddev/glint/maintenance/). -## Project layout +## Contributing and support -```text -src/ - core/ sensors, settings, themes - ui/ HUD, tray, settings, layouts - widgets/ independent painter widgets - app.py application entry point -tests/ core behavior tests -``` +- Read [CONTRIBUTING.md](CONTRIBUTING.md) before preparing a change. +- Use the [issue tracker](https://github.com/ZFordDev/Glint/issues) for reproducible bugs and focused feature requests. +- Report vulnerabilities privately using [SECURITY.md](SECURITY.md). +- Review release history in [CHANGELOG.md](CHANGELOG.md). ## License -MIT - -## Releases - -Glint is distributed exclusively through GitHub Releases as minimal standalone archives—there are no Microsoft Store, Snap Store, or other store packages. - -The archives are currently unsigned. Windows SmartScreen and macOS Gatekeeper may therefore ask users to confirm that they trust the download. Code signing can be added later without changing the GitHub-only distribution model. - -Maintainers publish a release by updating `project.version` in `pyproject.toml`, merging the tested change to `main`, and pushing a matching tag such as `v1.0.0`. GitHub Actions then: - -1. verifies formatting, lint, tests, and the tag/version match; -2. builds native Windows, macOS, and Linux bundles with PyInstaller; -3. creates SHA-256 checksums; and -4. publishes the archives and generated notes to the tagged GitHub Release. - -The workflow can also be started manually in rehearsal mode, which validates and builds without publishing. Enabling its `publish` input requires an existing matching tag and creates the release after all builds succeed. +Glint is open-source software released under the [MIT License](LICENSE). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..224c5fe --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,34 @@ +# Security Policy + +Glint welcomes responsible reports that help keep its users and systems safe. + +## Supported versions + +Security fixes target the latest stable release and the current development branch. Older releases, forks, modified builds, and unofficial distributions may not receive fixes. Users should update to the latest stable GitHub Release when a security update is published. + +## Report a vulnerability privately + +Use [GitHub's private vulnerability reporting](https://github.com/ZFordDev/Glint/security/advisories/new) whenever possible. + +If that form is unavailable, email [zforddev@gmail.com](mailto:zforddev@gmail.com) with `Glint security report` in the subject line. + +Do not open a public issue, discussion, or pull request for an unpatched vulnerability. Include the affected version and platform, potential impact, reproduction steps or a minimal proof of concept, and any useful logs with personal information removed. + +Reports made in good faith should avoid accessing data that is not yours, disrupting other systems, or causing harm. The maintainer will review the report, attempt to reproduce it, prepare a fix or mitigation when appropriate, and coordinate disclosure through the original private channel. + +## Scope + +This policy covers Glint's source code and official GitHub Release archives, including sensor collection, configuration and layout file handling, autostart integration, packaging, and bundled dependencies. + +The following are generally outside scope unless they create a vulnerability in an official release: + +- Unsupported versions, forks, and modified or unofficial builds +- Vulnerabilities that require an already-compromised operating system +- Hardware or driver behavior that only makes a metric unavailable or inaccurate +- Reports that identify an outdated dependency without demonstrating relevant impact + +## Security characteristics + +Glint reads local operating-system metrics and may call locally installed facilities such as WMI or `nvidia-smi`. It does not require administrator privileges, expose a network service, collect telemetry, or transmit sensor readings. Preferences and layouts are stored locally in the platform application configuration directory. + +Official archives are currently unsigned. Verify downloads against the `SHA256SUMS` file attached to the same GitHub Release and obtain releases only from `github.com/ZFordDev/Glint`.