Github 간단 튜토리얼 (2판)

Transcript

1. Github 간단 튜토리얼 (2판) 김태인 tikim@dsp.inha.ac.kr 요약 버전관리 및 이슈트래커 서비스를 제공하는 웹사이트인 Github 를 소개하고 연구실에서 Github 를 이용하여 업무를 진행할 때 알아야 하는 부분들을 설명하였다.
2. 페이지 1 / 19 목차 1. Github 소개 ........................................................................................................................... 2 2. 저장소 (Repository) ................................................................................................................ 4 3. 이슈 트래커 (Issue Tracker) ..................................................................................................... 7 3.1. 이슈 트래커를 활용한 업무흐름의 예시............................................................................... 8 3.1.1. 프로그램 코드를 작성하지 않는 리포의 이슈 트래킹 ................................................... 8 3.1.2. 프로그램 코드를 작성하는 리포의 이슈 트래킹 ........................................................ 11 4. 로컬 개발 환경 준비 ............................................................................................................... 13 4.1. Github Desktop.......................................................................................................... 14 5. 풀 리퀘스트 (Pull Request) .................................................................................................... 16 5.1. 포크한 저장소의 변경사항이 원본 저장소에 반영되도록 요청하기 .......................................... 17 5.2. 서로 다른 브랜치의 변경사항이 반영되도록 요청하기 .......................................................... 19
3. 페이지 2 / 19 1. Github 소개 Github는 분산형 버전 관리 시스템(VCS, Version Control System)인 Git 서비스를 제공하는 웹사이트이다. Git은 메인 저장소(Repository)를 기반으로 다양한 클론(Clone) 저장소와 브랜치(Branch)를 만들어 각각의 시 점에서 자유롭게 버전관리가 가능하고 상호 병합도 용이하여 최근에는 대부분의 프로그램 소스코드를 대상으로 한 버전 관리시스템으로써 사용되고 있다. Github에서 제공하는 주요 서비스로는 저장소, 이슈트래커(Issue tracker), 풀 리퀘스트(Pull Request), CI/CD (지속적 통합/지속적 제공)이 있으며, 본 문서에서는 CI/CD를 제 외한 나머지 3가지 서비스에 대해 설명한다.
4. 페이지 3 / 19 (이 시점에서 Github 계정이 없다면 먼저 생성해두는 것을 권장합니다)
5. 페이지 4 / 19 2. 저장소 (Repository) 저장소는 Github에서 생성할 수 있는 Git 기반 버전 관리 시스템의 기본적인 단위로서, 일반적으로 공통된 성 격을 가지고 있는 프로그램 코드 혹은 문서, 미디어 등을 이 저장소에 모아 관리하는 형태로 이용한다. 일반적 으로 저장소를 생성하게 되면 해당 저장소의 주소는 github.com/[개인 ID 혹은 단체 이름]/[리포지토리 이름] 과 같은 형태로 부여된다. Git을 기반으로 제공된 저장소이므로 보통은 Git 관리 프로그램 등을 통해 저장소를 로컬 컴퓨터에 내려 받고 파일을 추가하거나 수정해야 하지만, Github는 웹페이지에서도 파일을 업로드/삭제 할 수 있으며, 텍스트 형식의 파일이라면 수정도 바로 가능하다. 이미 생성된 저장소를 로컬에 복사하고 싶다면 해당 저장소 메인 페이지에서 "Code▼" 버튼을 누른 다음 "Open with Github Desktop" 혹은 "Download ZIP"을 선택하면 된다. 그림 1. Github 저장소의 예시1 만약 새로운 저장소를 만들고 싶다면 그림 2 와 같이 Github 페이지 맨 우측 상단에 있는 "+ ▼" 버튼을 누른 다음 "New repository"를 선택하면 된다. 새 저장소를 만들 때는 보통 그림 3 처럼 README 파일을 기본 생성하도록 체크하고, 프로그램 코드가 저장될 예정이라면 해당 코드의 컴파일 결과물 및 부산물 같은 일시적인 파일들이 버전관리에 추가되지 않도록 해당 코드 언어의 gitignore 파일을 선택하여 추가하고, 해당 저장소의 라이선스까지 선택해주는 것이 일반적인 상황에서 권장된다. 1 https://github.com/dotnet/core
6. 페이지 5 / 19 그림 2. Github에서 새 저장소를 만드는 위치 그림 3. Github에서 새 저장소를 만드는 예시
7. 페이지 6 / 19 이 때 README 파일에는 해당 리포를 개발 혹은 실행하는데 필요한 정보들이 모두 작성되어 있어야 한다. 다른 사람이 해당 코드를 언제든지 받아서 실행할 수 있을 정도로 준비되어야 하며, 이렇게 정리해둔 정보는 나중에 리포를 만든 본인이 시간이 지나 세부적인 실행 방법을 잊어버렸을 때에도 많은 도움이 될 수 있다. 그림 4는 일반적인 프로그램 코드를 포함하는 리포의 README.md 작성 예시이다. 크게는 문서 정보, 개발 환경, 실행 환경, 개발 주의사항 등을 작성하면 된다. 개발 단계에만 머물러 있는 코드라면 개발 환경만 작성하면 되지만, 일반인 같은 최종 사용자가 있는 프로그램을 만드는 경우라면 최종 사용자를 위한 실행 환경도 작성해둬야 한다. 개발 환경은 해당 리포의 소스코드를 받은 임의의 개발자가 문제없이 개발을 이어나갈 수 있을 정도의 정보를 명시해야 한다. 프로그램 언어, 사용한 IDE, 라이브러리 등을 적으면 된다. 그림 4. README.md 파일의 예시 (1) 그림 5처럼 Anaconda 등의 가상환경을 사용한 경우 반드시 가상환경을 재현할 수 있는 environment.yml 등과 같은 파일을 첨부하고 이걸로 가상환경을 복구할 수 있는 방법도 적어야 한다. 파이썬 라이브러리(PIP)를 이용한 경우 freeze 명령어를 이용해 environment.txt를 추출하는 것도 좋지만 반드시 필요한 라이브러리(및 버전)만 특정해서 적는 것이 더 좋다. 그림 5. README.md 파일의 예시 (2)
8. 페이지 7 / 19 3. 이슈 트래커 (Issue Tracker) 이슈 트래커란, 특정 프로젝트 혹은 개발을 진행하는 도중에 생기는 문제점이나 건의사항 같은 각종 안건들을 한 곳에 기록하고 해결하기 위한 시스템이다. 일반적으로 Bugzilla, Mantis, Redmine, Trello, Jira 같은 3rd party 이슈트래커들이 많이 있으나 Github는 자체적으로 저장소 별로 이슈 트래커를 제공한다. 이슈를 관리하 고 싶은 저장소에서 좌측 상단에 있는 "⊙ Issues" 탭을 누르면 이슈 트래커로 이동할 수 있다. Github는 기본 적으로 프로그램 코드를 관리하는 것에 최적화된 시스템이지만, 이슈 트래커를 자체적으로 제공하기 때문에 문 서, 그림, 정책 등과 같이 프로그램 코드가 아닌 것을 관리할 용도로 사용할 수도 있다. 그림 6. Github 저장소의 이슈트래커 예시2 이슈는 그림 7과 같이 생성할 수 있으며, 우측에서 해당 이슈의 담당자나 카테고리 등을 배정할 수 있다. 그림 7. 이슈 생성 예시 2 https://github.com/sappho192/IronworksTranslator/issues
9. 페이지 8 / 19 Github 이슈 트래커는 마일스톤(Milestones)이라는 기능도 제공하는데, 이는 이슈들이 프로젝트의 특정 버전 혹은 기한까지 완료되어야 할 때 유용하게 사용할 수 있다. 예를 들어 그림 8은 저장소에서 생성한 이슈들이 "1.0.0" 혹은 "In future"에 속해있는 것을 보여주는데, 전자는 프로그램의 다음 공개 버전인 1.0.0이 되기 위 해 해결해야 할 이슈들이 모여있는 것이고, 후자는 1.0.0 이후에도 언젠가 해결되면 좋은 이슈들이 모여있는 것이다. 그림 8. Github 마일스톤 예시3 3.1. 이슈 트래커를 활용한 업무흐름의 예시 앞서 설명한 이슈트래커를 실무에서 사용할 때는 어느 정도 일관된 작업흐름이 존재한다. 여기서는 두 가지 유 형의 리포에서의 이슈 트래킹 예시를 들어 설명한다. 3.1.1. 프로그램 코드를 작성하지 않는 리포의 이슈 트래킹 https://github.com/InhaDSP/GeneralDuties DSPLab의 리포 중 프로그램 코드를 작성하지 않는 대표적인 리포는 GeneralDuties이다. 본 리포는 연구실에 서 이뤄지는 일반적인 업무들(물품 구매, 장비 고장 신고 등)을 관리하기 위한 것으로, 특정 사안이 발생했을 때 이슈를 생성하여 진행하면 된다. 3 https://github.com/sappho192/IronworksTranslator/milestones
10. 페이지 9 / 19 그림 9. 정수기 생수 구매 이슈 그림 9에는 연구실 생수를 구매하고 싶은 학생이 생성한 이슈의 예시가 들어있다. [링크] 이슈를 생성한 사람은 일반적으로 이슈를 생성할 때 아래와 같은 정보를 모두 기록해야 한다. ① 이슈의 원인에 대한 간략한 설명 ② 이슈를 해결할 수 있는 사람 (멘션의 형태로 기록) ③ (가능하다면) 이슈를 해결할 수 있는 방법 ④ 담당자(Assignees) 배정 ⑤ 이슈 레이블(Labels) 배정 이때 이슈 레이블은 그림 10과 같은 목록에서 가장 적절한 것들을 고르면 된다. 이렇게 달아둔 레이블은 나중에 이슈 목록에서 해당 레이블을 클릭하면 그림 11 과 같이 해당 레이블을 가지고 있는 이슈들만 모아서 볼 수도 있다. 그림 11. 모범 사례 레이블을 갖고 있는 이슈 그림 10. 이슈 레이블의 종 류
11. 페이지 10 / 19 그림 12. 인용(Quote)를 이용한 코멘트 답변 그림 12는 인용을 이용하여 코멘트에 답변한 예시이다. 앞선 사람들의 발언 중 답변해야 할 부분을 특정해야 할 경우 Quote Reply 기능을 이용하면 정확히 어떤 부분에 대한 답변인지를 명시할 수 있다. 그림 13. 이슈를 다시 열고 진행한 예시 일반적인 이슈들은 일회성의 성격을 갖고 있어 문제가 해결되면 이슈를 닫고 끝나게 되지만, 미처 알지 못했던 문제가 남아있었거나 해당 이슈가 재발했을 경우에는 그림 13처럼 이슈를 다시 열고 문제를 해결한 다음에 다 시 닫을 수도 있다. [링크]
12. 페이지 11 / 19 3.1.2. 프로그램 코드를 작성하는 리포의 이슈 트래킹 프로그램 코드를 작성하는 리포에서도 일반적인 작업 과정은 앞에서의 과정과 유사하지만, 정확히 어떤 파일 의 코드가 (잠재적인) 문제를 갖고 있는지를 직접적으로 명시하거나 특정 커밋에서 해결이 되었다는 정보를 알 려줘야 하는 경우가 있다. 그림 14. 특정 코드를 직접 언급하는 이슈 그림 14의 이슈에서는 본문에서 문제가 되는 코드를 직접 언급하고 있으며, 이를 해결할 수 있을 것 같은 참고 자료들을 언급하고 있다. 그림 15와 같이 언급을 원하는 코드의 페이지에서 해당 코드의 줄 번호를 클릭한 다 음 Copy permalink를 선택하면 해당 코드의 링크를 얻을 수 있다. 이것을 코멘트 본문에 붙여넣으면 그림 14 처럼 Github에서 자동으로 코드를 예쁘게 표시해준다. 만약 여러 줄을 보여주고 싶다면 그림 16처럼 Shift를 누른 상태에서 코드의 시작 줄 번호와 끝나는 곳의 줄 번호를 클릭한 다음 링크를 얻으면 된다. 그림 15. 특정 코드의 주소를 얻는 방법 그림 16. 여러 줄의 코드를 참조하는 방법
13. 페이지 12 / 19 또한 해당 이슈를 특정 커밋에서 해결했을 경우, 코멘트로 해당 커밋을 언급하는 것도 좋다. 커밋 이력으로 가면 그림 17 처럼 특정 커밋의 고유값인 해시값을 복사할 수 있다. 이것을 복사해서 그림 18 처럼 코멘트에 붙여넣으면 Github 에서 예쁘게 표시해준다. 그림 17. 커밋의 해시값을 얻는 방법 그림 18. 코멘트에서 커밋의 해시값을 언급한 예 이슈를 진행하다보면 이전에 생성했던 이슈와 관련이 있는 경우도 생기며, 파생 이슈를 생성하게 되는 일도 있다. 이럴 땐 그림 19 처럼 코멘트 본문에서 #을 이용해 이슈 혹은 풀 리퀘스트의 번호를 적으면 해당 이슈를 언급할 수 있으며, 그 후 언급된 이슈 내에서는 특정 이슈가 해당 이슈를 언급했다는 내역이 추가된다. [예시] 그림 19. 이슈 혹은 풀 리퀘스트를 언급하는 방법
14. 페이지 13 / 19 4. 로컬 개발 환경 준비 Github에서 생성된 저장소를 로컬 컴퓨터 환경에 가져와서 작업하는 방법은 간단하다. 2장에서 설명했듯이 저장소 메인 페이지에서 "Code▼" 버튼을 누른 다음 "Open with Github Desktop" 혹은 "Download ZIP"을 선택하면 된다. 다만 "Download ZIP"을 선택하면 git 버전관리 내역이 들어있는 ".git" 폴더는 제거된 상태로 받아지기 때문에 이것은 최종 유저(End user) 입장에서 이용하기 좋은 선택지이며 저장소에 기여하기 위해선 "Open with Github Desktop"을 선택하는 것이 적절하다. 바로 다음 장에서 Github Desktop을 이용한 개발 환경 준비 및 실제 개발 과정을 간단히 소개한다.
15. 페이지 14 / 19 4.1. Github Desktop Github Desktop은 Github에서 제공하는 GUI git 관리 프로그램이며, https://desktop.github.com/ 에서 받을 수 있다. 만약 컴퓨터에 git이 설치되어 있지 않다면 본 프로그램이 설치되는 시점에 자동으로 최신 버전 의 git이 설치된다. Github Desktop이 설치된 이후에 임의의 저장소 페이지에서 "Open with Github Desktop"를 클릭하면 해당 저장소를 로컬에 복사해올 수 있으며 로컬에서 임의로 버전 관리도 가능하다. 그림 20. Github Desktop 화면 예시 그림 20에서처럼 로컬에서 이뤄진 변경사항들을 선택하고 좌측 하단에 변경사항들의 요약을 작성하면 이를 로 컬 git에 반영할 수 있으며, 이를 커밋(Commit)이라고 한다. 이렇게 수행한 커밋을 Github에 있는 실제 저장 소에 반영하려면 그림 21과 같이 프로그램 우측 상단에 있는 "Push origin" 버튼을 누르면 된다. 다만 본인이 해당 저장소에 직접 변경사항들을 push 할 수 있는 권한을 가지고 있어야 한다. 만약 권한을 갖고 있지 않을 때에는 두 가지 해결 방법이 있다. 그림 21. 로컬 저장소의 변경사항을 원본 저장소에 반영하는 UI
16. 페이지 15 / 19 첫 번째 방법으로는 저장소의 주인이 "Settings" 탭의 "Collaborators" 페이지에서 직접 push를 원하는 사 람의 github 계정을 추가하고 "Write" 이상의 권한을 부여하는 방법이다. 다만 일반적으로는 이렇게 저장소의 변경사항을 직접 반영할 수 있는 권한은 프로젝트 매니저와 같이 최종 결정 권한을 가지고 있는 사람 한정으로 부여하는 것이 좋다. 두 번째 방법은 통상적으로 git 및 Github에서 지향하는 기여 방법으로, 다음 장에서 소 개한다. 그림 22. 저장소 Collarborators 추가 페이지
17. 페이지 16 / 19 5. 풀 리퀘스트 (Pull Request) 풀 리퀘스트는 외부로부터의 변경사항을 내부에 반영하고 싶을 때 진행할 수 있는 절차이다. 이러한 상황은 크게 두 가지로 나뉠 수 있다. 1. 저장소의 주인이 아닌 사람이 포크(Fork)를 통해 저장소를 자신의 소유로 복제한 후, 변경사항들을 커 밋하고 이를 다시 주인의 저장소로 반영시켜 기여하고 싶을 때 2. 저장소의 특정 브랜치에서 이뤄진 변경사항(커밋)들을 또다른 브랜치에 반영시키고 싶을 때 두 가지는 공통적으로 서로 다른 고유 브랜치 간의 변경사항을 병합한다는 특징이 있다. 예를 들어, Taein 이 라는 유저가 Project2022 라는 저장소를 생성하면 기본적으로 활성화되는 main 브랜치는 엄밀히 말하면 Taein/Project2022-main 브랜치이다. 앞서말한 1의 경우는 Bowon 이라는 유저가 Taein/Project2022 저장소를 클론하여 Bowon/Project2022 라는 본인 소유의 저장소를 포크를 통해 새롭게 복제한 다음, Bowon/Project2022-main 브랜치에서 변경사 항들을 커밋하고 이들을 Taein/Project2022-main 브랜치에 반영하기 위해 풀 리퀘스트를 생성하여 Taein 유 저의 승인을 받으려는 경우를 예시로 들 수 있다. 그럼 2의 경우는 Taein 유저가 Taein/Project2022-main 브랜치로부터 develop이라는 브랜치를 새로 생 성하여(Taein/Project2022-develop) 변경사항들을 커밋한 다음, 이를 다시 main 브랜치에 반영하려고 할 때 를 예시로 들 수도 있고, 역으로 Taein/Project2022-develop 브랜치까지의 변경사항들을 Bowon/Project2022-main 브랜치에 반영하고 싶을 때도 예시로 들 수 있다. 그림 23. 풀 리퀘스트를 통한 브랜치 병합 과정 실제로 각 경우를 진행하는 방법은 다음 장에서 설명한다.
18. 페이지 17 / 19 5.1. 포크한 저장소의 변경사항이 원본 저장소에 반영되도록 요청하기 먼저 1의 경우는 자신의 소유가 아닌 원본 저장소를 포크하여 자신 소유의 복제본 저장소를 만드는 것으로 시 작한다. 본 장에서는 연구실에서 실험삼아 만들어 놓은 [저장소]를 포크하는 과정을 예시로 활용하였다. 그림 24의 우측 상단에 "Fork" 버튼을 누르는 것으로 간단히 포크가 완료된다. 그림 25의 좌측 상단을 보면 저장소 의 주인이 InhaDSP에서 sappho192로 바뀌어 있는 것을 확인할 수 있으며, 바로 하단에 작은 글씨로 원본 저장소의 출처도 표기되어 있다. 또한 포크된 저장소들은 그림 25의 좌측 하단처럼 원본 저장소와 변경사항이 얼마나 차이나는지(앞서있거나 뒤떨어져있거나) 표시되어 있다. 그림 24. 원본 저장소의 상단 메뉴 그림 25. 포크된 저장소의 상단 메뉴 여기서는 저장소에 있는 "README.md" 파일을 Github에서 직접 수정하는 것으로 새로운 커밋을 만들었다. 따라서 그림 26과 같이 원본 저장소로부터 1개의 앞선 커밋이 있다는 것이 확인되고 있다. 여기서 "Contribute" 버튼을 눌러 나오는 "Open pull request"를 선택하면 풀 리퀘스트가 생성된다. 그림 26. 변경사항이 생겼을 때 포크된 저장소 상태 그림 27. Contribute 버튼을 통한 Pull request 생성
19. 페이지 18 / 19 풀 리퀘스트를 생성하기 전에 그림 28와 같이 어떤 저장소(head repository) 의 브랜치에서 어떤 저장소 (base repository)의 브랜치로 변경사항을 반영하고 싶은지를 선택할 수 있고, 하단에서는 커밋 별 변경사항들 을 확인할 수 있다. "Create pull request"를 누르면 그림 29과 같이 이슈 생성 페이지와 비슷한 화면이 나오며, 작성 방법도 거의 비슷하다. 해당 페이지에서 마지막으로 "Create pull request"를 한 번 더 누르면 실제로 풀 리퀘스트가 생성되게 된다. 리퀘스트를 받은 저장소 주인은 그림 30처럼 병합 승인을 내릴 수 있다. 그림 28. 풀 리퀘스트 생성 페이지 그림 29. 풀 리퀘스트 정보 작성 페이지 그림 30. 풀 리퀘스트 병합 UI
20. 페이지 19 / 19 5.2. 서로 다른 브랜치의 변경사항이 반영되도록 요청하기 여기서는 앞서 설명한 경우의 두 번째의 진행 과정을 설명한다. 먼저 포크한 본인의 저장소에서 페이지 왼쪽 에 있는 "main" 브랜치 버튼을 클릭하면 그림 31처럼 새로운 브랜치의 이름을 입력하고 생성할 수 있다. 그림 31. Github에서 새로운 브랜치를 생성하는 UI 본 예시에서는 develop 브랜치를 생성한 다음 해당 브랜치로 이동하고, README.md를 다시 적당히 수정 하고 저장하여 커밋을 생성하였다. 그러면 그림 32처럼 develop 브랜치의 변경사항을 가지고 풀 리퀘스트를 바로 만들 수 있도록 새로운 UI가 표시된다. 여기서 "Compare & pull request"를 클릭하면 앞 장에서처럼 풀 리퀘스트를 생성할 수 있게 된다. 그림 32. develop 브랜치의 변경사항으로 인해 풀 리퀘스트 추천이 표시된 모습 이 때 Github에서는 자동으로 반영을 적용할 대상 저장소 & 브랜치와 반영이 존재하는 저장소 & 브랜치를 추 론하여 배정해주는데, 가끔 반영을 적용할 대상 저장소와 브랜치가 의도치 않은 곳으로 지정될 때가 있으니 반 드시 확인할 필요가 있다. 그림 33. 주인과 브랜치가 모두 다른 풀 리퀘스트