‘so easy’

핸드북 폴더 구조 #

`/content/’ #

이 안의 내용이 핸드북에서 보여지는 루트 폴더 위치다. 매칭 예는 다음과 같다.

파일 위치	URL
/content/_index.md	/
/content/company/_index.md	/company
/content/internal/dept/_index.md	/dept
/content/company/handbook/_index.md	/company/handbook
/content/company/handbook/regular-edit.md	/company/handbook/regular-edit

문서외의 static 리소스를 넣는 곳. 사실 본 페이지가 담겨 있는 것처럼 같은 폴더에 넣어도 된다.

파일 위치	URL
/static/images/ghost.png	/images/ghost.png

문서나 이미지에 공백이 포함되면 안됨. ‘%20’등으로 url-encoded string으로 치환하거나 파일에서 공백 제거
다른 리로스를 참조할경우 ‘/content’를 빼야 됨
상대 url을 쓸 경우 실제 핸드북 url 기준으로 접근해야 된다.
- _index.md 에서는 ‘./file.png’로 접근 가능
- 아니라면 ‘../file.png’처럼 접근 가능

모든 핸드북 문서에는 오너(owner/DRI) 가 존재한다. 오너는 git 소스 CODEOWNERS 정의 되어 있다.

해당 문서의 오너가 아닌 경우 혹은 다른 멤버의 의견을 듣고 싶을 경우에는 ‘리뷰(내용 확인/review)’ 절차가 들어간다.

flowchart LR A["브랜치(branch) 생성"] -- 수정 --> B["병합 준비된 브랜치"] -- "병합(merge)" --> 완료

변경 할 내용을 따로 분리하는 작업 공간 이라고 생각하면 된다. 실제 핸드북에 적용(병합/merge)할 때는 변경 내용이 맞는지 확인(review)하는 절차를 거쳐서 병합한다.

일반적인 경우 해당 문서의 오너(DRI)가 자신이므로 간단한 수정 방법과 거의 유사하나 처음 브랜치 생성과 적용(병합/merge) 절차가 추가된다.

흐름
flowchart LR A["브랜치(branch) 생성"] -- 수정 --> B["수정 완료된 브랜치"] -- "리뷰 확인 후 병합(merge)" --> 완료 B -- "리뷰 요청" --> owner owner["오너 혹은 리뷰어"] -- "리뷰" --> B

추가로 수정을 하려면 생성된 브랜치를 찾는다.
원하는 폴더를 찾아서 원하는 파일을 추가하거나 원하는 파일을 수정한다. (오른쪽 수정 버튼)
폴더 위치에서 오른쪽에 ‘Add File’로 신규 .md를 생성(‘Create new file’)하거나 이미지를 업로드(‘Upload files’) 할 수 있다.
이미 새로 생성된 브랜치에서 수정이므로 수정 내역을 바로 커밋한다. 새로 만든 브랜치 이름을 확인할 수 있다.

pull request가 뜬금없이 나오는데 그냥 그런게 있나보다 하고 넘어 가도 된다.

본인이 생성한 브랜치(실제로는 브랜치에 연결된 pull request)를 선택한다.
변경 내역을 확인 후 바로 병합하거나 리뷰 요청을 할 수 있다. 오너는 자동으로 리뷰어로 선택된다.
- 변경 내역: 변경 내역을 확인, ‘files changed’를 누르면 모든 변경 내역을 한번에 확인 가능
- 중단에 변경 내용이 자동으로 배포되었다. 해당 주소를 누르면 변경 내역이 배포된 페이지를 확인 할 수 있다.
- 오른쪽 상단에서 리뷰를 요청 할 수 있다. 멤버에서 github id를 확인하고 선택하면 된다.
- 하단에서 바로 병합할 수 있다.

slack에서 github를 연결하세요.
/github signin
slack과 github가 연결된 후 리뷰어로 선택되면 #handbook-dev에서 노티를 받을 수 있다.

리뷰어로 선택되면 이메일과 slack으로 리뷰 요청이 온다. ‘files changed’를 누르면 전체 변경 내역을 확인하고 변경 내용이 포함된 배포된 핸드북 페이지를 보고 수락하면 된다.
- comment: 라인별로 커멘트 할 수 있음
- approve: 리뷰 ok
- request changes: 수정 요청

일반적으로는 리뷰 approve된 후에 병합하면 된다. (github에서 시스템적으로 리뷰 approve되어야 병합가능 하도록 설정 할 수 있음)

문제없이 여기까지 왔다면 축하합니다.

문제가 있다면 #handbook에서 @gshock을 찾아주세요.

오너((owner/DRI) - 해당 핸드북 내용을 담당하는 책임자
리뷰(내용 확인/review) - 변경 내용을 확인하는 절차
브랜치(branch) - 변경 내용을 따로 분리하는 작업 공간
병합(적용/merge) - 수정 내용 브랜치를 핸드북에 병합하여 배포하는 작업
PR(풀리퀘스트/Pull Request) - github 용어로 소스에 대해 수정사항을 요청하는 워크플로. 이런 내용이 있으니 소스에 반영해달라는 요청이다. 이 문서와 우리 핸드북 문서 작업에서는 한개의 branch당 한개의 PR이 있으므로 따로 설명하지는 않았고 크게 신경 쓰지 않아도 된다.