Improve README framing and add issue/label maintainer tooling

2026-02-23 08:17:59 +01:00
parent 2aca752a51
commit 7869b61836
9 changed files with 408 additions and 9 deletions
--- a/.github/ISSUE_TEMPLATE/bug-report.yml
+++ b/.github/ISSUE_TEMPLATE/bug-report.yml
@@ -0,0 +1,92 @@
+name: Bug report
+description: Report incorrect behavior, regressions, or build/install failures
+title: "[bug] "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting an issue. Please provide enough detail to reproduce the problem.
+  - type: dropdown
+    id: issue_area
+    attributes:
+      label: Area
+      description: Which area best fits this issue?
+      options:
+        - distro-compat
+        - integration
+        - icons
+        - architecture/runtime
+        - ci
+        - docs
+        - other
+    validations:
+      required: true
+  - type: input
+    id: deskify_version
+    attributes:
+      label: Deskify version
+      description: For example `v0.1.0-alpha.2` or commit SHA
+      placeholder: v0.1.0-alpha.2
+    validations:
+      required: true
+  - type: input
+    id: distro
+    attributes:
+      label: Linux distribution
+      description: Include distro + version
+      placeholder: Fedora 41 / Arch Linux / Ubuntu 24.04
+    validations:
+      required: true
+  - type: input
+    id: desktop_environment
+    attributes:
+      label: Desktop environment / session
+      description: Include DE/WM and Wayland/X11 if relevant
+      placeholder: GNOME (Wayland), KDE Plasma (X11), Hyprland
+  - type: textarea
+    id: command
+    attributes:
+      label: Command used
+      description: Exact command that triggered the issue
+      placeholder: |
+        deskify build --url "https://example.com" --name "Example"
+      render: bash
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior / error output
+      description: Paste the relevant error message or describe what happened
+    validations:
+      required: true
+  - type: textarea
+    id: repro_steps
+    attributes:
+      label: Steps to reproduce
+      placeholder: |
+        1. Install prerequisites...
+        2. Run `deskify ...`
+        3. Observe ...
+    validations:
+      required: true
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I checked the README/known limitations and prerequisites
+          required: true
+        - label: I included distro/environment details
+          required: true
+        - label: I included the exact command and error output
+          required: true
+
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Deskify README
+    url: https://github.com/spalencsar/deskify/blob/master/README.md
+    about: Check installation requirements, known limitations, usage examples, and release notes first.
+  - name: Contributing Guide
+    url: https://github.com/spalencsar/deskify/blob/master/CONTRIBUTING.md
+    about: Read local checks, smoke-test guidance, and contribution expectations before opening work-related issues/PRs.
+  - name: Maintainer Notes (Labels / Triage)
+    url: https://github.com/spalencsar/deskify/blob/master/docs/maintainer-notes.md
+    about: Reference label categories and alpha-phase triage conventions.
--- a/.github/ISSUE_TEMPLATE/feature-request.yml
+++ b/.github/ISSUE_TEMPLATE/feature-request.yml
@@ -0,0 +1,72 @@
+name: Feature request
+description: Suggest a user-facing improvement, integration idea, or architectural direction
+title: "[feature] "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the suggestion. Feature requests are most helpful when they describe the problem first, then the proposed solution.
+  - type: dropdown
+    id: request_area
+    attributes:
+      label: Area
+      description: Which area best fits this request?
+      options:
+        - integration
+        - icons
+        - architecture/runtime
+        - distro-compat
+        - docs
+        - ci
+        - other
+    validations:
+      required: true
+  - type: checkboxes
+    id: design_signal
+    attributes:
+      label: Design impact
+      description: Tick this if the request changes long-term project direction
+      options:
+        - label: This likely affects architecture or long-term product direction (`design decision`)
+          required: false
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem statement
+      description: What problem are you trying to solve?
+      placeholder: |
+        I want to ...
+        The current limitation is ...
+    validations:
+      required: true
+  - type: textarea
+    id: proposed_solution
+    attributes:
+      label: Proposed solution
+      description: Describe the behavior/API/CLI change you would like to see
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: What are you doing today, or what other options did you consider?
+      placeholder: PWAs, Flatpak web apps, manual `.desktop` entries, etc.
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope / rollout thoughts (optional)
+      description: If relevant, suggest MVP scope or phased rollout
+      placeholder: Could start as..., later evolve into...
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: I described the problem, not only the implementation idea
+          required: true
+        - label: I checked existing issues/discussions for duplicates
+          required: true
+
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -46,6 +46,10 @@ cargo test
 cargo check
 ```

+## Maintainer Notes (Repo Meta / Triage)
+
+Maintainers can use `docs/maintainer-notes.md` for the current label strategy and issue triage conventions during the alpha phase.
+
 ## Manual Smoke Test (Recommended for Behavior Changes)

 If your change affects build/install/list/remove behavior, run a quick smoke test:
--- a/5
+++ b/5
@@ -0,0 +1,5 @@
+REPO ?= spalencsar/deskify
+
+.PHONY: labels
+labels:
+	./scripts/setup-github-labels.sh $(REPO)
--- a/README.md
+++ b/README.md
@@ -14,28 +14,81 @@

 ---

-## ⚡ Why deskify?
+## Why Deskify Exists

-The original [Nativefier](https://github.com/nativefier/nativefier) project (Node.js/Electron) was an incredible tool, but it is now unmaintained and deprecated. Furthermore, packaging an entire Chromium V8 engine for *every single web app* you create consumes massive amounts of RAM and disk space.
+Web apps are now core tools, but Linux desktops still treat them like second-class citizens.

-**deskify** solves this by leveraging [Tauri](https://tauri.app/). Instead of bundling a heavy browser engine, it uses your native system webview (e.g., `webkit2gtk` on Linux). 
+- Electron-based wrappers solve distribution, but often at high RAM/disk cost.
+- PWAs help in some browsers, but desktop integration is inconsistent across environments.
+- The original [Nativefier](https://github.com/nativefier/nativefier) proved the need, but it is now unmaintained.

-## 🚧 Project Status (Alpha / Early MVP)
+`deskify` takes a Linux-first approach: it turns a website into a native-feeling desktop app using [Tauri](https://tauri.app/) and the system webview (for example `webkit2gtk`) instead of bundling a full browser engine per app.
+
+## How Deskify Works Today (Alpha / MVP)

 `deskify` is ready for public use and testing as an **early MVP**, but it is **not production-hardened yet**.

 - **Platform scope:** Linux only
- **Build model:** `deskify` compiles a local Tauri wrapper app on your machine
- **First build can take a while:** Rust crates + Tauri build steps may need to compile
- **Test coverage:** currently limited (core behavior is implemented, but automated coverage is still growing)
+- **Current architecture:** one generated Tauri wrapper project per app
+- **Build model:** `deskify` compiles the wrapper locally on your machine
+- **Why this MVP design:** simpler debugging, isolated failures, low contributor complexity
+- **Tradeoff:** build time and distro-specific setup issues become user-facing
+- **Test coverage:** currently limited (core behavior is implemented, automated coverage is growing)
+
+### MVP Architecture (Today)
+
+```mermaid
+flowchart TD
+    A[deskify CLI] --> B[Generate temporary Tauri wrapper project]
+    B --> C[Fetch or copy icon]
+    C --> D[Write tauri.conf.json + source files]
+    D --> E[Run cargo tauri build locally]
+    E --> F[Install binary to local executable dir]
+    F --> G[Install icon + .desktop entry]
+    G --> H[Launch from Linux app menu]
+```

 ### Known Limitations
+
 - Requires Tauri/Linux system dependencies to be installed locally before `deskify build`
 - Generated app build success can vary by distro/system setup (WebKitGTK/Tauri prerequisites)
 - No official cross-platform support (Windows/macOS) yet
 - GitHub Releases / binary automation for `deskify` itself may lag behind source updates during early MVP

-### 🌟 Features
+## Where Deskify Is Going
+
+Deskify aims to make web applications **first-class Linux desktop applications**.
+
+Planned evolution (direction, not promise):
+
+- Shared runtime model for multiple apps
+- Per-app config and icon installs without full rebuilds
+- Stronger Linux desktop integration (deployment, automation, kiosk/admin workflows)
+- Better distro compatibility guidance and troubleshooting
+
+The current per-app build approach is intentional for the MVP. The goal is to keep it simple now while making the longer-term direction visible.
+
+### Planned Evolution (Concept)
+
+```mermaid
+flowchart TD
+    A[deskify CLI] --> B[deskify runtime binary]
+    A --> C[App config files]
+    A --> D[Icons + .desktop entries]
+    C --> E[apps/chatgpt.json]
+    C --> F[apps/netflix.json]
+    B --> G[Load app config at launch]
+    G --> H[Open site in system webview]
+    D --> I[Linux app menu integration]
+```
+
+## Why Not Just Use Flatpak Web Apps / PWAs / Electron?
+
+- **Electron wrappers:** powerful, but often heavy for simple single-site desktop apps
+- **PWAs:** useful when available, but integration and behavior vary by browser/desktop environment
+- **Flatpak web app approaches:** can be valid, but `deskify` targets a CLI-driven, system-native, admin-friendly workflow with minimal runtime overhead
+
+### Key Features
 - **Extremely Lightweight:** Generated binaries are tiny (~4-6 MB) and RAM consumption is minimal.
 - **Automatic Icon Fetching:** Scrapes high-quality 128x128 favicons automatically using the Google Favicon API.
 - **XDG-Compliant System Integration:** Safely creates `.desktop` entries in `~/.local/share/applications` and manages application icons in `~/.local/share/icons/hicolor/`.
@@ -139,6 +192,7 @@ You can view all applications generated by `deskify`:
 deskify list
 ```
 *Output:*
+
 ```text
 Installed Deskify Apps:
 - ChatGPT (Internal ID: chatgpt)
@@ -179,7 +233,7 @@ Expected: clean validation error and no unintended file deletion.
 - Start with **source-first** releases (repository + tags)
 - Add automated binary releases later via GitHub Actions

-For the first public launch, tagging `v0.1.0-alpha.1` is a sensible default.
+For the current public alpha, use `v0.1.0-alpha.2` (and continue with `v0.1.0-alpha.N` for follow-up releases).

 ---

--- a/docs/github-labels.json
+++ b/docs/github-labels.json
@@ -0,0 +1,72 @@
+[
+  {
+    "name": "architecture/runtime",
+    "color": "5319E7",
+    "description": "Runtime model, shared runtime, config-based apps, install model evolution"
+  },
+  {
+    "name": "distro-compat",
+    "color": "D93F0B",
+    "description": "Distro-specific build/runtime issues and environment differences"
+  },
+  {
+    "name": "integration",
+    "color": "0E8A16",
+    "description": "Desktop integration topics (.desktop, icons, launchers, window class behavior)"
+  },
+  {
+    "name": "icons",
+    "color": "FBCA04",
+    "description": "Favicon fetching, icon parsing, icon quality, and fallback behavior"
+  },
+  {
+    "name": "good first issue",
+    "color": "7057FF",
+    "description": "Scoped tasks suitable for first-time contributors"
+  },
+  {
+    "name": "needs testing",
+    "color": "BFDADC",
+    "description": "Behavior change needs manual or wider validation across systems"
+  },
+  {
+    "name": "design decision",
+    "color": "1D76DB",
+    "description": "Affects long-term architecture or product direction"
+  },
+  {
+    "name": "docs",
+    "color": "0075CA",
+    "description": "README, CONTRIBUTING, examples, troubleshooting, and release notes"
+  },
+  {
+    "name": "bug",
+    "color": "D73A4A",
+    "description": "Incorrect behavior or regression"
+  },
+  {
+    "name": "enhancement",
+    "color": "A2EEEF",
+    "description": "Feature or improvement request"
+  },
+  {
+    "name": "ci",
+    "color": "C5DEF5",
+    "description": "GitHub Actions, release workflows, and build checks"
+  },
+  {
+    "name": "feature",
+    "color": "84B6EB",
+    "description": "User-facing functionality addition (release note category)"
+  },
+  {
+    "name": "fix",
+    "color": "E99695",
+    "description": "Behavior correction or bug fix (release note category)"
+  },
+  {
+    "name": "chore",
+    "color": "FEF2C0",
+    "description": "Maintenance tasks and non-user-facing housekeeping"
+  }
+]
--- a/docs/maintainer-notes.md
+++ b/docs/maintainer-notes.md
@@ -0,0 +1,46 @@
+# Maintainer Notes
+
+This document captures lightweight repo-management conventions for `deskify` during the alpha/MVP phase.
+
+## Issue Labels (Recommended)
+
+Use labels to make project direction visible and to reduce triage friction.
+
+- `architecture/runtime` - runtime model, shared runtime, config-based apps, install model evolution
+- `distro-compat` - distro-specific build/runtime issues (WebKitGTK, packaging prerequisites, environment differences)
+- `integration` - desktop integration topics (`.desktop`, icons, launchers, window class behavior)
+- `icons` - favicon fetching, icon parsing, icon quality/fallback behavior
+- `good first issue` - scoped tasks suitable for first-time contributors
+- `needs testing` - behavior change needs manual or wider validation across systems
+- `design decision` - issue/PR affects long-term architecture or product direction
+- `docs` - README, CONTRIBUTING, examples, troubleshooting, release notes
+- `bug` - incorrect behavior or regression
+- `enhancement` - feature or improvement request
+- `ci` - GitHub Actions, release workflows, build checks
+
+Label definitions for GitHub setup are stored in `docs/github-labels.json`.
+If you use GitHub CLI, `scripts/setup-github-labels.sh <owner/repo>` will create/update them.
+
+## Triage Heuristics (Alpha)
+
+- Prefer labeling directionally first (`architecture/runtime`, `distro-compat`, `integration`) before priority.
+- Use `design decision` early when a discussion can create long-term constraints.
+- Add `needs testing` to changes that touch build/install/remove flows or desktop integration behavior.
+- Distinguish user-environment issues from code bugs (`distro-compat` + details) to avoid misclassifying support reports.
+
+## Release Notes Categories (Suggested Mapping)
+
+- `feature`, `enhancement` -> user-facing functionality additions
+- `fix`, `bug` -> behavior corrections and regressions
+- `docs` -> documentation changes
+- `chore`, `ci` -> maintenance and pipeline work
+
+## Maintainer Framing (README / Issues)
+
+During alpha, consistently frame Deskify as:
+
+- a Linux-first web app integration tool
+- an early MVP with intentional per-app build architecture
+- a project with a visible evolution path toward runtime/config-based installs
+
+This helps avoid "Nativefier clone" framing as the default community label.
--- a/scripts/setup-github-labels.sh
+++ b/scripts/setup-github-labels.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if ! command -v gh >/dev/null 2>&1; then
+  echo "Error: GitHub CLI ('gh') is not installed." >&2
+  exit 1
+fi
+
+repo="${1:-}"
+labels_file="${2:-docs/github-labels.json}"
+
+if [[ -z "${repo}" ]]; then
+  echo "Usage: $0 <owner/repo> [labels-json-path]" >&2
+  echo "Example: $0 spalencsar/deskify" >&2
+  exit 1
+fi
+
+if [[ ! -f "${labels_file}" ]]; then
+  echo "Error: labels file not found: ${labels_file}" >&2
+  exit 1
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "Error: 'jq' is required to read ${labels_file}." >&2
+  exit 1
+fi
+
+echo "Syncing labels to ${repo} using ${labels_file} ..."
+
+jq -c '.[]' "${labels_file}" | while IFS= read -r label; do
+  name="$(jq -r '.name' <<<"${label}")"
+  color="$(jq -r '.color' <<<"${label}")"
+  description="$(jq -r '.description' <<<"${label}")"
+
+  if gh label edit "${name}" --repo "${repo}" --color "${color}" --description "${description}" >/dev/null 2>&1; then
+    echo "Updated: ${name}"
+  else
+    gh label create "${name}" --repo "${repo}" --color "${color}" --description "${description}" >/dev/null
+    echo "Created: ${name}"
+  fi
+done
+
+echo "Done."