kernalix7--winpodx/CONTRIBUTING.md

Contributing to WinPodX

English | 한국어

Thank you for your interest in contributing to WinPodX! This guide will help you get started.

Prerequisites

• Python 3.9+ (developed on 3.13; CI covers 3.9 / 3.10 / 3.11 / 3.12 / 3.13)
• FreeRDP 3+

Build

git clone https://github.com/kernalix7/winpodx.git
cd winpodx
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Test

# Run tests
pytest tests/ -v

# Lint
ruff check src/ tests/

# Format check
ruff format --check src/ tests/

pytest runs on a Linux CI runner and cannot exercise the Windows guest. Any change that touches the guest (config/oem/, scripts/windows/, the reverse-open shim, compose ports/QEMU args, the agent, install flow, RAIL launch) must also be smoke-tested against a real Windows guest before merge — see docs/RELEASE_TESTING.md for the guest-side smoke

• per-release checklist.

Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Write your changes following conventional commits
4. Submit a Pull Request

PR Checklist

Before submitting a PR, ensure the following:

• pytest tests/ -v passes
• ruff check src/ tests/ reports zero errors
• ruff format --check src/ tests/ passes
• Documentation is updated (if applicable)
• No hardcoded credentials or secrets

Commit Convention

This project follows Conventional Commits:

Prefix	Purpose
feat	New feature
fix	Bug fix
docs	Documentation changes
refactor	Code refactoring (no feature change)
test	Adding or updating tests
chore	Maintenance tasks (CI, deps, etc.)

Examples

feat: add Wayland display detection
fix: resolve DPI scaling on multi-monitor setups
docs: update installation instructions
refactor: simplify backend abstraction layer
test: add unit tests for UNC path conversion
chore: update ruff to 0.8.x

No AI tool co-author trailers

Do not add Co-authored-by: trailers that name AI tools / coding agents. This applies to all of:

• Co-authored-by: Cursor <cursoragent@cursor.com>
• Co-authored-by: Claude <noreply@anthropic.com> (and any other Anthropic email)
• Co-authored-by: Copilot <...> (any GitHub Copilot variant)
• Co-authored-by: <any other AI tool / agent identity>

You wrote the patch — the human author of record is you. AI tooling doesn't get co-authorship credit in this repo regardless of how much it contributed. If you forgot and a trailer slipped in, we'll ask you to amend (or, for already-merged PRs, propose a coordinated history-rewrite via a follow-up PR).

Human co-authors (e.g., a colleague who pair-programmed with you on the change) are fine and welcome — those should use real human identities + emails.

Writing release notes

Each version section in CHANGELOG.md (and docs/CHANGELOG.ko.md) starts with ### Highlights — a one-sentence headline followed by 3–6 scannable bullets. This is what users see at the top of the GitHub release page: release.yml extracts the version's section verbatim, so the first thing in the section is the first thing in the release body.

The detailed ### Added / ### Changed / ### Fixed bullets follow underneath. They're for archeology and exhaustive tracking, not first-read.

Skeleton:

## [X.Y.Z] - YYYY-MM-DD

### Highlights

**One-sentence headline.** Optional 1-2 sentence elaboration if needed.

- Most important user-visible change (one line, scannable)
- Second most important change
- (3-6 bullets max; no prose blocks)

### Added
- (detailed bullets)

### Changed
- (detailed bullets)

### Fixed
- (detailed bullets)

When cutting a release, also push the REL-vX.Y.Z marker tag — this is what fires release.yml (which builds the wheel + sdist, extracts the CHANGELOG section, and updates the GitHub release body). Without the REL- marker, the version tag (vX.Y.Z) triggers only the four packaging workflows (obs-publish.yml, rhel-publish.yml, debs-publish.yml, aur-publish.yml) but no wheel / sdist and no auto-extracted release body.

git tag vX.Y.Z <commit>
git tag REL-vX.Y.Z vX.Y.Z^{}    # dereference to commit to avoid a nested-tag warning
git push origin vX.Y.Z REL-vX.Y.Z

Crediting contributors in Highlights

When a Highlights bullet covers work that came from outside the maintainer (external PR or external bug report / feature request), credit the contributor inline. The convention:

Source	Suffix
External PR (someone else's commits)	(by @username, #PR)
External issue / feature request (maintainer wrote the code)	(reported by @username, #issue)
Both — external report and external PR by the same person	(by @username, #PR / #issue)

GitHub auto-renders both forms as the user's avatar + handle on the release page, so the recognition surfaces without extra work.

Example:

### Highlights

- Atomic Fedora flavours (Silverblue / Kinoite / Bazzite) now ship via the
  OBS repo with `rpm-ostree install --apply-live`. (by @Zeik0s, #163)
- LTSC IoT and Win10 LTSC pickable from Settings or `--win-version`.
  (reported by @gabe39, #178)
- Dynamic Desktop Window Resolution — Full Desktop sessions now resize
  the FreeRDP client window automatically. (by @Zeik0s, #202)
- Ubuntu 26.04 build target + Wayland-friendly Recommends split.
  (by @juampe, #206)
- `winpodx setup` rerun no longer overwrites the working Windows password
  and locks the user out of their guest. (reported by @tolistim, #216)
- Host-adaptive Windows-on-KVM tuning — `cfg.pod.tuning_profile = "auto"`
  detects host capability and applies `+invtsc` on x86_64 invariant-TSC
  CPUs. (reported by @ismikes, #215)
- Fedora 42 / 43 / 44 install snippet now uses dnf5 syntax (`dnf
  config-manager addrepo --from-repofile=<URL>`); the dnf4 form
  failed on Fedora 41 +. (reported by @payayas, #228)
- `install.sh` re-verifies `/dev/kvm` after the package install loop
  and refuses to proceed with an actionable BIOS / kernel-module /
  kvm-group diagnostic when hardware virtualisation is off. README
  gains a "Minimum requirements" section so users see the gating
  checks before they curl-install. (reported by @pnogaret2019-code,
  #220)
- `install.sh` picks `qemu-system-x86` (or `qemu-system-x86-hwe`)
  on Ubuntu 24.04+ / Debian 13 where `qemu-kvm` became a virtual
  package with no install candidate. Same probe pattern as the
  freerdp2 → freerdp3 selector. (reported by @n-osennij, #200)
- Tray UX overhaul: auto-spawned from GUI / CLI, bundled SVG so the
  indicator actually renders, Open Dashboard menu, Quit confirms +
  stops pod, install.sh marker suppresses spurious recovery
  notifications during Sysprep.

The "no AI tool co-author trailers" rule above is unrelated: it bans machine-generated attribution. Human contributors are credited liberally and explicitly.

Security

If you discover a security vulnerability, please follow the process described in SECURITY.md. Do NOT open a public issue.