image ‘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/’

문서외의 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)’ 절차가 들어간다.

  • 오너((owner/DRI) - 해당 핸드북 내용을 담당하는 책임자
  • 리뷰(내용 확인/review) - 변경 내용을 확인하는 절차

핸드북 문서의 오너

  • 흐름

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

브랜치(branch)가 뭐예요?

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

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

  • 브랜치(branch) - 변경 내용을 따로 분리하는 작업 공간
  • 병합(적용/merge) - 수정 내용 브랜치를 핸드북에 병합하여 배포하는 작업

핸드북 변경 내용 리뷰 요청

  • 흐름

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

예습

브랜치 생성하고 첫번째 수정 하기

  • 원하는 페이지에서 “Edit this page"를 누른다.

  • 브랜치 이름을 정한다. 핸드북 지라 이슈를 만들고 티켓(jira key)를 넣는걸 권장한다. 예) LH-1 image

  • ‘Create pull request’를 누른다. 수정 내역 하나가 들어간 branch가 준비되었다. image

추가로 수정하기

  • 추가로 수정을 하려면 생성된 브랜치를 찾는다. image

  • 원하는 폴더를 찾아서 원하는 파일을 추가하거나 원하는 파일을 수정한다. (오른쪽 수정 버튼)

  • 폴더 위치에서 오른쪽에 ‘Add File’로 신규 .md를 생성(‘Create new file’)하거나 이미지를 업로드(‘Upload files’) 할 수 있다. image

  • 이미 새로 생성된 브랜치에서 수정이므로 수정 내역을 바로 커밋한다. 새로 만든 브랜치 이름을 확인할 수 있다. image

병합 / 리뷰 요청 하기

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

  • 본인이 생성한 브랜치(실제로는 브랜치에 연결된 pull request)를 선택한다. image

  • 변경 내역을 확인 후 바로 병합하거나 리뷰 요청을 할 수 있다. 오너는 자동으로 리뷰어로 선택된다.

    • 변경 내역: 변경 내역을 확인, ‘files changed’를 누르면 모든 변경 내역을 한번에 확인 가능
    • 중단에 변경 내용이 자동으로 배포되었다. 해당 주소를 누르면 변경 내역이 배포된 페이지를 확인 할 수 있다.
    • 오른쪽 상단에서 리뷰를 요청 할 수 있다. 멤버에서 github id를 확인하고 선택하면 된다.
    • 하단에서 바로 병합할 수 있다. image

리뷰 하기

slack에서 github를 연결하세요.

/github signin

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

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

리뷰 확인 후 병합

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

🧨 축하합니다. 🚀

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

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

팬시하게 페이지 꾸미기

용어 정리

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