kernalix7--winpodx/docs/CONTRIBUTING.ko.md

WinPodX 기여 가이드

English | 한국어

WinPodX에 관심을 가져 주셔서 감사합니다! 이 가이드는 기여를 시작하는 데 도움을 드립니다.

사전 요구 사항

• Python 3.9+ (3.13 에서 개발; CI 는 3.9 / 3.10 / 3.11 / 3.12 / 3.13 매트릭스)
• FreeRDP 3+

빌드

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

테스트

# 테스트 실행
pytest tests/ -v

# 린트
ruff check src/ tests/

# 포맷 검사
ruff format --check src/ tests/

pytest는 Linux CI 러너에서 돌며 Windows 게스트를 실행할 수 없습니다. 게스트를 건드리는 변경(config/oem/, scripts/windows/, reverse-open shim, compose 포트/QEMU args, 에이전트, 설치 흐름, RAIL 실행)은 머지 전 실제 Windows 게스트 스모크도 필요 — 게스트측 스모크 + 릴리즈별 체크리스트는 docs/RELEASE_TESTING.ko.md 참고.

워크플로우

1. 저장소를 포크합니다
2. 기능 브랜치를 생성합니다 (git checkout -b feat/my-feature)
3. Conventional Commits 규칙에 따라 변경 사항을 작성합니다
4. Pull Request를 제출합니다

PR 체크리스트

PR을 제출하기 전에 다음을 확인하세요:

• pytest tests/ -v 통과
• ruff check src/ tests/ 오류 없음
• ruff format --check src/ tests/ 통과
• 문서 업데이트 완료 (해당하는 경우)
• 하드코딩된 자격 증명 또는 비밀 정보 없음

커밋 규칙

이 프로젝트는 Conventional Commits를 따릅니다:

접두사	용도
feat	새로운 기능
fix	버그 수정
docs	문서 변경
refactor	코드 리팩토링 (기능 변경 없음)
test	테스트 추가 또는 업데이트
chore	유지보수 작업 (CI, 의존성 등)

예시

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

AI 툴 co-author 트레일러 금지

Co-authored-by: 트레일러에 AI 툴 / 코딩 에이전트 이름을 넣지 마세요. 다음 모두 해당:

• Co-authored-by: Cursor <cursoragent@cursor.com>
• Co-authored-by: Claude <noreply@anthropic.com> (및 다른 Anthropic 이메일)
• Co-authored-by: Copilot <...> (GitHub Copilot 모든 변종)
• Co-authored-by: <기타 AI 툴 / 에이전트 정체성>

패치를 작성한 건 당신입니다 — 정식 사람 author 는 당신. AI 툴이 얼마나 기여했든 이 repo 에서 co-author credit 받지 않습니다. 깜빡하고 트레일러가 들어갔다면 amend 요청하거나 (이미 머지된 PR 의 경우) 후속 PR 로 조정된 history-rewrite 를 제안합니다.

사람 co-author (예: 변경 사항을 함께 페어 프로그래밍한 동료) 는 환영 — 실제 사람 정체성 + 이메일 사용.

릴리스 노트 작성

CHANGELOG.md (그리고 docs/CHANGELOG.ko.md) 의 각 버전 섹션은 ### Highlights 로 시작합니다 — 한 줄 헤드라인 + 3–6 개 스캔 가능한 bullet. 이것이 GitHub 릴리스 페이지 맨 위에 보이는 내용입니다. release.yml 이 해당 버전 섹션을 verbatim 으로 추출해서 릴리스 body 에 넣기 때문에, 섹션 맨 앞에 있는 게 릴리스 본문 맨 앞에 옴.

자세한 ### Added / ### Changed / ### Fixed bullet 은 그 아래에. archeology 와 exhaustive tracking 용이지 first-read 용이 아님.

스켈레톤:

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

### Highlights

**한 줄 헤드라인.** 필요시 1-2 문장 추가 컨텍스트.

- 가장 중요한 사용자 가시적 변경 (한 줄, 스캔 가능)
- 두 번째 중요한 변경
- (최대 3-6 bullets; prose 블록 금지)

### Added
- (자세한 bullet)

### Changed
- (자세한 bullet)

### Fixed
- (자세한 bullet)

릴리스 컷할 때 REL-vX.Y.Z marker tag 도 같이 푸시 — 이것이 release.yml 을 fire 시킴 (wheel + sdist 빌드, CHANGELOG 섹션 추출, GitHub 릴리스 body 갱신). REL- marker 없으면 버전 태그 (vX.Y.Z) 가 4개 패키징 워크플로우 (obs-publish.yml, rhel-publish.yml, debs-publish.yml, aur-publish.yml) 만 trigger 하고 wheel / sdist 없음 + 자동 추출 릴리스 body 없음.

git tag vX.Y.Z <commit>
git tag REL-vX.Y.Z vX.Y.Z^{}    # nested-tag 경고 피하려고 commit 으로 dereference
git push origin vX.Y.Z REL-vX.Y.Z

Highlights 에서 기여자 표기

Highlights bullet 이 메인테이너 외부에서 온 작업 (외부 PR / 외부 버그 리포트 / feature request) 을 다룰 때, 인라인으로 기여자 크레딧을 표기. 컨벤션:

출처	접미사
외부 PR (다른 사람의 커밋)	(by @username, #PR)
외부 이슈 / feature request (코드는 메인테이너 작성)	(reported by @username, #issue)
둘 다 — 같은 사람의 외부 리포트 + 외부 PR	(by @username, #PR / #issue)

GitHub 가 두 형식 모두 릴리스 페이지에 user 아바타 + 핸들로 자동 렌더링 — 추가 작업 없이 크레딧이 노출됨.

예시:

### 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)

위의 "AI tool co-author trailers 금지" 룰과는 무관: 그것은 기계 생성 attribution 금지. 사람 기여자는 자유롭고 명시적으로 크레딧.

보안

보안 취약점을 발견한 경우, SECURITY.ko.md에 설명된 절차를 따라 주세요. 공개 이슈를 열지 마세요.