Phase 0 of expert feedback (#1~#11): infrastructure + design + 1차 fixes
Implementations (즉시 동작): - #1 crash logging: harness/crash_logger.py (sys.excepthook + threading + faulthandler, 회전 파일 logs/scanvas.log). main 진입점 통합. - #2 smooth curves (1차): gate_3d_builder ogee profile를 arc-length parametric CubicSpline로 4× densify (8pt→32pt, 36→132 cells, 60 FPS 안전). - #3 TIN colormap: matplotlib "terrain"의 파란색 범위 제거 → 짙은갈색→황토→ 모래→능선 LinearSegmentedColormap. 9 사이트 교체. 회귀 테스트 추가. - #5 uv: pyproject.toml + UV_GUIDE.md. base/[py313]/[dev]/[build] extras + hatchling. - #6,#7,#8 dev cycle infra: .pre-commit-config.yaml (ruff+secrets+위생), .gitea/workflows/ci.yml (Py3.11+3.13 matrix), tests/test_regressions.py (18 회귀 테스트, iter=1~7 fix 박제), CONTRIBUTING.md (Red→Green 알고리즘). Design docs (다음 세션 마이그레이션 청사진): - #4 UI/UX 전면 수정: UI_REDESIGN_PLAN.md (12 popup→1 inspector, vtkTkRenderWidget embedding 게이트, 4 phase × 7 sessions). - #10 Core/Plugin: ARCHITECTURE_PLAN.md (Core 14 / Plugin 7 구조물 + 2 렌더 + 1 QA, STRUCTURE_REGISTRY 확장, manifest 기반 디스커버리). - #11 perf hotspots: PERFORMANCE_BASELINE.md (19 핫스팟, P1: 타일 직렬DL 5~30s, 캡처 직렬 4.5~15s, numpy 벡터화 가능 Python loops, 텍스처 4회 반복read). Behavior preservation: ruff 0 errors, pytest 17 passed/1 skipped(bpy), import 33/33 OK on Py3.13.13. Item #2 P2/P3 곡선, #4 UI 마이그레이션, #10 Phase 1 추출, #11 P1 최적화는 차기 세션. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
127
CONTRIBUTING.md
Normal file
127
CONTRIBUTING.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# S-CANVAS 개발 사이클 (Red → Green)
|
||||
|
||||
> **피드백 #6/#7/#8**: 사용자가 명시한 개발 관리 원칙. 이 문서는 그 원칙을 코드화.
|
||||
|
||||
## 1. 개발 사이클 — Red → Green → Push
|
||||
|
||||
```
|
||||
[로컬] [원격]
|
||||
↓
|
||||
코드 작성/수정
|
||||
↓
|
||||
ruff check (자동 fix) ← Red 단계: 린트 위반 0
|
||||
↓
|
||||
pytest (회귀 + 단위) ← Red → Green 전환: 모든 테스트 통과
|
||||
↓
|
||||
git commit ← pre-commit hook이 ruff 재검사
|
||||
↓
|
||||
git push ← Gitea Actions가 ruff + pytest 재실행
|
||||
↓ 모두 Green 시에만 main에 머지
|
||||
[성공 → 다음 작업]
|
||||
[실패 → Red 복귀]
|
||||
```
|
||||
|
||||
**핵심 원칙**: Red가 켜진 상태로는 push 금지. main은 항상 Green.
|
||||
|
||||
## 2. 새 버그 발견 시 (피드백 #7)
|
||||
|
||||
> "버그가 식별되면 수정 후 재발하지 않도록 하는 알고리즘도 필요"
|
||||
|
||||
**알고리즘**:
|
||||
1. 버그 재현 코드 → `tests/test_regressions.py` 에 **먼저** 추가 (Red 상태).
|
||||
2. pytest 실행 → 새 테스트 fail 확인 (재현 확인).
|
||||
3. 수정 코드 작성 → pytest 통과 확인 (Green).
|
||||
4. commit (테스트 + 수정 함께).
|
||||
5. 이후 누군가가 같은 버그를 재도입하려 하면 → CI에서 즉시 catch.
|
||||
|
||||
이게 "재발 방지 알고리즘". 메모만 적는 게 아니라 **실행 가능한 가드**로.
|
||||
|
||||
## 3. 코드 퀄리티 장치 (피드백 #8)
|
||||
|
||||
| 단계 | 도구 | 무엇을 차단 |
|
||||
|---|---|---|
|
||||
| 작성 중 | ruff (LSP/IDE) | 실시간 린트 |
|
||||
| commit 시 | pre-commit | ruff + 위생 + 비밀 누출 |
|
||||
| push 시 | Gitea Actions | ruff + py_compile + pytest 매트릭스 |
|
||||
| 코드 리뷰 | code-reviewer subagent | 비전 위반/구조 함정 |
|
||||
|
||||
## 4. 시작하기
|
||||
|
||||
```powershell
|
||||
cd D:\2026\PROGRAM\1_S-CANVAS
|
||||
|
||||
# uv 환경
|
||||
uv venv .venv313 --python 3.13
|
||||
.\.venv313\Scripts\activate
|
||||
uv pip install -e ".[py313,dev]"
|
||||
|
||||
# pre-commit 등록
|
||||
pre-commit install
|
||||
pre-commit install --hook-type pre-push # push 직전 pytest 추가 게이트
|
||||
|
||||
# 테스트 한 번 돌려서 환경 확인
|
||||
pytest -ra
|
||||
ruff check
|
||||
```
|
||||
|
||||
## 5. 새 기능/버그 수정 워크플로
|
||||
|
||||
```powershell
|
||||
# 0. 기능 브랜치
|
||||
git checkout -b feature/my-thing
|
||||
|
||||
# 1. (버그 수정인 경우만) 회귀 테스트 먼저 추가 → Red 확인
|
||||
# tests/test_regressions.py 에 새 함수 추가
|
||||
pytest tests/test_regressions.py::test_new_thing # → fail (정상)
|
||||
|
||||
# 2. 코드 작성/수정
|
||||
|
||||
# 3. ruff 자동 수정
|
||||
ruff check --fix
|
||||
|
||||
# 4. pytest 통과 확인 (Green 도달)
|
||||
pytest -ra
|
||||
|
||||
# 5. commit (pre-commit이 ruff 재검사)
|
||||
git add -p
|
||||
git commit -m "fix: <설명>"
|
||||
|
||||
# 6. push (pre-push hook이 pytest 재실행)
|
||||
git push origin feature/my-thing
|
||||
|
||||
# 7. PR 만들기 → Gitea Actions가 매트릭스 검증 → main 머지
|
||||
```
|
||||
|
||||
## 6. 자동 push (피드백 #6 — 본 라운드 미구현, 다음 라운드)
|
||||
|
||||
현재는 사람이 `git push` 실행. 다음 라운드 후보:
|
||||
|
||||
- **옵션 A (보수)**: `pre-push` 훅에서 ruff + pytest pass 시 자동 `git push` (사람 한 번 더 확인 필요).
|
||||
- **옵션 B (적극)**: 로컬 `watch` 데몬 — Green 도달 직후 자동 push.
|
||||
- **옵션 C (안전)**: feature 브랜치만 자동 push, main은 항상 PR.
|
||||
|
||||
옵션 C 권장. main 보호는 Gitea repo settings → Branch Protection 으로 강제.
|
||||
|
||||
## 7. 서브에이전트 활용
|
||||
|
||||
`.claude/agents/` 안 7개 specialized agent — Claude Code 세션에서 자동/명시 호출:
|
||||
- `product-vision-keeper` — 큰 결정 전 검토
|
||||
- `ux-designer` — UI 변경
|
||||
- `performance-guardian` — 성능 회귀 의심
|
||||
- `library-architect` — 새 구조물/플러그인
|
||||
- `pyvista-renderer` — 3D 시각 품질
|
||||
- `code-reviewer` — 코드 변경 후 비판
|
||||
- `INSTALL_AND_USE.md` — 설치/사용 가이드
|
||||
|
||||
`.claude/agents/INSTALL_AND_USE.md` 참고.
|
||||
|
||||
## 8. 산출물 (이번 라운드 신규)
|
||||
|
||||
- `harness/crash_logger.py` — 크래시 로그 + faulthandler (#1)
|
||||
- `scanvas_maker.py` `_TIN_EARTH_CMAP` — 파란색 없는 TIN 컬러맵 (#3)
|
||||
- `pyproject.toml` + `UV_GUIDE.md` — uv 마이그레이션 (#5)
|
||||
- `ARCHITECTURE_PLAN.md` — Core/Plugin 분리 설계 (#10)
|
||||
- `PERFORMANCE_BASELINE.md` — 19 핫스팟 + 측정 plan (#11)
|
||||
- `UI_REDESIGN_PLAN.md` — single-window 재설계 (#4)
|
||||
- `tests/` + `.pre-commit-config.yaml` + `.gitea/workflows/ci.yml` + 본 문서 — 개발 사이클 인프라 (#6/#7/#8)
|
||||
- `~/.claude/projects/.../memory/feedback_no_ab_pingpong.md` — A/B 무한루프 금지 영구 룰 (#9)
|
||||
Reference in New Issue
Block a user