guzhujushi
5319589dfd
审查并精简 ChatGPT 的建库建议后落地的第一版骨架，只定接口不写实现。 - 建议审查：14 个包 → 7 个；约 250 个函数 → 约 40 个；5 个 Result 类 → 1 个 （docs/01-suggestion-review.md） - docs/：架构、路线图（含永久不做清单）、环境、Git 工作流、函数卡片模板 - src/mcm_toolkit/：core / data / stats / models / solve / decision / viz 共 23 个模块，均为签名 + docstring + NotImplementedError - tests/：9 个文件，其中 test_api_surface.py 已通过（20 passed） - examples/ problems/ notebooks/ figures/ tables/ 骨架 - pyproject.toml（核心依赖 4 个 + 6 组 extras）、environment.yml - scripts/：setup-venv.ps1（ASCII + LF）、setup-conda.ps1、doctor.ps1 - 环境：.venv（system-site-packages）与 conda 环境 mcm-toolkit 均已建好， 数值栈版本与 base 完全对齐（numpy 2.4.6 / scipy 1.18.1 / pandas 3.0.6，MKL 后端）
138 lines
3.4 KiB
Markdown
138 lines
3.4 KiB
Markdown
# Git 工作流与远程托管
|
|
|
|
> 本仓库目前是**本地仓库**，之后托管到你自己的 Gitea。
|
|
|
|
---
|
|
|
|
## 一、仓库约定
|
|
|
|
### 行尾
|
|
|
|
由 `.gitattributes` 强制：**仓库内一律 LF**，checkout 时不做自动转换。
|
|
|
|
原因：AGENTS.md 要求 shell 脚本 UTF-8 无 BOM + LF；而这个仓库会被队友在
|
|
Windows / WSL / Linux 上 clone。不固定行尾的话，每次提交都会出现
|
|
"整个文件都变了"的假 diff，review 时根本看不出真实改动。
|
|
|
|
例外：`*.bat` / `*.cmd` 保持 CRLF（cmd 解析需要）。
|
|
|
|
Windows 用户建议同时设：
|
|
|
|
```powershell
|
|
git config --global core.autocrlf false
|
|
git config --global core.eol lf
|
|
```
|
|
|
|
### 什么不入库
|
|
|
|
见 `.gitignore`。重点是三条：
|
|
|
|
| 忽略 | 为什么 |
|
|
|---|---|
|
|
| `.venv/`、`.conda/` | 环境可由 `scripts/setup-*.ps1` 重建，不该进版本库 |
|
|
| `problems/**/raw/`、`**/*.xlsx`、`problems/**/*.csv` | 赛题原始数据体积大、可重新下载；只提交**处理脚本和结论** |
|
|
| `figures/*.png`、`figures/*.pdf`、`tables/*.csv` | 中间产物。定稿的图请放进 `problems/<年份>_<题号>/figures/` 再提交 |
|
|
|
|
**判断标准：这个东西能不能由仓库里的其他文件重新生成？**
|
|
能 → 不入库。
|
|
|
|
---
|
|
|
|
## 二、日常提交
|
|
|
|
```powershell
|
|
git add -A
|
|
git commit -m "feat(stats): 实现 bootstrap_ci"
|
|
```
|
|
|
|
提交信息建议带模块前缀，方便以后回溯"这个函数是哪次加的"：
|
|
|
|
| 前缀 | 用途 |
|
|
|---|---|
|
|
| `feat(<模块>)` | 新增函数 / 功能 |
|
|
| `fix(<模块>)` | 修 bug |
|
|
| `test(<模块>)` | 只改测试 |
|
|
| `docs` | 只改文档 |
|
|
| `env` | 环境、依赖、脚本 |
|
|
| `chore` | 其他杂项 |
|
|
|
|
提交前跑一遍：
|
|
|
|
```powershell
|
|
.\scripts\doctor.ps1
|
|
```
|
|
|
|
它会同时检查 venv 和 conda 两套环境并跑测试。
|
|
|
|
---
|
|
|
|
## 三、推到自己的 Gitea
|
|
|
|
### 1. 在 Gitea 上建空仓库
|
|
|
|
不要勾选"初始化仓库"（不要生成 README / .gitignore / LICENSE），
|
|
否则首次 push 会冲突。
|
|
|
|
### 2. 加远程并推送
|
|
|
|
```powershell
|
|
cd D:\MCM&ICM_Toolkit
|
|
|
|
# 换成你自己的 Gitea 地址
|
|
git remote add origin https://git.你的域名/用户名/mcm-icm-toolkit.git
|
|
|
|
# 如果 Gitea 用的是自签证书，先在浏览器里访问一次并信任，或：
|
|
# git config --global http.sslBackend schannel
|
|
|
|
git branch -M main
|
|
git push -u origin main
|
|
```
|
|
|
|
### 3. 用 SSH（推荐，免密）
|
|
|
|
```powershell
|
|
ssh-keygen -t ed25519 -C "guzhu@mcm-toolkit"
|
|
Get-Content "$env:USERPROFILE\.ssh\id_ed25519.pub" | Set-Clipboard
|
|
# 粘贴到 Gitea → 设置 → SSH/GPG 密钥
|
|
|
|
git remote set-url origin git@git.你的域名:用户名/mcm-icm-toolkit.git
|
|
git push -u origin main
|
|
```
|
|
|
|
### 4. 如果不想公开
|
|
|
|
Gitea 建仓库时选 **Private**。队友通过
|
|
仓库设置 → 协作者 → 添加成员 授权。
|
|
|
|
---
|
|
|
|
## 四、给队友的说明
|
|
|
|
队友 clone 后只需要：
|
|
|
|
```powershell
|
|
git clone <你的仓库地址>
|
|
cd mcm-icm-toolkit
|
|
.\scripts\setup-venv.ps1 # 零下载，复用他们自己的 Anaconda base
|
|
.\scripts\doctor.ps1
|
|
```
|
|
|
|
`setup-venv.ps1` 用的是 `--system-site-packages`，所以他们本机得先有 Anaconda。
|
|
如果队友没有 Anaconda，让他走 `scripts/setup-conda.ps1`。
|
|
|
|
---
|
|
|
|
## 五、回滚
|
|
|
|
环境升级出问题时的回退手段：
|
|
|
|
```powershell
|
|
# conda 自己保留了 revision 历史
|
|
conda list -n base --revisions
|
|
conda install -n base --revision <N>
|
|
|
|
# 代码回滚
|
|
git log --oneline
|
|
git revert <commit>
|
|
```
|