deskify/docs/maintainer-notes.md

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.