Yun Chan 3dfddcac6f 전 저장소 리팩터링과 SSOT 정비

2026-07-15 21:31:30 +09:00

11 KiB

Raw Blame History

연구팀·디자인 담당을 위한 협업 가이드 (Git을 처음 쓰는 분께)

이 문서는 개발이 처음인 연구팀 대학원생·디자인 담당 학생이 이 저장소(프로젝트 파일 보관소)에 안전하게 참여하기 위한 안내서다. 어려운 용어는 나올 때마다 한 줄로 풀어서 설명한다. 천천히 따라오면 되고, 막히면 언제든 단톡방에 물어보면 된다.

먼저 알아둘 3가지

여러분은 코드를 몰라도 참여할 수 있다. 대부분은 웹 브라우저 화면만으로 가능하다.

실수해도 프로젝트가 망가지지 않도록 설계돼 있다. 아래 "하지 말아야 할 것"만 지키면 된다.

문구(화면에 보이는 글자) 수정은 단톡방에 목록으로 전달하는 것이 가장 쉬운 기본 경로다. 직접 고쳐보고 싶은 분을 위한 방법도 뒤에 따로 안내한다.

1. 왜 main(master)에 직접 손대면 안 되나

먼저 용어부터.

용어	한 줄 뜻
저장소(repository, 레포)	프로젝트의 모든 파일과 수정 이력이 담긴 온라인 보관소
브랜치(branch, 가지)	원본을 건드리지 않고 따로 복사해서 작업하는 "작업용 사본"
main / master	실제 서비스에 반영되는 원본 줄기. 손대면 바로 모두에게 영향
커밋(commit)	"여기까지 이렇게 고쳤다"라고 저장하는 한 번의 기록

비유로 이해하기. main(master)은 병원의 정식 환자 차트 원본이라고 생각하면 된다. 누구든 원본에 바로 낙서하듯 고치면, 다른 사람이 그 잘못된 차트를 그대로 믿고 일하게 되고, 누가 언제 무엇을 바꿨는지도 뒤엉킨다. 그래서 우리는 항상 원본을 복사한 작업용 사본(브랜치) 에서 고친 뒤, 담당자가 한 번 확인(리뷰)하고 나서야 원본에 반영한다.

이렇게 하면 좋은 점:

원본은 항상 작동하는 상태로 유지된다 (파일럿·시연 중에 갑자기 화면이 깨지지 않는다).
실수해도 내 작업용 사본에서만 일어나므로 되돌리기 쉽다.
바꾼 이유와 내용을 담당자가 한 번 검토하므로 사고가 미리 걸러진다.

한 줄 요약: 원본(main/master)에 직접 저장(커밋)·업로드(push)하지 않는다. 항상 사본(브랜치) → 확인(리뷰) → 반영 순서.

2. 시작 준비 — GitHub 계정과 저장소 초대

우리는 GitHub라는 서비스에서 이 저장소를 관리한다. (GitHub = 저장소를 온라인에 두고 여럿이 함께 작업하게 해주는 웹사이트.)

여러분이 할 일 (체크리스트)

1. github.com 에서 무료 계정을 만든다. (이메일·비밀번호만 있으면 된다)
2. 가입에 사용한 GitHub 아이디(username) 또는 이메일을 단톡방에 알려준다.
3. 소유자(윤찬)가 여러분을 저장소에 초대한다. → 초대 실행은 윤찬이 직접 한다. 여러분이 신청하는 것이 아니다.
4. 초대되면 여러분의 가입 이메일로 초대 메일이 오거나, GitHub 알림에 초대가 뜬다.
5. 메일/알림의 "Accept invitation(초대 수락)" 버튼을 누른다. 끝.

수락하고 나면 저장소 페이지가 열리고, 이제 여러분도 이 프로젝트의 협업자(collaborator)가 된다.

초대가 안 왔거나 버튼을 못 찾겠으면 단톡방에 알려주면 된다. 흔한 일이니 걱정하지 않아도 된다.

3. 실제 수정 흐름 — 웹 브라우저만으로 (권장)

여기서는 컴퓨터에 아무것도 설치하지 않고, GitHub 웹사이트 화면만으로 파일을 고치고 반영 요청까지 하는 방법을 설명한다. 대부분의 문구·문서 수정은 이 방법으로 충분하다.

먼저 이 흐름의 전체 그림:

파일 열기 → 편집(연필) 버튼 → 내용 수정 → "Propose changes(변경 제안)"
   → 자동으로 새 브랜치(사본) 생성됨 → Pull Request(반영 요청) 작성
   → 담당자 리뷰 → 문제 없으면 병합(main에 반영)

용어 두 개만 더:

용어	한 줄 뜻
Pull Request (PR, 풀 리퀘스트)	"제 사본에서 이렇게 고쳤으니 원본에 반영해 주세요"라는 반영 요청서
병합(merge, 머지)	검토를 통과한 사본의 변경을 원본에 합치는 것

3-1. 단계별 (웹 UI 기준)

파일을 찾아 연다. 저장소 페이지에서 폴더를 눌러 들어가 원하는 파일을 클릭한다. (예: 문구는 대개 apps/web/src/pages/ 폴더 안에 있다 — 4장 참조)
연필(✏️) 아이콘을 누른다. 파일 오른쪽 위에 있다. "Edit this file(이 파일 편집)" 뜻이다.
내용을 고친다. 화면에서 글자를 직접 수정하면 된다.
오른쪽 위 "Commit changes...(변경 저장)" 초록 버튼을 누른다.
작은 창이 뜨면:
- 변경 설명에 무엇을 왜 고쳤는지 한 줄로 적는다. (예: 학습자 홈 안내 문구 오타 수정)
- 반드시 아래쪽 "Create a new branch ... and start a pull request(새 브랜치를 만들어 PR 시작)" 를 고른다. → 이걸 고르면 원본을 건드리지 않고 자동으로 사본(브랜치)이 만들어진다. (첫 번째 "Commit directly to the master branch(원본에 바로 저장)"는 고르지 않는다.)
- 브랜치 이름은 자동으로 채워지니 그대로 둬도 된다.
- "Propose changes" 를 누른다.
Pull Request(반영 요청) 화면이 나온다. 제목·설명을 확인하고(자동으로 채워져 있음) "Create pull request" 를 누른다.
끝. 이제 담당자가 리뷰한다. 단톡방에 "PR 올렸습니다"라고 한 마디 남겨주면 확인이 빨라진다.
담당자가 수정 요청을 남기면, 같은 PR에서 파일을 다시 편집해 커밋하면 된다. 문제 없으면 담당자가 병합(merge) 하여 원본에 반영한다.

3-2. 한눈에 보는 체크리스트

원하는 파일을 연다
연필(✏️) 버튼으로 편집
"Commit changes" → 새 브랜치 만들기 선택 (원본 직접 저장 아님)
"Create pull request"로 반영 요청
단톡방에 PR 올렸다고 공유
리뷰 통과 후 담당자가 병합 → 완료

4. UI 문구(화면 글자) 수정 프로세스

4-1. 기본 경로 — 단톡방으로 목록 전달 (가장 쉽고 빠름)

화면에 보이는 문구를 고치고 싶을 때 가장 권장하는 방법이다.

바꿀 문구를 목록으로 정리한다. 아래처럼 "어디의 / 무엇을 / 어떻게" 형태면 개발자가 바로 반영한다.

위치(어느 화면) 현재 문구 바꿀 문구

학습자 홈 상단 회기를 시작하세요 오늘의 회기를 시작해 보세요

회기 준비 화면 버튼 시작 회기 시작
이 목록을 단톡방에 전달한다.
개발 쪽에서 단순 텍스트 교체 수준으로 즉시 반영한다.

위치(어느 화면)	현재 문구	바꿀 문구
학습자 홈 상단	회기를 시작하세요	오늘의 회기를 시작해 보세요
회기 준비 화면 버튼	시작	회기 시작

문구 수정은 이 경로가 기본이다. Git을 몰라도 되고, 실수할 일도 없다.

4-2. 직접 고쳐보고 싶은 분을 위한 안내

3장의 웹 UI 방법으로 직접 PR을 올리고 싶다면, 문구는 주로 아래 위치에 있다.

폴더: apps/web/src/pages/
파일: 화면별 .tsx 파일 (예: 학습자 홈은 LearnerHome.tsx, 회기 화면은 Session.tsx, 교수자 화면은 Professor.tsx)
문구 형태: 파일 안에서 따옴표(" ")로 감싼 한글 글자가 화면에 보이는 문구다. 예: label: "전체" 에서 전체, "내담자 정보를 불러오는 중" 같은 부분.

가장 중요한 원칙 — 문자열(따옴표 안 글자)만 바꾸고, 코드 구조는 절대 건드리지 않는다.

해도 되는 것 (안전)	하면 안 되는 것 (위험)
따옴표 안쪽의 한글 글자만 수정	따옴표 `"` 자체를 지우기
`"시작"` → `"회기 시작"` 처럼 글자만 교체	`label:`, `{ }`, `( )`, `;`, `<` `>` 같은 기호 수정
오타·띄어쓰기·표현 다듬기	줄을 통째로 지우거나 위치 옮기기
	영어로 된 코드 부분(`value`, `desc` 등) 수정

헷갈리면 무리하지 말고 4-1의 목록으로 전달하면 된다. 그게 더 빠를 때가 많다. 직접 PR을 올렸다면 단톡방에 알려서 리뷰를 받는다. 병합 전에 담당자가 확인하므로, 잘못 고쳤어도 원본에 그대로 들어가지 않는다.

5. 하지 말아야 할 것 (꼭 지켜주세요)

하지 말 것	왜 위험한가
❌ main(master)에 직접 저장·업로드	원본이 검토 없이 바뀌어 시연·파일럿 중 화면이 깨질 수 있다. 항상 사본(브랜치)+PR로.
❌ force push(강제 덮어쓰기)	남들이 올린 기록까지 지워버릴 수 있다. 이 단어가 나오면 절대 실행하지 말고 문의.
❌ 남의 브랜치(사본)를 덮어쓰기·삭제	다른 사람이 작업 중인 내용을 날린다. 내 사본만 다룬다.
❌ 코드 파일을 대량으로 수정	문구 한두 줄이 아니라 구조를 건드리면 프로그램이 멈춘다. 문구는 "문자열만" 원칙.
❌ `.env`·비밀번호·API 키 등 secret 파일 커밋	비밀 정보가 온라인에 영구히 노출된다. 이런 파일은 올리지 않는다.
❌ 확신 없는 대량 삭제	무엇이 사라질지 모른다. 애매하면 먼저 물어본다.

위 항목 중 하나라도 "이거 해도 되나?" 싶으면 멈추고 단톡방에 물어보는 것이 정답이다. 물어봐서 손해 보는 일은 없다.

6. 도움 요청 채널

막히거나 헷갈릴 때: 단톡방에 바로 물어본다. 캡처(스크린샷)를 함께 올리면 더 빠르다.
자주 나오는 질문
- "초대가 안 왔어요" → 단톡방에 GitHub 아이디/이메일을 다시 알려준다.
- "어떤 버튼을 눌러야 할지 모르겠어요" → 화면 캡처와 함께 물어본다.
- "문구만 바꾸고 싶어요" → 4-1의 목록 양식으로 단톡방에 전달하면 개발 쪽에서 반영한다.

혼자 오래 고민하지 말고, 처음엔 무엇이든 물어보면서 익히면 된다.

(선택 심화) 로컬 Git으로 작업하기

컴퓨터에 직접 도구를 설치해 작업하는 방법도 있지만, 연구팀·디자인 담당은 위 3장의 웹 UI 방법만으로 충분하다. 로컬 개발 환경이 필요한 경우(개발 인력 합류 등)에는 별도 문서 local-development.md를 참고한다. 이 문서를 처음부터 볼 필요는 없다.

11 KiB Raw Blame History