RELEASE.md (6088B)
1 # Release Guide: PyPI & APT 패키지 배포
2
3 ## 1. PyPI 배포 (pipx 지원)
4
5 ### 1-1. PyPI 계정 생성
6 1. https://pypi.org/account/register/ 방문
7 2. 계정 생성 및 이메일 인증
8 3. (선택) 2FA 활성화 (권장)
9
10 ### 1-2. API 토큰 생성
11 1. https://pypi.org/manage/account/token/ 방문
12 2. "Add API token" 클릭
13 3. Token name: `uaf-upload`
14 4. Scope: "Entire account" (첫 업로드) 또는 "Project: uaf"
15 5. 생성된 토큰 복사 (다시 볼 수 없음!)
16
17 ### 1-3. TestPyPI에서 먼저 테스트 (권장)
18
19 ```bash
20 # TestPyPI 계정 생성: https://test.pypi.org/account/register/
21 # TestPyPI API 토큰 생성: https://test.pypi.org/manage/account/token/
22
23 # 빌드
24 python -m build
25
26 # 테스트 업로드
27 twine upload --repository testpypi dist/*
28
29 # Username: __token__
30 # Password: pypi-AgE... (복사한 토큰 전체)
31
32 # 테스트 설치
33 pipx install --index-url https://test.pypi.org/simple/ uaf
34
35 # 테스트 실행
36 sudo uaf --help
37 ```
38
39 ### 1-4. 정식 PyPI 업로드
40
41 ```bash
42 # 정식 업로드
43 twine upload dist/*
44
45 # Username: __token__
46 # Password: pypi-AgE... (복사한 토큰 전체)
47 ```
48
49 업로드 성공 후 URL: https://pypi.org/project/uaf/
50
51 ### 1-5. 전 세계 사용자가 설치 가능!
52
53 ```bash
54 # pipx로 설치 (권장)
55 pipx install uaf
56
57 # 또는 pip로 설치
58 pip install uaf
59
60 # 사용
61 sudo uaf
62 ```
63
64 ---
65
66 ## 2. APT 패키지 배포 (.deb)
67
68 ### 2-1. 필요한 도구 설치
69
70 ```bash
71 sudo apt install debhelper dh-python python3-all python3-setuptools
72 ```
73
74 ### 2-2. debian/ 디렉토리 구조 생성
75
76 ```bash
77 mkdir -p debian
78 cd debian
79 ```
80
81 다음 파일들을 생성해야 합니다:
82
83 #### `debian/control`
84
85 ```
86 Source: uaf
87 Section: net
88 Priority: optional
89 Maintainer: sqzer-x
90 Build-Depends: debhelper-compat (= 13),
91 dh-python,
92 python3-all,
93 python3-setuptools
94 Standards-Version: 4.6.0
95 Homepage: https://github.com/sqzer-x/uaf
96 Vcs-Git: https://github.com/sqzer-x/uaf.git
97
98 Package: uaf
99 Architecture: all
100 Depends: ${python3:Depends},
101 ${misc:Depends},
102 python3-scapy,
103 iw,
104 iproute2
105 Recommends: wireless-tools
106 Description: Real-time wireless access point scanner with active reconnaissance
107 UAF is a Linux CLI tool for discovering and analyzing WiFi access
108 points. It supports passive monitoring across 2.4/5/6 GHz bands and active
109 reconnaissance on open networks.
110 .
111 Features:
112 - Real-time AP discovery with channel hopping
113 - Security detection (WEP/WPA/WPA2/WPA3)
114 - Active scanning: DHCP, ARP, port scanning
115 - CSV/JSON export with scan results
116 ```
117
118 #### `debian/rules`
119
120 ```makefile
121 #!/usr/bin/make -f
122
123 export PYBUILD_NAME=uaf
124
125 %:
126 dh $@ --with python3 --buildsystem=pybuild
127 ```
128
129 #### `debian/changelog`
130
131 ```
132 uaf (1.0.0-1) unstable; urgency=medium
133
134 * Initial release
135 * Passive WiFi scanning with channel hopping
136 * Active reconnaissance on open networks
137 * CSV/JSON export support
138
139 -- sqzer-x Tue, 11 Feb 2026 22:00:00 +0900
140 ```
141
142 #### `debian/copyright`
143
144 ```
145 Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
146 Upstream-Name: uaf
147 Upstream-Contact: sqzer-x
148 Source: https://github.com/sqzer-x/uaf
149
150 Files: *
151 Copyright: 2026 sqzer-x
152 License: GPL-2.0-or-later
153
154 License: GPL-2.0-or-later
155 This program is free software; you can redistribute it and/or modify
156 it under the terms of the GNU General Public License as published by
157 the Free Software Foundation; either version 2 of the License, or
158 (at your option) any later version.
159 .
160 This program is distributed in the hope that it will be useful,
161 but WITHOUT ANY WARRANTY; without even the implied warranty of
162 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
163 GNU General Public License for more details.
164 .
165 On Debian systems, the complete text of the GNU General
166 Public License version 2 can be found in "/usr/share/common-licenses/GPL-2".
167 ```
168
169 #### `debian/compat`
170
171 ```
172 13
173 ```
174
175 ### 2-3. .deb 패키지 빌드
176
177 ```bash
178 # 프로젝트 루트에서
179 dpkg-buildpackage -us -uc -b
180
181 # 또는 debuild 사용
182 debuild -us -uc -b
183 ```
184
185 빌드 성공 후 상위 디렉토리에 `.deb` 파일이 생성됩니다:
186 ```
187 ../uaf_1.0.0-1_all.deb
188 ```
189
190 ### 2-4. 로컬 테스트
191
192 ```bash
193 # 설치
194 sudo dpkg -i ../uaf_1.0.0-1_all.deb
195
196 # 의존성 해결 (필요시)
197 sudo apt-get install -f
198
199 # 테스트
200 sudo uaf --help
201
202 # 제거
203 sudo apt remove uaf
204 ```
205
206 ### 2-5. GitHub Releases에 업로드
207
208 1. GitHub 저장소 → Releases → "Create a new release"
209 2. Tag: `v1.0.0`
210 3. Title: `UAF v1.0.0`
211 4. Description: Release notes 작성
212 5. `.deb` 파일 업로드 (Assets)
213 6. "Publish release" 클릭
214
215 사용자는 다음과 같이 설치:
216 ```bash
217 wget https://github.com/sqzer-x/uaf/releases/download/v1.0.0/uaf_1.0.0-1_all.deb
218 sudo dpkg -i uaf_1.0.0-1_all.deb
219 sudo apt-get install -f
220 ```
221
222 ### 2-6. PPA (Personal Package Archive) 생성 (고급)
223
224 Ubuntu 공식 저장소처럼 `apt install uaf`를 지원하려면:
225
226 1. Launchpad 계정 생성: https://launchpad.net/
227 2. PPA 생성: https://launchpad.net/~/+activate-ppa
228 3. GPG 키 생성 및 등록
229 4. 소스 패키지 빌드 & 업로드
230
231 자세한 가이드: https://help.launchpad.net/Packaging/PPA
232
233 ---
234
235 ## 3. 릴리스 체크리스트
236
237 배포 전 확인사항:
238
239 - [ ] 모든 테스트 통과 (`pytest tests/ -v`)
240 - [ ] README.md 업데이트 (기능, 설치 방법)
241 - [ ] CHANGELOG 작성
242 - [ ] 버전 번호 업데이트 (`pyproject.toml`)
243 - [ ] LICENSE 파일 확인
244 - [ ] GitHub 저장소 public으로 설정
245 - [ ] .gitignore 확인 (민감 정보 제외)
246
247 ---
248
249 ## 4. 문제 해결
250
251 ### PyPI 업로드 실패
252 - 이름 충돌: 다른 이름 선택
253 - 버전 충돌: 버전 번호 증가 후 재빌드
254 - 인증 실패: API 토큰 재확인
255
256 ### .deb 빌드 실패
257 - 의존성 부족: `debian/control` Dependencies 확인
258 - 권한 문제: `debian/rules`에 실행 권한 (`chmod +x debian/rules`)
259
260 ---
261
262 ## 5. 다음 릴리스 (v1.1.0)
263
264 향후 기능 추가 시:
265
266 1. 버전 번호 업데이트 (`pyproject.toml`, `debian/changelog`)
267 2. 패키지 재빌드 (`python -m build`, `dpkg-buildpackage`)
268 3. 업로드 (`twine upload dist/*`, GitHub Release)