From 058fe7428cfb0e8e5d4bf5865b3e6722ac5e7ed2 Mon Sep 17 00:00:00 2001 From: Ublaze Date: Mon, 23 Mar 2026 13:27:32 +0400 Subject: [PATCH 1/2] Add ToC, CI badge, issue templates, CONTRIBUTING, CHANGELOG - Add collapsible Table of Contents to README (253 lines warranted one) - Add CI workflow badge to the badge row - Create bug report and feature request issue templates - Create PR template with checklist - Create CONTRIBUTING.md with dev setup, code style, and PR guidelines - Create CHANGELOG.md in Keep a Changelog format for v0.1.0 Co-Authored-By: Claude Opus 4.6 --- .github/ISSUE_TEMPLATE/bug_report.md | 35 ++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 23 +++++++ .github/PULL_REQUEST_TEMPLATE.md | 15 +++++ CHANGELOG.md | 29 ++++++++ CONTRIBUTING.md | 80 +++++++++++++++++++++++ README.md | 20 ++++++ 6 files changed, 202 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..96b020d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,35 @@ +--- +name: Bug Report +about: Something isn't working as expected +title: '' +labels: bug +assignees: '' +--- + +## What happened? + +A clear description of the bug. + +## Steps to reproduce + +1. ... +2. ... +3. ... + +## Expected behavior + +What should have happened instead. + +## Environment + +- **Windows version**: (e.g., Windows 11 23H2) +- **Caffeinator version**: (e.g., v0.1.0 standalone exe / pip install) +- **Python version** (if running from source): + +## Logs / Screenshots + +Paste any relevant logs or attach screenshots. You can find logs at `%APPDATA%\procawake\`. + +## Additional context + +Anything else that might help — monitored apps, config snippets, `procawake diagnose` output, etc. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..fe7123b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,23 @@ +--- +name: Feature Request +about: Suggest an idea or improvement +title: '' +labels: enhancement +assignees: '' +--- + +## Problem or use case + +What are you trying to do, and why is it difficult or impossible today? + +## Proposed solution + +How would you like it to work? + +## Alternatives considered + +Have you tried any workarounds or other tools? + +## Additional context + +Screenshots, config examples, links to related issues, etc. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..830f399 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,15 @@ +## What does this PR do? + +A brief description of the change. + +## Related issue + +Closes # + +## Checklist + +- [ ] I've run `pytest tests/ -v` and all tests pass +- [ ] I've run `ruff check src/` with no warnings +- [ ] I've tested the change on Windows 10 or 11 +- [ ] I've updated the README if this changes user-facing behavior +- [ ] My changes are focused — one feature or fix per PR diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..b75a953 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,29 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/). + +## [0.1.0] - 2026-03-23 + +### Added + +- Per-app monitoring rules with display, system, or both actions +- Settings GUI for scanning and selecting running applications +- System tray with color-coded coffee cup icon (idle / active / paused) +- Native Win32 power API (`PowerCreateRequest`) — visible in `powercfg /requests` +- Session-aware monitoring — pauses on screen lock +- 30-second cooldown to prevent rapid on/off during app restarts +- Auto-detect for 35+ common applications (IDEs, media players, meeting tools) +- Window title matching with regex support +- CPU threshold triggering +- Foreground-only option +- Full CLI: `run`, `status`, `scan`, `list`, `add`, `remove`, `enable`, `disable`, `diagnose`, `config` +- Standalone `.exe` build via PyInstaller +- Windows installer build via Inno Setup + +### Fixed + +- Tray icon stuck on idle when monitored apps are already running at launch + +[0.1.0]: https://github.com/Ublaze/Caffeinator/releases/tag/v0.1.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..1db2c15 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,80 @@ +# Contributing to Caffeinator + +Thanks for your interest in contributing! Caffeinator is a small utility and contributions of all sizes are welcome — bug fixes, new features, docs improvements, or just reporting issues. + +## Getting Started + +1. **Fork and clone** the repo: + + ```bash + git clone https://github.com//Caffeinator.git + cd Caffeinator + ``` + +2. **Install in development mode**: + + ```bash + pip install -e ".[dev]" + ``` + +3. **Run the app** to make sure everything works: + + ```bash + procawake + ``` + +## Development Workflow + +1. Create a feature branch from `main`: + + ```bash + git checkout -b my-feature + ``` + +2. Make your changes. Keep commits focused — one logical change per commit. + +3. Run the checks before pushing: + + ```bash + # Lint + ruff check src/ + + # Type check + mypy src/procawake/ --ignore-missing-imports + + # Tests + pytest tests/ -v + ``` + +4. Push your branch and open a Pull Request against `main`. + +## Code Style + +- We use [Ruff](https://docs.astral.sh/ruff/) for linting. The CI pipeline enforces this. +- Type hints are encouraged. We run `mypy` in CI. +- Keep functions short and well-named. If a comment explains *what* the code does, the code probably needs renaming. + +## Testing + +- Tests live in `tests/` and use `pytest`. +- If you're adding a new feature, add tests for it. +- If you're fixing a bug, add a test that would have caught it. + +## Pull Request Expectations + +- **One thing per PR.** A bug fix and a new feature should be separate PRs. +- **Describe the "why."** The PR description should explain the motivation, not just list files changed. +- **Keep it small.** Smaller PRs get reviewed faster and merged sooner. +- **Tests must pass.** CI runs lint, type checking, and tests on Python 3.11 through 3.13. + +## Reporting Bugs + +Open an issue using the **Bug Report** template. Include your Windows version, how you installed Caffeinator (exe vs pip vs source), and any relevant logs from `%APPDATA%\procawake\`. + +## Suggesting Features + +Open an issue using the **Feature Request** template. Describe the problem you're trying to solve — sometimes there's already a way to do it with existing config options. + +## Questions? + +Open a discussion or issue. There are no dumb questions. diff --git a/README.md b/README.md index 6e4e4dc..4d3c1d3 100644 --- a/README.md +++ b/README.md @@ -11,8 +11,28 @@ Python MIT License Download + CI

+
+Table of Contents + +- [Why Caffeinator?](#why-caffeinator) +- [Features](#features) +- [Quick Start](#quick-start) +- [How It Works](#how-it-works) +- [Settings GUI](#settings-gui) +- [CLI (for power users)](#cli-for-power-users) +- [Configuration](#configuration) +- [Comparison](#comparison) +- [System Requirements](#system-requirements) +- [Building from Source](#building-from-source) +- [Architecture](#architecture) +- [Contributing](#contributing) +- [License](#license) + +
+ --- **Caffeinator** is a Windows app that keeps your screen alive when specific applications are running. Unlike tools that are always-on or use input simulation hacks, Caffeinator monitors your processes and only prevents sleep when apps *you care about* are active. From 2c3a8b1b11f6a5bf6fd9868b9b6bfe32073953c9 Mon Sep 17 00:00:00 2001 From: Ublaze Date: Mon, 23 Mar 2026 13:39:34 +0400 Subject: [PATCH 2/2] Add star CTA at bottom of README --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index 4d3c1d3..1680534 100644 --- a/README.md +++ b/README.md @@ -271,3 +271,11 @@ Issues and PRs are welcome. Please: ## License [MIT](LICENSE) — use it however you want. + +--- + +
+ +If Caffeinator saved your screen, consider giving it a :star: — it helps others find it! + +