185 lines
11 KiB
Markdown
185 lines
11 KiB
Markdown
# 연구팀·디자인 담당을 위한 협업 가이드 (Git을 처음 쓰는 분께)
|
|
|
|
이 문서는 **개발이 처음인 연구팀 대학원생·디자인 담당 학생**이 이 저장소(프로젝트 파일 보관소)에
|
|
안전하게 참여하기 위한 안내서다. 어려운 용어는 나올 때마다 한 줄로 풀어서 설명한다.
|
|
천천히 따라오면 되고, 막히면 언제든 단톡방에 물어보면 된다.
|
|
|
|
> **먼저 알아둘 3가지**
|
|
> 1. 여러분은 코드를 몰라도 참여할 수 있다. 대부분은 **웹 브라우저 화면만으로** 가능하다.
|
|
> 2. 실수해도 프로젝트가 망가지지 않도록 설계돼 있다. 아래 "하지 말아야 할 것"만 지키면 된다.
|
|
> 3. 문구(화면에 보이는 글자) 수정은 **단톡방에 목록으로 전달하는 것이 가장 쉬운 기본 경로**다.
|
|
> 직접 고쳐보고 싶은 분을 위한 방법도 뒤에 따로 안내한다.
|
|
|
|
---
|
|
|
|
## 1. 왜 main(master)에 직접 손대면 안 되나
|
|
|
|
먼저 용어부터.
|
|
|
|
| 용어 | 한 줄 뜻 |
|
|
|---|---|
|
|
| **저장소(repository, 레포)** | 프로젝트의 모든 파일과 수정 이력이 담긴 온라인 보관소 |
|
|
| **브랜치(branch, 가지)** | 원본을 건드리지 않고 따로 복사해서 작업하는 "작업용 사본" |
|
|
| **main / master** | 실제 서비스에 반영되는 **원본 줄기**. 손대면 바로 모두에게 영향 |
|
|
| **커밋(commit)** | "여기까지 이렇게 고쳤다"라고 저장하는 한 번의 기록 |
|
|
|
|
**비유로 이해하기.** `main(master)`은 병원의 **정식 환자 차트 원본**이라고 생각하면 된다.
|
|
누구든 원본에 바로 낙서하듯 고치면, 다른 사람이 그 잘못된 차트를 그대로 믿고 일하게 되고,
|
|
누가 언제 무엇을 바꿨는지도 뒤엉킨다. 그래서 우리는 항상 **원본을 복사한 작업용 사본(브랜치)** 에서
|
|
고친 뒤, 담당자가 한 번 확인(리뷰)하고 나서야 원본에 반영한다.
|
|
|
|
이렇게 하면 좋은 점:
|
|
|
|
- 원본은 항상 **작동하는 상태**로 유지된다 (파일럿·시연 중에 갑자기 화면이 깨지지 않는다).
|
|
- 실수해도 내 작업용 사본에서만 일어나므로 **되돌리기 쉽다**.
|
|
- 바꾼 이유와 내용을 담당자가 **한 번 검토**하므로 사고가 미리 걸러진다.
|
|
|
|
> 한 줄 요약: **원본(main/master)에 직접 저장(커밋)·업로드(push)하지 않는다. 항상 사본(브랜치) → 확인(리뷰) → 반영 순서.**
|
|
|
|
---
|
|
|
|
## 2. 시작 준비 — GitHub 계정과 저장소 초대
|
|
|
|
우리는 **GitHub**라는 서비스에서 이 저장소를 관리한다. (GitHub = 저장소를 온라인에 두고 여럿이 함께
|
|
작업하게 해주는 웹사이트.)
|
|
|
|
**여러분이 할 일 (체크리스트)**
|
|
|
|
- [ ] 1. [github.com](https://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 기준)
|
|
|
|
1. **파일을 찾아 연다.** 저장소 페이지에서 폴더를 눌러 들어가 원하는 파일을 클릭한다.
|
|
(예: 문구는 대개 `apps/web/src/pages/` 폴더 안에 있다 — 4장 참조)
|
|
2. **연필(✏️) 아이콘을 누른다.** 파일 오른쪽 위에 있다. "Edit this file(이 파일 편집)" 뜻이다.
|
|
3. **내용을 고친다.** 화면에서 글자를 직접 수정하면 된다.
|
|
4. 오른쪽 위 **"Commit changes...(변경 저장)"** 초록 버튼을 누른다.
|
|
5. 작은 창이 뜨면:
|
|
- **변경 설명**에 무엇을 왜 고쳤는지 한 줄로 적는다. (예: `학습자 홈 안내 문구 오타 수정`)
|
|
- **반드시 아래쪽 "Create a new branch ... and start a pull request(새 브랜치를 만들어 PR 시작)"** 를 고른다.
|
|
→ 이걸 고르면 **원본을 건드리지 않고 자동으로 사본(브랜치)이 만들어진다.** (첫 번째 "Commit directly to the master branch(원본에 바로 저장)"는 **고르지 않는다.**)
|
|
- 브랜치 이름은 자동으로 채워지니 그대로 둬도 된다.
|
|
- **"Propose changes"** 를 누른다.
|
|
6. **Pull Request(반영 요청) 화면**이 나온다. 제목·설명을 확인하고(자동으로 채워져 있음)
|
|
**"Create pull request"** 를 누른다.
|
|
7. 끝. 이제 **담당자가 리뷰**한다. 단톡방에 "PR 올렸습니다"라고 한 마디 남겨주면 확인이 빨라진다.
|
|
8. 담당자가 수정 요청을 남기면, 같은 PR에서 파일을 다시 편집해 커밋하면 된다.
|
|
문제 없으면 담당자가 **병합(merge)** 하여 원본에 반영한다.
|
|
|
|
### 3-2. 한눈에 보는 체크리스트
|
|
|
|
- [ ] 원하는 파일을 연다
|
|
- [ ] 연필(✏️) 버튼으로 편집
|
|
- [ ] "Commit changes" → **새 브랜치 만들기 선택** (원본 직접 저장 아님)
|
|
- [ ] "Create pull request"로 반영 요청
|
|
- [ ] 단톡방에 PR 올렸다고 공유
|
|
- [ ] 리뷰 통과 후 담당자가 병합 → 완료
|
|
|
|
---
|
|
|
|
## 4. UI 문구(화면 글자) 수정 프로세스
|
|
|
|
### 4-1. 기본 경로 — 단톡방으로 목록 전달 (가장 쉽고 빠름)
|
|
|
|
화면에 보이는 문구를 고치고 싶을 때 **가장 권장하는 방법**이다.
|
|
|
|
1. **바꿀 문구를 목록으로 정리**한다. 아래처럼 "어디의 / 무엇을 / 어떻게" 형태면 개발자가 바로 반영한다.
|
|
|
|
| 위치(어느 화면) | 현재 문구 | 바꿀 문구 |
|
|
|---|---|---|
|
|
| 학습자 홈 상단 | 회기를 시작하세요 | 오늘의 회기를 시작해 보세요 |
|
|
| 회기 준비 화면 버튼 | 시작 | 회기 시작 |
|
|
|
|
2. 이 목록을 **단톡방에 전달**한다.
|
|
3. 개발 쪽에서 **단순 텍스트 교체 수준으로 즉시 반영**한다.
|
|
|
|
문구 수정은 이 경로가 기본이다. 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`](./local-development.md)를 참고한다. 이 문서를 처음부터 볼 필요는 없다.
|