GPEN社区贡献指南：Pull Request提交规范说明
1. 为什么需要规范的Pull Request
GPEN图像肖像增强项目自开源以来，已吸引众多开发者参与二次开发与功能优化。无论是修复一个图片修复时的边缘伪影问题，还是为批量处理模块增加进度条反馈，每一次代码贡献都在提升这个工具的实际价值。但混乱的PR（Pull Request）会让维护者难以快速判断改动意图、验证修改效果，甚至可能引入兼容性风险。
你可能遇到过这些情况：提交了一个参数调整的PR，却没说明为什么这个值更合理；修复了WebUI界面错位，但没附上修复前后的对比截图；或者新增了模型自动下载功能，却没更新使用手册文档。这些问题看似微小，但累积起来会显著拖慢整个项目的迭代节奏。
本指南不是为了设置门槛，而是帮你用最省力的方式，让自己的贡献被快速接纳、稳定运行，并真正帮到其他用户。毕竟，我们共同的目标不是“提交代码”，而是“让GPEN更好用”。
2. 提交前的必备检查清单
在点击“Create pull request”按钮之前，请花2分钟完成以下检查。这比后续反复修改PR要高效得多。
2.1 代码层面
- 功能可运行：本地完整测试过修改点，确保不破坏现有流程（例如：单图增强仍能出图、批量处理不会卡死）
- 无硬编码路径：避免出现
/root/run.sh这类绝对路径，改用相对路径或配置项读取 - 日志友好：新增逻辑中如有关键状态输出（如“模型加载完成”、“降噪强度应用为65”），请使用
print()或logging.info()，而非print("debug: ...") - 变量命名清晰：不使用
a,tmp,data1等模糊名称；推荐denoise_strength,is_skin_protected,batch_output_dir
2.2 文档与体验层面
- 界面文字统一：中文标点全角、无英文冒号混用（❌ “增强强度：0-100” → “增强强度：0–100”）；按钮文案动词开头（❌ “增强开始” → “开始增强”）
- 参数说明同步更新：若新增/修改了高级参数（如新增“肤色饱和度”滑块），必须同步更新
README.md中的参数表格和用户使用手册对应章节 - 截图真实有效：若PR涉及UI变更（如Tab页结构调整、新增提示框），请提供实际运行截图，而非PS效果图。截图需包含完整浏览器窗口边框，体现真实环境
2.3 安全与合规层面
- 不泄露敏感信息：检查代码中无硬编码微信ID、API密钥、本地路径等私有信息
- 保留版权标识：所有新增文件头部需包含标准版权声明（见下文模板），不得删除或修改原作者“科哥”署名及微信联系方式
- 不引入未授权依赖：新增Python包需在
requirements.txt中明确定义版本（如gradio==4.38.0），禁用pip install some-package式模糊安装
3. Pull Request标题与描述规范
一个好PR，从标题就开始讲清楚故事。它不是给机器看的，而是给正在喝咖啡、准备审核的维护者看的。
3.1 标题写法：一句话说清“改了什么+为什么”
| ❌ 不推荐 | 推荐 | 说明 |
|---|---|---|
fix bug | 修复批量处理中JPEG格式图片无法保存的问题 | 避免模糊词汇，明确问题场景与对象 |
add feature | 新增「肤色保护」开关，默认开启以防止高增强下肤色失真 | 说明功能价值与默认行为 |
update readme | 同步更新「高级参数」表格，补充「对比度」参数说明及推荐值范围 | 指向具体文档位置与修改点 |
3.2 描述内容：结构化呈现，节省双方时间
PR描述请严格按以下三段式组织（每段空一行）：
第一段：问题背景（Why）
用1–2句话说明这个改动解决的实际痛点。例如：“当前单图增强在处理暗光人像时，即使开启‘强力’模式，肤色仍易发灰发青，用户反馈修复后缺乏自然感。”
第二段：解决方案（What & How）
- 明确改动范围（如：“修改
webui.py第217行参数传递逻辑”、“新增skin_tone_preserve.py模块”） - 关键设计选择（如：“采用Lab色彩空间分离L通道与ab通道，仅对L通道做增强，ab通道保持原值”）
- 若有性能影响，注明（如：“处理耗时增加约0.8秒，但失真率下降62%”）
第三段：验证方式（How to test）
告诉维护者如何快速确认效果。例如：
- “上传任意一张暗光人像（如
test_images/dim_portrait.jpg）” - “将增强强度设为90，处理模式选‘强力’，开启‘肤色保护’”
- “对比输出图与原图，重点观察脸颊、额头区域肤色是否自然”
重要提醒：请勿在描述中写“已测试通过”“没问题”等主观断言。用可复现的操作步骤代替判断，这是工程协作的基本信任。
4. 代码变更实操示例
下面以一个真实高频需求为例，展示从问题发现到PR落地的完整链路——为「单图增强」页面增加处理耗时显示。
4.1 问题定位与方案设计
用户常抱怨“不知道还要等多久”，尤其在CPU模式下。当前界面仅显示“处理中…”文字，缺乏量化反馈。理想方案：在结果预览区下方动态显示“已处理：17.3秒”。
4.2 关键代码修改（精简示意）
# 文件：webui.py # 修改位置：enhance_single_image() 函数内 def enhance_single_image(image, strength, mode, denoise, sharpen): start_time = time.time() # ← 新增计时起点 # ... 原有处理逻辑（模型推理、后处理等） ... end_time = time.time() elapsed = round(end_time - start_time, 1) # ← 新增返回耗时信息（供前端显示） return processed_image, f"处理完成，耗时 {elapsed} 秒"// 文件：templates/index.html // 修改位置：结果展示区块 <div id="result-container"> <img id="output-image" src="" alt="增强结果"> <p id="process-time" class="text-sm text-gray-500 mt-2"></p> <!-- ← 新增时间显示容器 --> </div> <script> // 在Gradio回调成功后更新时间显示 gradioApp().on('load', () => { const timeDisplay = document.getElementById('process-time'); // 从后端返回的第二个值提取并显示 if (typeof gradioApp().state !== 'undefined') { timeDisplay.textContent = gradioApp().state[1] || ''; } }); </script>4.3 同步更新文档
在《用户使用手册》“二、功能说明 → Tab 1: 单图增强”末尾追加：
新增提示：处理完成后，界面将显示精确耗时（如“处理完成，耗时 18.4 秒”），便于您评估不同参数组合下的效率表现。
5. 社区协作礼仪与常见误区
技术开源的本质是人与人的协作。以下细节虽小，却极大影响合作体验。
5.1 请务必做到
- 及时响应评论：若维护者提出修改建议（如“请将日志级别改为
logging.debug()”），请在48小时内回复确认或说明原因，避免PR长期挂起 - 一次PR聚焦一事：不要在一个PR里同时修复bug、新增功能、重构UI。例如：“修复PNG透明通道丢失 + 新增JPEG压缩质量调节”应拆分为两个独立PR
- 尊重原有风格：项目中大量使用紫蓝渐变色（
#6366f1/#8b5cf6）、圆角卡片、Gradio默认组件样式。新增UI元素请保持视觉一致性，勿擅自引入新CSS框架
5.2 请避免的典型错误
- 提交编译产物：勿提交
dist/、__pycache__/、.gradio/等生成目录，它们会污染Git历史且无意义 - 修改无关文件：不要因IDE自动格式化而提交整个
requirements.txt的行尾空格变更，只提交你真正修改的行 - 忽略中文语境：所有用户可见文案（按钮、提示、错误信息）必须为简体中文，禁用拼音缩写（如“bz”代替“编辑”）、英文混杂（如“点击Submit按钮”）
6. 总结：你的贡献，正在塑造GPEN的未来
提交一个符合规范的PR，本质上是在完成一次微型产品交付：你定义了问题、设计了解决方案、验证了效果、并为用户提供了清晰的使用说明。这比单纯写代码更接近工程师的核心能力。
当你下次打开GPEN WebUI，看到自己提交的功能被成百上千人日常使用——那个在「高级参数」里默默生效的肤色保护开关，那个在批量处理页底部跳动的实时耗时数字，那个被用户截图分享到朋友圈的惊艳修复效果——你会真切感受到，开源不是单打独斗，而是无数双手共同托起的一束光。
现在，就从检查你的下一个PR开始吧。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
