Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
118 lines (85 loc) · 10.3 KB

CONTRIBUTING.md

File metadata and controls

118 lines (85 loc) · 10.3 KB
Raw

허브를 고치고 더하는 방법

이 문서는 Causal Inference Hub를 관리하는 사람을 위한 안내입니다. 허브 소개는 README에 있습니다.

공개 원칙

  • 이름은 Builder만 표시합니다. 러너는 이름 없이 인원수로만 보여 줍니다.
  • 커리큘럼 L0–L2는 무료 자료만으로 끝까지 갈 수 있게 유지합니다. 책과 강의는 L2에 유료로 따로 표시합니다.

내용 더하기

PR을 올리기 전에 python3 scripts/check_data.py를 실행해 주세요. 배포 워크플로도 같은 검사를 하며, 실패하면 배포하지 않습니다. 링크는 https(또는 http)나 사이트 안의 경로만, id는 영문·숫자·하이픈만, 기수·인원은 정수만 허용합니다. 글(articles/*.md)의 HTML은 화면에 그릴 때 정리(sanitize)되어 스크립트가 실행되지 않습니다.

사이트는 빌드 도구 없이 data/ 폴더의 JSON 파일을 읽어 그립니다. 대부분의 수정은 파일 하나를 고치는 PR이면 됩니다.

파일 고치는 경우
data/featured.json 첫 화면 배너의 대표 오픈소스 링크를 바꿀 때. repo를 적으면 스타 수가 함께 나옵니다.
data/projects.json 기수별 프로젝트를 추가할 때. 러너는 인원수(runners)만 적습니다. Builder가 회고를 보내 주면 "retro": {"why": "…", "learned": "…", "next": "…"}로 넣습니다. 비어 있으면 화면에 나오지 않습니다.
data/builders.json Builder의 LinkedIn, GitHub 아이디(프로필 사진에 쓰임), 한 줄 소개, Builder가 되기 전 러너로 참여한 프로젝트(runnerOf)를 넣을 때. slug는 Builder 페이지 주소(/builders/<slug>.html)가 되므로 한 번 정하면 바꾸지 않습니다.
data/growth.json 기수별 누적 러너 수. 프로젝트 시트를 xlsx로 내려받아 python scripts/runners_from_sheet.py 파일.xlsx > data/growth.json으로 만듭니다. 이름은 파일에 남지 않습니다.
data/events.json Data Forum 같은 행사를 추가할 때. 다가오는 행사에는 tagline, time, venue, address, signupStart·signupEnd(신청 기간), capacity(정원), code(추천 코드 안내), timetable, poster·timetableImage(assets/img/의 이미지)를 적을 수 있습니다. 신청 기간에 따라 첫 화면 띠와 카드의 문구가 ‘신청 예정 · 받는 중 · 마감’으로 바뀝니다.
data/repos.json 레포를 추가하거나 설명·단계·트랙·상태를 바꿀 때
data/map.json 트랙 지도에서 레포의 위치를 정할 때. 책과 강의(paid)의 표지와 소개도 여기서 고칩니다.
data/levels.json 레벨의 설명과 볼 순서를 바꿀 때. learn(배우는 것), outcome(끝나면), steps(순서대로 볼 레포와 한 줄 note), more(웹북 장이나 허브 페이지 같은 더 해 보기 링크)를 적습니다. steps에 없는 같은 레벨의 레포는 ‘골라 보기’로 나옵니다.
data/leveltest.json 레벨 진단 문제를 고칠 때. 문제마다 band(L0·L1·L2), 보기 opts, 정답 순서 answer(0부터), 해설 why, 다시 볼 장 chapter를 적습니다. bands의 pass보다 적게 맞힌 첫 구간이 시작 Level이 되고, 모두 넘으면 관심 분야에 따라 Level 3이나 4가 됩니다.
data/routes.json 관심 분야별로 이어서 볼 자료를 바꿀 때. 레벨 진단 결과의 ‘관심 분야에 맞춰 이어서’에 쓰입니다.
data/articles.json, articles/*.md 연재 글을 추가할 때. 아래 ‘연재 쓰기’를 보세요.
data/game.json ‘상관일까, 인과일까?’ 문항을 고칠 때. answer는 corr 또는 cause이고, 문항마다 웹북 장 링크(chapter)를 답니다.
data/daily.json 오늘의 한 문제 문항을 더하거나 고칠 때. 형식은 game.json과 같고, 날짜마다 순서대로 돌아갑니다. 인과와 상관 문항을 비슷한 수로 맞춥니다.
data/stats.json 직접 고치지 않습니다. 매주 GitHub Actions가 스타 추이와 기여자 수를 갱신합니다.

레포를 추가할 때의 예시입니다.

{
  "repo": "new-repo-name",
  "title": "허브에 보일 이름",
  "summary": "한두 문장 소개",
  "level": "L2",
  "lines": ["main"],
  "status": "running",
  "builders": ["Builder 이름"],
  "cohorts": [13],
  "site": "https://causalinferencelab.github.io/new-repo-name/",
  "stars": 0
}

stars는 기본값이고, 사이트는 열릴 때 GitHub에서 최신 스타 수와 마지막 커밋 날짜를 불러옵니다.

Builder 페이지와 배지

builders/<slug>.html, builders/index.html, badges/<slug>.svg는 scripts/build_builders.py가 데이터 파일로 만듭니다. 만들어지는 파일이라 커밋하지 않고, 배포할 때 GitHub Actions가 실행합니다. 로컬에서 보려면 먼저 실행하세요.

python3 scripts/build_builders.py

링크를 공유할 때 보이는 이미지(assets/og/builders/<slug>.jpg)는 따로 만들어 커밋합니다. Builder가 새로 생기거나 숫자가 바뀌면 다시 만들어 주세요. 이미지가 없는 페이지는 허브 기본 이미지를 씁니다.

pip install playwright && python -m playwright install chromium
python3 scripts/builder_cards.py

연재 쓰기

허브의 ‘연재’ 섹션은 팀원이 쓰는 글을 모읍니다. 매주 월요일 ‘이번 주 포스트’가 바뀌고, 글쓴이는 작가 카드로 소개됩니다.

  1. articles/<slug>.md에 본문을 씁니다. slug는 영문 소문자·숫자·하이픈입니다.
  2. data/articles.json에 한 줄을 더합니다.
{ "slug": "did-in-practice-01", "title": "이중차분법을 실무에 쓸 때", "summary": "한 줄 소개", "date": "2026-11-02",
  "author": "Builder 이름", "series": "연재 이름", "episode": 1, "weekOf": "2026-11-02" }
  • author가 data/builders.json의 이름과 같으면 작가 카드에 사진, 메달, Builder 페이지가 붙습니다.
  • series와 episode를 넣으면 같은 연재의 글이 순서대로 묶이고, 글 아래에 이전 편·다음 편이 생깁니다.
  • weekOf(그 주 월요일)를 넣으면 그 주의 ‘이번 주 포스트’로 고정됩니다. 없으면 일주일 안에 올라온 새 글, 그다음은 돌아가며 보여 줍니다.
  • 다른 블로그에 올린 글은 "url": "https://..."를 넣으면 그 주소로 연결됩니다(본문 파일은 필요 없습니다).
  • date가 미래인 글은 그날(한국 시간)까지 목록에 보이지 않습니다. 연재 여러 편을 PR 하나로 올려 두고, 편마다 date와 weekOf를 그 주 월요일로 넣으면 한 주에 한 편씩 열립니다. 미리 보려면 article.html#<slug>로 직접 엽니다.
  • related에는 map.json의 책·강의 id나, repos.json에서 site가 있는 레포 이름(예: Causal-Inference-with-Python)을 넣습니다. 글 아래에 이어지는 자료로 보입니다.

활동 여권과 실험실

스탬프 정의는 assets/js/passport.js의 STAMPS에 있습니다. kind: "auto"는 허브가 알아서 찍고(window.hubStamp("post")), kind: "self"는 행사 후기, 강의 후기, 레포 댓글처럼 허브 밖에서 하는 일이라 방문자가 ‘했어요’를 눌러 찍습니다. 레벨 스탬프(stage_L0–stage_L4)는 그 레벨의 퀘스트를 모두 클리어하면 허브가 찍습니다. L3·L4처럼 data/levels.json에 quests(스탬프 id 목록)가 있는 레벨은 그 스탬프들이 퀘스트이고, 없는 레벨은 steps에 적은 자료가 퀘스트입니다. 레벨 진단 스탬프(level_test)는 진단을 끝까지 풀면 찍히고, 결과는 cil-hub-level에 남습니다. /?level로 들어오면 진단이 바로 열립니다. 이미 받은 스탬프는 다시 주지 않고, 기록은 localStorage에만 남습니다. 웹북 독자 스탬프는 같은 도메인의 웹북이 남기는 cil-book-read(읽은 장)를 보고 찍고, 역 정보 창의 '내 진도'와 '이어 읽기'는 cil-book-read, cil-book-last를 읽습니다. /#passport로 들어오면 여권이 바로 열립니다. 교란 실험실(lab.html, assets/js/lab.js)의 데이터는 페이지에서 만드는 가상 사용자입니다.

이벤트 측정

assets/js/track.js의 hubTrack(이름, 파라미터)가 GA4로 이벤트를 보냅니다. GA4가 설치되지 않았으면 아무 일도 하지 않습니다. 이벤트 이름과 파라미터는 PM 문서의 이벤트 사전을 따르고, 새 이벤트를 넣을 때는 사전에도 같이 적습니다. HTML에서는 data-event="click_join" data-event-params='{"target":"template","source":"builder_page"}'처럼 속성만으로도 보낼 수 있습니다. 로컬에서 확인하려면 콘솔에서 window.HUB_DEBUG = true를 켭니다.

배포

main에 머지되면 Deploy site 워크플로가 사이트를 만들어 gh-pages 브랜치에 올리고, GitHub Pages가 그 브랜치를 공개합니다. gh-pages는 지우지 마세요. 지우면 Pages 설정이 꺼지고 사이트 전체가 404가 됩니다. 머지된 브랜치를 한꺼번에 지울 때도 gh-pages와 main은 남겨 두세요.

로컬에서 보기

python3 -m http.server 8000
# http://localhost:8000

JSON을 fetch로 읽기 때문에 파일을 더블클릭해서 열면 데이터가 보이지 않습니다.

배포

main에 머지되면 GitHub Actions가 JSON 문법을 검사한 뒤 사이트 파일을 gh-pages 브랜치로 배포합니다 (.github/workflows/deploy.yml). 같은 워크플로가 매주 월요일 scripts/update_stats.py로 스타의 월별 추이, 기여자 수, 레포별 마지막 커밋 날짜를 모아 data/stats.json에 반영한 뒤 다시 배포합니다. 머지 직후 Actions 탭에서 "Run workflow"를 한 번 누르면 바로 채워집니다.

레포의 상태 (status)

상태 기준
running 진행 중 이번 기수에 진행 중인 프로젝트
active 최근 업데이트 올해 코드나 내용이 갱신된 레포
stable 완결 내용이 마무리되어 오류 수정 위주로 관리하는 레포
depot 운영·보관 허브 운영(이 레포, 프로젝트 템플릿)과 보관용 레포