"오픈소스 기여 실전, 처음이면! 개발가이드 컨트리뷰션으로 쉽게 시작하세요!"라는 영상을 보면서 작성한 내용입니다. 중간중간 영상에서 휙휙 지나간 내용을 좀 더 자세히 정리해 봅니다.
이렇게 이야기하지만 저도 뭔가 중간중간 넘어간 것이 있을 수 있으니 양해를~~
https://youtu.be/HL8VIV9JHdU?si=xGh6xwKylmBvf_Vn
- 컨트리뷰션이란 무엇인가?
오픈소스 프로젝트에 참여하고 기여하는 (모든) 활동을 의미함
(아쉬운 부분은 영상이 30분 분량인데, 5분 정도를 컨트리뷰션에 대한 설명으로 채웠다는 것. 물론 다른 주제 속에서 컨트리뷰션에 대한 발표였다면 이해할 수 있지만, 컨트리뷰션을 안내하는 이전 영상과 이어지는 영상이라서 굳이 또 설명을 할 필요가 있었을까 싶음. 문서화 컨트리뷰션에 관심이 있다면 5분 26초부터 보셔도 됩니다).
- More Common Than You Think: An In-Depth Study of Casual Contributors
컨트리뷰션에서 상당 부분을 문서화가 차지하고 있다는 이야기를 하면서 언급한 논문입니다. 논문 제목에서도 알 수 있지만, Casual Contributor에 대한 연구입니다. Casual Contributor는 프로젝트에 한 번 또는 아주 적은 횟수로 기여하는 기여자를 의미한다고 합니다.
전체 커밋에서 Casual Contributor의 비중은 1.73%로 아주 적은 수치라서 컨트리뷰션의 패턴으로 보기는 애매하지만, 이 영상에서 설득(?)하고자 하는 대상이 어쩌면 Casual Contributor라서 적절한 논문이 아닌가 싶습니다.
단순 오타/문법 수정이 가장 많고, 문서 내 예시 코드 수정이라든지 번역 추가 등의 작업이 있었고, 간혹 문서를 좀 더 명확하게 재작성하는 경우도 있었다고 합니다. 문서화는 초보자가 OSS 커뮤니티에 첫발을 내디딜 수 있는 쉬운 경로라는 점을 강조하고 있으며, 작은 노력이지만 프로젝트의 신뢰성과 접근성, 사용성을 향상하는데 중요한 역할을 하는 것이라고 합니다.
https://news.ycombinator.com/item?id=11977747
https://naver.github.io/OpenSourceGuide/book/BetterContribution/why-contribute-to-open-source.html
- 표준프레임워크 개발가이드 컨트리뷰션
작년(2024년)부터 시작했다고 합니다. 기존에는 코드나 버그 수정에 중점을 두었는데, 좀 더 사용자의 진입 장벽을 낮추고자 하는 시도가 아닌가 싶습니다. 작년에는 문서와 코드가 하나의 저장소에 있었는데(아마도), 올해는 문서를 위한 저장소를 분리했다고 합니다.
https://github.com/eGovFramework/egovframe-docs
작년 개발가이드 컨트리뷰션은 DokuWiki 기반의 문서를 Markdown 형식의 문서로 변환하는데 중점을 두었다고 합니다(아, 이게 운영을 위한 저장소를 분리한 것이 아니라 Markdown 문서 변환을 위한 저장소로 분리를 한 것이네요). 작년은 처음 시작이라 여러 시행착오가 있었는데, 그중 하나가 내가 작성한 PR이 어떻게 반영되는지 알기가 어려웠다는 점이라고 합니다. 그래서 올해는 컨트리뷰션이 반영된 결과물을 볼 수 있도록 미리 보기를 제공한다고 합니다(뭐 따로 만든 건 아니고 그냥 github에서 제공하는 기능이지만...)
https://egovframework.github.io/egovframe-docs/
- KRDS 디자인 반영
문서 기본 디자인을 반영하기 위해 Frontmatter 작성 시 유의해야 한다고 합니다.
KRDS는 대한민국 정부 디자인 시스템입니다. 공공 프로젝트 시 이 가이드라인을 따르도록 권장하고 있어서, 공공 프로젝트에 참여하는 많은 기업들이 KRDS에 최적화된 서비스를 제공하려고 준비를 하고 있다고 합니다.
https://www.krds.go.kr/html/site/index.html
- 컨트리뷰션 환경 준비 (저장소 포크)
17분 07초부터입니다. 여기부터 실제 어떤 일을 해야 하는지 설명합니다.
1. GitHub 계정을 만들거나 로그인합니다.
2. 표준프레임워크 포털 가이드 문서 저장소로 이동합니다.
https://github.com/eGovFramework/egovframe-docs
3. 문서 저장소를 포크합니다.
문서 저장소 화면 오른쪽 위에 있는 버튼 중 "Fork"라고 쓰여있는 버튼 비슷하게 생긴 영역을 클릭합니다.
용어가 익숙하지 않은데, 원본 데이터를 복사하는 작업입니다.
"Create a new form" 화면이 나오면 "Create fork" 버튼을 클릭합니다.
복사가 완료되면 여러분의 계정에 표준프레임워크 포털 가이드 문서 저장소가 만들어진 것을 확인할 수 있습니다.
- 컨트리뷰션 환경 준비 (문서 작성 도구)
영상에서 설명은 Visual Studio Code(VS Code) 기준으로 설명합니다.
https://code.visualstudio.com/
- 컨트리뷰션 환경 준비 (저장소 클론)
영상에서는 클론을 하구요~ 라고만 하고 지나가서~ 좀 더 자세하게 설명하자면
1. 복사한 내 저장소에서 저장소 URL을 복사합니다.
문서 저장소 화면 오른쪽 위에 있는 버튼 중 "Code"라는 초록색 버튼을 클릭하면 "Clone" 창이 표시되고 HTTPS URL을 복사할 수 있습니다.
2. VS Code를 실행합니다.
3. 명령 팔레트를 엽니다.
Ctrl + Shift + P 키를 입력하면 VS Code 상단에 작은 입력창이 표시됩니다.
4. 명령 팔레트에서 "git clone"을 검색합니다.
5. 검색 결과에서 "Git: Clone"으로 표시된 항목을 선택합니다(클릭하거나 엔터키를 입력하면 됩니다).
6. 저장소 URL을 입력합니다.
1번 단계에서 복사한 URL을 입력합니다.
7. 저장소 리소스를 복사할 로컬 폴더를 선택합니다.
클론이라는 것이 GitHub에 있는 내용을 내 컴퓨터로 가져오는 것이라서 저장할 로컬 폴더를 선택해야 합니다.
8. 클론(복사)이 완료되면 "Open"을 선택합니다.
이제 영상에서 보이는 것처럼 EGOVFRAME-DOCS 프로젝트가 표시됩니다.
(Open 실행 시 폴더를 신뢰하느냐 물어보기도 하는데, 내 컴퓨터니깐 믿고 체크를 하면 됩니다).
VS Code EXPLORER에서 .md 파일을 클릭해보면 미리보기가 제공되지 않는데, 다음에 설명할 플러그인을 설치해야 합니다.
- 컨트리뷰션 환경 준비 (Markdown All in One)
.md 파일을 미리 보기 하거나 기타 여러 가지 마크다운 확장 기능을 사용하기 위한 용도입니다.
1. VS Code 왼쪽 메뉴바에서 Extensions 아이콘을 클릭합니다.
2. 검색창에 "Markdown All in One"을 입력합니다.
3. 결과 목록에서 "Markdown All in One"을 확인하고 "Install" 버튼을 클릭합니다.
4. .md 파일을 열고 화면 오른쪽 위에 있는 버튼 중 첫 번째 "Open Preview to the side" 버튼을 클릭하면 화면 오른쪽에 미리보기창이 열립니다.
- 컨트리뷰션 해보기
20분 40초 정도부터 다시 표준프레임워크 포털 가이드 문서 저장소부터 차례로 설명해 줍니다.
실제 어떻게 하는지만 궁금하다면 여기부터 보셔도 되겠네요(라고 생각했는데 그냥 저장소의 readme를 쓰윽 살펴보는 정도라서 ㅠㅠ).
차례차례 따라가야 할 듯합니다.
- 컨트리뷰션 환경 준비 (upstream 연결)
저장소를 클론해서 내 PC에서 내용을 작성한 후 PR 요청을 하려고 하는데요.
같은 시간 다른 분들도 업데이트를 할 수 있으니 저장소가 최신 상태를 유지하고 충돌이 생기지 않게 설정을 해주어야 합니다.
이제부터는 터미널을 열고 명령어를 직접 입력합니다.
VS Code 화면 하단에 터미널이 열려있으면 열려있는 터미널에서 진행하고 그렇지 않다면
1. 메뉴에서 [Terminal > new Terminal]을 선택합니다.
2. 하단에 열린 터미널에 아래 명령어를 입력합니다.
git remote add upstream https://github.com/eGovFramework/egovframe-docs.git
3. 제대로 처리되었는지 확인하기 위해 아래 명령어를 입력합니다.
git remote -v
아래와 같이 결과가 나오면 정상입니다.
origin 항목은 여러분의 저장소 URL이 나와야겠죠. upstream 항목만 확인하세요.
| origin https://github.com/koko8829/egovframe-docs.git (fetch) origin https://github.com/koko8829/egovframe-docs.git (push) upstream https://github.com/eGovFramework/egovframe-docs.git (fetch) upstream https://github.com/eGovFramework/egovframe-docs.git (push) |
- 컨트리뷰션 작업 준비
원본 저장소와 싱크를 맞추는 작업입니다.
아래 순서에 따라 터미널에 명령어를 입력합니다.
git fetch upstream main
git checkout main
git merge upstream/main
(머지 또는 리베이스 중에 선택을 하라고 하는데, 리베이스는 충돌 시 복잡하게 꼬일 수 있어서 머지를 권장합니다).
git push origin main
저장소 클론 이후에 바로 작업 준비를 했다면 최신 상태이기 때문에 바로바로 넘어갈 겁니다.
- 컨트리뷰션 작업 결과 반영
수정한 결과물을 반영하는 작업입니다.
아래 순서에 따라 터미널에 명령어를 입력합니다.
git add .
git commit -m "커밋 메시지 작성"
파일을 저장하고 정상적으로 커밋이 되었다면 아래와 같이 메시지가 나옵니다.
| [main 9ed3910] 커밋 메시지 작성 1 file changed, 25 insertions(+), 8 deletions(-) |
이제 충돌을 방지하기 위해 작업 준비에서 했던 것과 비슷하게 작업을 합니다.
git fetch upstream main
git merge upstream/main
문제가 없다면 내 origin에 푸시합니다.
git push origin main
이렇게 하면 내 저장소에서 방금 커밋한 내용을 확인할 수 있습니다.
- 컨트리뷰션 작업 결과 PR
1. 내 저장소에서 "Compare & pull request" 버튼을 클릭합니다.
("Compare & pull request" 버튼이 보이지 않을 수 있습니다. 정상적으로 커밋이 된 상태라면 "Contribute" 버튼을 클릭하고 "Open pull request" 버튼을 클릭해서 진행합니다).
2. 제목과 설명 입력 후 "Create pull request" 버튼을 클릭합니다.
버튼을 누르면 입력 창이 나오고 자세한 예시 설명이 작성되어 있습니다.
정상적으로 PR이 등록되었다면 자동으로 체크하고 배포가 됩니다.
(수동으로 리뷰하는 과정은 없는 듯합니다).
작업한 페이지가 https://egovframework.github.io/egovframe-docs에 정상적으로 배포가 되었는지 확인합니다.
* 참고로 "2025년 전자정부 표준프레임워크 컨트리뷰션"이라는 이름으로 5월 19일부터 9월 19일까지 이벤트(?)가 진행되고 있습니다.
소스코드 개선, 아이디어 제안, 가이드 개선 3가지 분야로 참여할 수 있는데, 소스코드와 가이드 개선은 그냥 PR을 올리면 참여가 되는 건지 모르겠네요.
아. 안내 메일을 보니 GitHub 계정 메일로 안내 메일을 발송한다고 합니다.
https://www.egovframe.go.kr/home/ntt/nttRead.do?pagerOffset=0&searchKey=&searchValue=&menuNo=74&bbsId=6&nttId=1914
* 오랜만에 PR을 올리다 보니 많이 당황스럽네요. 예전에는 이것보다 간단했던 것 같은데 ^^
