8.9 KiB
Contributing to Owen Graphite v3
Owen Graphite v3 (현재 안정 릴리즈 v3.1.51)은 처음부터 다시 작성된 코드베이스입니다. 본 문서는 v3 기여자가 따라야 할 워크플로우와 검증 절차를 정리합니다.
0. 사전 준비
- Python 3.10+ (
.venv\Scripts\python.exe권장; Windows 기준) - Obsidian 1.5.8+
- (선택) Style Settings 플러그인 — 옵션 토글 확인용
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt # Playwright 등 fingerprint 캡처용
python -m playwright install chromium
1. 폴더 구조
진본 CSS는 모두 src/ 아래에 있습니다.
src/
tokens/ # 색, 타이포, 간격, 그림자, glass surface 토큰
base/ # reset, 타이포, reading view, live preview 기본
surfaces/ # callout, table, code, list, embed, canvas, graph
chrome/ # workspace, nav, overlay, settings
features/ # style settings, report, pdf/print, dark
themes/ # dark, a11y
plugins/ # dataview, tasks, 기타 호환
polish/ # 최종 조정 + glass polish
번들 결과는 dist/theme-v3.css, 진본 사본은 루트 theme.css.
2. 작업 흐름
- WIKI 확인: 모든 코드 작성, 기능 개선, 수정, 정리 작업 전에 dev/WIKI/README.md, dev/WIKI/CORE-PRINCIPLES.md, dev/WIKI/QUICK-ROUTING.md, 관련 workflow/MAP을 먼저 읽습니다.
- 분기:
git checkout -b feature/<name>(베이스:main) - 편집:
src/안에서만 수정.theme.css는 직접 편집하지 않습니다. - 번들:
python dev/scripts/bundle_v3.py - 승격:
Copy-Item dist\theme-v3.css theme.css -Force(또는 macOS/Linuxcp) - 빠른 전체 점검:
python dev/scripts/release_check.py— 번들 freshness, 메타데이터, Style Settings, docs/assets, CSS budget, Live Preview, PDF header/footer, 중복 selector threshold를 한 번에 확인
- 개별 감사:
python dev/scripts/audit_v3_hit_routing.py— Live Preview 회귀 차단python dev/scripts/audit_lp_pdf_selector_ownership.py— Live Preview/Reading/PDF selector ownership 및 HyperMD direct-line vertical box 회귀 차단python dev/scripts/v3_audit_duplicate_selectors.py— 중복 selector 통계 (정보용)python dev/scripts/build_unused_css_report.py— unused CSS 제거 전 후보/예약 selector 분류
- 시각 회귀 (선택):
python dev/scripts/capture_computed_fingerprint.py --build v3 --theme lightpython dev/scripts/capture_computed_fingerprint.py --build v3 --theme darkpython dev/scripts/fp_diff_summary.py [--theme dark]— 베이스라인과 0 diff 유지
- commit/PR: 메시지에 영향 받는
src/모듈을 명시. fingerprint diff가 0이 아닌 경우 PR 본문에 사유 첨부.
2.1 변경 유형별 검증 매트릭스
| 변경 유형 | 최소 검증 | 추가 확인 |
|---|---|---|
src/tokens/ 색·간격·타이포 토큰 |
python dev/scripts/release_check.py |
Light/Dark fingerprint diff 또는 실제 Obsidian 화면 비교 |
src/base/ / src/surfaces/ 본문·표·코드·callout |
python dev/scripts/release_check.py |
긴 표, 긴 코드 토큰, callout 내부 목록 fixture 확인 |
src/chrome/ 탭·탐색기·검색·설정 UI |
python dev/scripts/release_check.py |
hover/focus가 row height를 바꾸지 않는지 수동 확인 |
src/features/42-report-print-polish.css 또는 PDF 설정 |
python dev/scripts/release_check.py |
PDF export 샘플, header/footer 겹침, 페이지 분할 확인 |
| Style Settings id/default/title 변경 | python dev/scripts/audit_style_settings_contract.py |
dev/WIKI/DOCS/v3/style-settings-contract.md와 JSON 계약 동시 갱신 |
| README 이미지·문서 링크 변경 | python dev/scripts/audit_docs_assets.py + python dev/scripts/audit_readme_svg_layout.py |
SVG 텍스트·아이콘이 컨테이너 경계에 닿지 않고 release/sync 자산에 포함되는지 확인 |
| unused CSS 제거 | python dev/scripts/build_unused_css_report.py |
dev/WIKI/DOCS/v3/unused-css-roadmap.md의 bucket별 제거 조건 충족 |
2.2 README 기능 소개와 이미지
- README의
2. 신기능 소개에는 최신 3개 기능만 유지합니다. - 네 번째로 밀린 기능은 dev/WIKI/DOCS/v3/feature-history.md로 이동합니다.
- 새 기능 이미지는 기능이 실제로 보이는 SVG/PNG를 사용하고, README 링크와 release/sync 포함 여부는
python dev/scripts/audit_docs_assets.py로 검증합니다. - 생성 SVG는 텍스트와 아이콘이 카드·툴바·뷰포트 경계에 닿지 않도록 여유 마진을 두고,
python dev/scripts/audit_readme_svg_layout.py를 통과해야 합니다. - 기본 Obsidian과 비교가 필요한 변경은 dev/WIKI/DOCS/v3/visual-comparison-guide.md의 캡처 기준을 따릅니다.
3. Direct-owner migration guard
src/polish/* late layer는 retired 상태입니다. 새 보정은 원 소유 모듈(base/, surfaces/, chrome/, features/, tokens/)에 직접 적용합니다.
.\.venv\Scripts\python.exe dev\scripts\build_effective_source_map.py
.\.venv\Scripts\python.exe dev\scripts\build_effective_baseline.py
.\.venv\Scripts\python.exe dev\scripts\build_style_settings_matrix.py
직접소유 이관 작업은 dev/WIKI/MAP/direct-owner-migration-matrix.md와 dev/WIKI/MAP/owner-registry.json을 기준으로 surface 단위로 진행합니다. 값 검증은 capture_effective_snapshot.py / diff_effective_snapshot.py, 출처 검증은 capture_provenance_snapshot.py와 dev/WIKI/MAP/effective-source-map.json을 사용합니다.
unused CSS 정리는 dev/WIKI/MAP/unused-css-candidates.md를 먼저 생성한 뒤 진행합니다. candidate가 아닌 reserved selector는 Obsidian 상태, 플러그인, 문서 의미, Style Settings, print/mobile 조건처럼 fixture에 없을 수 있는 경로이므로 별도 coverage 없이 제거하지 않습니다. 다음 coverage 보강은 리포트의 Reserved Reason Summary와 Coverage Gap Hotspots를 기준으로 정합니다.
4. 보존 계약 (Preservation Contract)
v3는 v2.30.14의 픽셀 결과를 보존합니다. 모든 변경은 다음을 통과해야 합니다.
| 계약 | 도구 | 통과 기준 |
|---|---|---|
| C1 시각 | dev/scripts/capture_computed_fingerprint.py + fp_diff_summary.py |
Light/Dark diff = 0 |
| C2 Live Preview 편집성 | dev/scripts/audit_v3_hit_routing.py |
violations = 0 |
| C3 Style Settings 옵션 | 수동 토글 매트릭스 | 37 옵션 × ON/OFF 동일 |
| C4 PDF 출력 | @media print 시나리오 수동 비교 |
페이지 수·레이아웃·footer 동일 |
상세 계약은 dev/WIKI/DOCS/v3/design-spec.md 참고.
5. !important 정책
declaration-level !important = 0. 새 !important를 추가하려면:
- 해당 룰의 선택자 특이도가 Obsidian core를 이기는지 확인 (대부분 충분합니다)
- 그래도 필요하다면 PR 본문에
defeats core selector형태로 사유 명시 - CSS 주석에 동일한 사유 인라인 명시
자동 제거 도구 dev/scripts/v3_strip_important_src.py 는 주석 안의 !important 토큰은 건드리지 않습니다.
6. 디자인 가이드라인 (Liquid Glass core)
- Resting state: 흰색/회색 frosted glass, 좌측 vertical rail 금지
- Hover: 살짝 밝아지고 들어올림, wide soft downward shadow, 얕은 pastel 톤
- Active: 선택 문서/탭 같은 명확한 상태에만 sky tint + glass border 적용
- 반복 chrome: 의미색 대신 밝기·그림자로만 반응
- 샘플 자산: 새 기능 추가 시 README의 해당 섹션에 liquid-glass 샘플 이미지(SVG/PNG) 동봉
자세한 원칙은 dev/WIKI/DOCS/v3/surface-state-matrix.md.
7. Pre-commit hook (선택)
ln -sf ../../dev/scripts/hooks/pre-commit .git/hooks/pre-commit
chmod +x dev/scripts/hooks/pre-commit
Windows에서는 hook 내용을 .git/hooks/pre-commit.ps1 로 직접 옮기거나, WSL/Git Bash 환경에서 실행하세요. Hook은 번들 + hit-routing 감사를 강제합니다.
8. Release 절차
dev/WIKI/DOCS/v3/release-plan.md 의 R0~R6 단계 참조.
요약:
manifest.json의version갱신CHANGELOG.md에 새 섹션 추가python dev/scripts/release_check.py --tag <version>python dev/scripts/build_release_notes.py --output dist/release-notes-v<version>.mdpython dev/scripts/build_release.py→dist/Owen-Graphite-<version>.zippython dev/scripts/audit_release_zip.pygit tag <version>+git push origin <version>(CI가 GitHub Release 생성)