从功能开发到开源维护：一个 Python 可视化项目的 Git 分支、维护文件与 PR 流程实践

摘要

很多项目在初期只关注"功能能不能跑"，但当项目准备放到 GitHub 上公开维护时，仅有功能代码是不够的。一个相对规范的开源项目，还需要具备清晰的分支管理、合理的 .gitignore、维护文档、Issue/PR 模板、基础测试、GitHub Actions 自动检查，以及可追踪的提交和 Pull Request 流程。

本文以一个 Python 项目维护过程为例，整理从本地分支创建、Git 推送、代理问题排查，到补充开源维护文件、提交 PR 的完整实践流程。

一、为什么项目需要"维护型整理"

在实际开发中，一个项目往往会经历三个阶段：

功能能跑
代码可读、可复现
项目可维护、可协作、可开源

很多学生项目、课程项目、个人开源项目停留在第一阶段：代码能运行，但缺少维护结构。例如：

没有 .gitignore，缓存文件、虚拟环境、输出视频都可能被提交；
没有 LICENSE，别人不知道能不能使用；
没有 CONTRIBUTING.md，别人不知道如何贡献代码；
没有 CHANGELOG.md，项目变更不可追踪；
没有 GitHub Actions，无法自动检查项目是否还能编译；
没有测试目录，核心函数改坏了也无法及时发现；
README 写得很长，但缺少运行、贡献、维护入口。

因此，项目维护的目标不是盲目增加功能，而是让项目变得更稳定、更可信、更容易被别人理解和协作。

二、维护前先确认仓库状态

在开始维护之前，首先要确认当前目录是不是正确的 Git 仓库。

例如项目路径是：

复制代码

cd "D:\大学\武术\Kungfu"

查看远程仓库：

复制代码

git remote -v

如果输出类似：

复制代码

origin  https://github.com/whilefog233/wushu_motion_visualizer.git (fetch)
origin  https://github.com/whilefog233/wushu_motion_visualizer.git (push)

说明当前目录确实绑定到了目标 GitHub 仓库。

再查看当前分支和状态：

复制代码

git status -sb
git branch --show-current

git status -sb 常见输出：

复制代码

## codex/muscle-visualizer...origin/codex/muscle-visualizer [ahead 1]

这表示本地分支比远程分支多 1 个提交，需要 push 到远程。

如果没有任何输出，需要进一步检查当前目录是否真的在 Git 仓库内：

复制代码

git rev-parse --is-inside-work-tree
git rev-parse --show-toplevel

三、创建维护分支

维护型改动最好不要直接写在主分支上，也不要和功能开发混在同一个分支里。

可以创建一个独立维护分支：

复制代码

git checkout -b maintenance/local-polish

如果分支已经存在，则切换过去：

复制代码

git checkout maintenance/local-polish

确认当前分支：

复制代码

git branch --show-current

期望输出：

复制代码

maintenance/local-polish

这种命名方式的含义是：

maintenance：这是维护型分支；
local-polish：主要做本地项目整理、文档补充、工程规范优化。

这样后续在 GitHub 上创建 PR 时，别人能很清楚地知道这个分支不是大功能开发，而是项目维护整理。

四、常见 GitHub 推送失败：DNS 和代理问题

在国内网络环境下，推送 GitHub 时经常遇到：

复制代码

fatal: unable to access 'https://github.com/...': Could not resolve host: github.com

或者 SSH 方式报错：

复制代码

ssh: Could not resolve hostname github.com: Name or service not known

这类问题的核心通常不是 Git 权限，而是本机无法解析 github.com。

可以先测试 DNS：

复制代码

nslookup github.com

如果出现：

复制代码

DNS request timed out.

说明 DNS 解析存在问题。

如果使用代理软件，需要确认本地代理端口。比如有些软件界面会显示：

复制代码

SOCKS5/HTTP 端口：7897

这时不能写成 7890，而应该使用真实端口 7897。

查看端口是否监听：

复制代码

netstat -ano | findstr :7897

配置 Git 代理：

复制代码

git config --global http.proxy http://127.0.0.1:7897
git config --global https.proxy http://127.0.0.1:7897

如果本机 DNS 解析失败，更推荐使用 socks5h，让代理端去解析域名：

复制代码

git config --global http.proxy socks5h://127.0.0.1:7897
git config --global https.proxy socks5h://127.0.0.1:7897

然后推送：

复制代码

git push -u origin maintenance/local-polish

注意：如果远程地址是 SSH 格式：

复制代码

git@github.com:用户名/仓库名.git

那么 Git 的 http.proxy 配置一般不会生效。此时建议先切回 HTTPS：

复制代码

git remote set-url origin https://github.com/whilefog233/wushu_motion_visualizer.git

五、维护型文件应该添加哪些

一个规范开源项目，至少应该补充以下几类维护文件。

1. `.gitignore`

.gitignore 用来忽略不应该进入 Git 仓库的文件，例如：

复制代码

# Python
__pycache__/
*.py[cod]
*.pyo
*.pyd

# Virtual environments
.venv/
venv/
env/

# Logs
*.log

# Local config
.env
.env.local
.streamlit/secrets.toml

# Build outputs
build/
dist/
*.egg-info/

# Test/cache
.pytest_cache/
.mypy_cache/
.ruff_cache/

# Media outputs
outputs/
results/
*.mp4
*.avi
*.mov
*.zip

# OS / IDE
.DS_Store
Thumbs.db
.vscode/
.idea/

对于视频分析类项目尤其要注意：输出视频、临时图片、缓存文件不应该随便提交到 Git。

2. `LICENSE`

如果项目打算公开，必须明确许可证。常见选择是 MIT License。

示例：

复制代码

MIT License

Copyright (c) 2026 whilefog233

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files...

没有许可证的仓库，别人严格来说并不能明确知道是否可以使用、修改或分发。

3. `CONTRIBUTING.md`

这个文件用于说明别人如何参与贡献。建议包含：

如何安装依赖；
如何运行项目；
如何提交 Issue；
如何提交 Pull Request；
项目定位边界；
不接受哪些夸大功能描述。

例如，对于武术动作可视化类项目，可以明确写：

复制代码

This project focuses on Wushu motion skeleton visualization, motion data display, and coach-assisted observation.

Please do not describe this project as:
- an automatic Wushu scoring system;
- a medical diagnostic tool;
- a real muscle activation measurement system;
- a verified biomechanics evaluation system.

这样可以防止 README 或后续 PR 把项目包装得过度夸张。

4. `CHANGELOG.md`

CHANGELOG.md 用来记录项目变更。

基础结构可以这样写：

复制代码

# Changelog

## Unreleased

### Added
- Added skeleton visualization workflow.
- Added video analysis mode.
- Added real-time camera mode.
- Added basic motion metrics.
- Added open-source maintenance files.

### Changed
- Improved README structure and project positioning.

### Fixed
- Improved handling of local generated files through `.gitignore`.

这能让项目变化更可追踪。

5. `SECURITY.md`

安全文档可以很简单：

复制代码

# Security Policy

If you discover a security issue, please do not publish sensitive details in a public issue.

Instead, contact the maintainer privately or open a minimal report without exposing credentials, tokens, private data, or exploit details.

重点是提醒不要把 token、密钥、隐私数据发到公开 Issue。

6. `CODE_OF_CONDUCT.md`

行为准则不用写得过度复杂，简洁即可：

复制代码

# Code of Conduct

This project expects all contributors to communicate respectfully and constructively.

Please avoid:
- personal attacks;
- harassment;
- offensive language;
- unrelated arguments;
- intentionally misleading claims.

Discussions should stay focused on project quality, documentation, reproducibility, and maintainability.

7. PR 模板

路径：

复制代码

.github/pull_request_template.md

内容可以包括：

复制代码

## Summary

Briefly describe what this pull request changes.

## Changes

- 
- 
- 

## Validation

- [ ] I ran the project locally
- [ ] I ran relevant tests
- [ ] I checked documentation updates

## Checklist

- [ ] No large generated files are included
- [ ] No secrets or private files are included
- [ ] The project capability is not exaggerated
- [ ] README or docs are updated if needed

这样可以让每次 PR 更规范。

8. Issue 模板

Bug 模板路径：

复制代码

.github/ISSUE_TEMPLATE/bug_report.md

示例：

复制代码

---
name: Bug report
about: Report a reproducible problem
title: "[Bug] "
labels: bug
---

## Description

Describe the problem clearly.

## Steps to Reproduce

1. 
2. 
3. 

## Expected Behavior

What did you expect to happen?

## Actual Behavior

What actually happened?

## Environment

- OS:
- Python version:
- Browser:
- Camera device, if related:

## Logs or Screenshots

Paste logs or screenshots here.

功能请求模板：

复制代码

.github/ISSUE_TEMPLATE/feature_request.md

示例：

复制代码

---
name: Feature request
about: Suggest an improvement
title: "[Feature] "
labels: enhancement
---

## Background

Why is this feature needed?

## Proposed Solution

Describe the expected behavior.

## Project Scope Check

Does this feature fit the project scope of skeleton visualization, motion data display, or coach-assisted observation?

## Alternatives

Describe any alternatives considered.

9. GitHub Actions

路径：

复制代码

.github/workflows/python-check.yml

基础配置：

复制代码

name: Python Check

on:
  push:
  pull_request:

jobs:
  python-check:
    runs-on: ubuntu-latest

    strategy:
      matrix:
        python-version: ["3.10", "3.11"]

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
          pip install pytest

      - name: Compile source files
        run: |
          if [ -f app.py ] && [ -d src ]; then
            python -m compileall app.py src
          elif [ -d src ]; then
            python -m compileall src
          else
            python -m compileall .
          fi

      - name: Run tests if available
        run: |
          if [ -d tests ]; then
            pytest
          else
            echo "No tests directory found. Skipping pytest."
          fi

这个 workflow 做三件事：

安装依赖；
检查 Python 文件能否编译；
如果存在 tests/，则运行 pytest。

即使项目测试还不完善，也可以先建立基础 CI。

10. docs 维护文档

建议添加：

复制代码

docs/MAINTENANCE.md
docs/ROADMAP.md
docs/camera_troubleshooting.md
docs/metrics.md

docs/MAINTENANCE.md 可以说明项目维护原则：

复制代码

# Maintenance Guide

This project prioritizes:

- reproducible setup;
- clear documentation;
- stable visualization workflow;
- lightweight tests;
- safe handling of local files;
- realistic project scope.

Acceptable contributions:

- documentation improvements;
- tests;
- camera error handling;
- visualization stability improvements;
- metric explanation updates;
- lightweight refactoring.

Not accepted for now:

- exaggerated AI scoring claims;
- medical diagnosis claims;
- real muscle activation claims without validated sensors;
- large generated media files;
- unrelated features.

docs/ROADMAP.md 可以说明路线图：

复制代码

# Roadmap

## Completed

- [x] Video upload analysis
- [x] Skeleton visualization
- [x] Real-time camera mode
- [x] Basic motion metrics
- [x] README improvements

## Planned

- [ ] Demo screenshots
- [ ] Sample outputs
- [ ] Export analysis package
- [ ] Camera troubleshooting improvements
- [ ] Unit tests for core metrics
- [ ] Manual action segment tagging

六、用 Codex 辅助添加维护文件

如果使用 Codex 这类代码助手，可以直接给它明确任务，不要让它自由发挥。

可以这样描述：

复制代码

请在当前仓库中添加一批开源维护文件，不要修改核心功能代码，不要做大规模重构。

目标：让项目看起来更像一个规范维护中的开源项目。

请添加或完善以下文件：

1. .gitignore
2. LICENSE，使用 MIT License
3. CONTRIBUTING.md
4. CHANGELOG.md
5. SECURITY.md
6. CODE_OF_CONDUCT.md
7. .github/pull_request_template.md
8. .github/ISSUE_TEMPLATE/bug_report.md
9. .github/ISSUE_TEMPLATE/feature_request.md
10. .github/workflows/python-check.yml
11. docs/MAINTENANCE.md
12. docs/ROADMAP.md

要求：
- 只做维护文件和轻量 README 链接更新；
- 不要删除现有功能；
- 不要新增大型依赖；
- 不要提交视频、模型、大型数据文件；
- 不要夸大项目能力；
- 完成后列出新增和修改的文件；
- 最后运行 git status -sb 和基础验证命令。

给 AI 工具任务时，重点是限定边界：

不要大规模重构；
不要改核心逻辑；
不要引入新功能；
不要添加虚假描述；
不要提交大文件；
最后必须总结修改内容。

七、检查修改结果

Codex 或自己改完后，不要立刻提交，先检查状态。

复制代码

git status -sb

查看修改统计：

复制代码

git diff --stat

查看具体变化：

复制代码

git diff

如果看到以下文件被加入，需要特别检查：

复制代码

*.mp4
*.avi
*.mov
*.zip
*.pt
*.onnx
*.pkl
.env
.streamlit/secrets.toml
__pycache__/
.venv/

这些一般不应该提交。

八、运行基础验证

Python 项目至少做一次编译检查：

复制代码

python -m compileall app.py src

如果存在 tests/ 目录，则运行：

复制代码

pytest

如果没有安装 pytest：

复制代码

pip install pytest
pytest

如果项目是 Streamlit 项目，可以额外测试启动：

复制代码

streamlit run app.py

这个步骤不是为了做复杂测试，而是为了确认维护文件的修改没有破坏项目的基本运行结构。

九、提交维护改动

确认无误后，提交：

复制代码

git add .
git commit -m "chore: add project maintenance files"

建议使用 chore 类型，因为这是项目维护类改动，不是新功能。

常见提交类型：

复制代码

feat: 新功能
fix: 修复问题
docs: 文档修改
test: 测试相关
chore: 工程维护
refactor: 重构
ci: CI 配置

本次比较适合：

复制代码

chore: add project maintenance files

或者：

复制代码

docs: add open source maintenance documents

十、推送到远程分支

确认当前分支：

复制代码

git branch --show-current

如果当前分支是：

复制代码

maintenance/local-polish

推送：

复制代码

git push -u origin maintenance/local-polish

如果使用的是功能分支，例如：

复制代码

codex/muscle-visualizer

则推送：

复制代码

git push -u origin codex/muscle-visualizer

十一、创建 Pull Request

推送成功后，进入 GitHub 仓库页面，创建 PR。

PR 标题可以写：

复制代码

Add project maintenance files and checks

PR 描述：

复制代码

## Summary

This PR adds basic open-source maintenance files and project checks.

## Changes

- Added `.gitignore`
- Added license and contribution documents
- Added changelog and security policy
- Added issue and pull request templates
- Added GitHub Actions workflow
- Added maintenance and roadmap documentation
- Updated README links where appropriate

## Validation

- Ran `python -m compileall app.py src`
- Ran `pytest` if tests are available

## Notes

This PR does not change the core feature scope. The project remains focused on motion visualization, motion data display, and coach-assisted observation.

如果 GitHub 显示：

复制代码

Able to merge

说明没有冲突，可以正常合并。

十二、维护型 PR 的价值

维护型 PR 看似没有增加新功能，但它对开源项目非常重要。

它能带来：

更清晰的项目边界
更规范的协作流程
更少的垃圾文件提交
更容易被别人运行和贡献
更强的工程可信度
更容易通过 GitHub 展示项目质量
更适合长期维护

尤其对于个人开源项目来说，维护文件、CI、测试、README、Issue 模板、PR 模板这些内容，会显著提升仓库的专业度。

总结

项目维护不是简单地"继续加功能"，而是让项目从"能跑"变成"可复现、可协作、可维护"。

一次比较完整的维护流程通常包括：

复制代码

确认仓库状态
创建维护分支
补充 .gitignore
添加 LICENSE
添加 CONTRIBUTING.md
添加 CHANGELOG.md
添加 SECURITY.md
添加 CODE_OF_CONDUCT.md
添加 Issue / PR 模板
添加 GitHub Actions
补充 docs 文档
运行 compileall / pytest 验证
提交 commit
push 到远程分支
创建 Pull Request
合并维护改动

对于个人项目来说，完成这些内容后，仓库会明显更像一个正式开源项目，而不是一次性作业或临时 Demo。

维护的核心不是堆砌功能，而是提高项目的稳定性、可信度和协作质量。