중요

번역은 여러분이 참여할 수 있는 커뮤니티 활동입니다. 이 페이지는 현재 100.00% 번역되었습니다.

3. 개발 프로세스

오픈 소스 프로젝트에서 흔히 볼 수 있듯이, 프로젝트에 대한 코드 및 문서의 기여는 높이 평가됩니다. QGIS 커뮤니티가 매우 든든한 지원군이 되어줄 것입니다. 이 장에서는 QGIS 프로젝트에서 여러분의 기여를 개발하고 병합하는 절차에 대해 설명합니다.

3.1. 깃 기반 프로젝트 

지난 몇 년 동안 QGIS 소스 코드는 현저히 복잡해져 왔습니다. 따라서 어떤 기능을 추가하는 것이 가져올 부작용을 대처하는 일도 힘들어졌습니다. 과거에는 QGIS 프로젝트의 배포 주기가 매우 길었습니다. 새 기능들을 추가한 다음 소프트웨어 시스템의 안정성을 다시 확립하는 데 많은 작업이 필요했기 때문입니다. 이런 문제점을 극복하기 위해 QGIS는 깃(git) 버전 제어 시스템을 사용하는 개발 모델로 전환했습니다. 이 모델은 먼저 기여자의 분기에 새 기능의 코드를 작성하고, 새 기능의 개발이 완료되고 안정되었을 때 QGIS 마스터(또는 주 분기)에 병합합니다.

QGIS 소스 코드는 https://github.com/qgis/QGIS 에 호스팅됩니다.

3.1.1. 역할 

깃허브(GitHub)에는 여러 역할(role)들이 존재합니다. 깃허브에서 계정을 개설하는 순간 여러분은 이미 저장소의 포크(fork)를 생성해서 기여할 수 있는 권한을 가지게 됩니다. ‘contributor’ 역할이죠. 핵심 개발자들은 ‘collaborator’ 역할로, 분기들을 업스트림과 공식 저장소로 병합시킬 수 있는 권한을 가집니다.

3.1.2. 환경 

QGIS 저장소를 사용해서 기여를 시작하려면, 다음 단계를 거쳐야 합니다:

깃허브 계정 을 만들기
여러분 고유의 QGIS 저장소 를 만들기 (포크 문서를 참조하세요)
시스템 상에 깃 클라이언트를 설치하기
여러분의 깃 환경 을 설정하기
그리고 재미있게 놀아보세요!

3.1.3. 깃 설치하기 

깃 프로젝트는 대부분의 플랫폼에 대해 소프트웨어 최신 버전을 제공하고 있습니다. https://git-scm.com/downloads 에 있는 지침을 따라 여러분의 OS 및 아키텍처에 해당하는 복사본을 다운로드해서 설치하십시오. 이 웹페이지에서 여러분의 저장소를 탐색하고 관리할 수 있는 깃 GUI 클라이언트도 설치할 수 있습니다. (대부분의 경우, GUI 클라이언트를 사용할 수 없다면 깃을 설치할 것입니다.)

3.2. 분기에서 개발 

3.2.1. 개발에 기여하기 

깃허브에 로그인해서 저장소의 포크를 생성하고 나면, 기여자(contributor) 역할로 참여할 수 있습니다.

참고

깃허브 웹사이트에 있는 여러분의 저장소 포크에서 QGIS 코드에 기여할 수 있습니다. 테스트 환경이 새로운 코드를 자동으로 빌드할 것입니다. 그러나 여러분이 복합적인 변경 사항들을 제공하고자 할 때 이 워크플로의 한계가 빠르게 드러날 수 있습니다. 다음 지침들은 로컬 클론 환경을 가정한 것입니다.

끌어오기(pull) 요청을 개시해서 기여할 수 있습니다. 다음 일반적인 단계를 따라해보십시오:

여러분의 로컬 컴퓨터에 여러분의 저장소를 복제 하고 빌드 환경을 설정하십시오.
새 분기를 생성하고 개발을 위해 편집하십시오.
변경 사항을 커밋하고 여러분의 분기를 깃허브에 있는 원격 포크로 다시 푸시하십시오. 그러면 바로 끌어오기 요청의 웹 링크(URL)가 제공될 것입니다.
여러분의 분기에서 마스터 분기로, 업스트림 저장소로 커밋 사항(들)을 끌어오도록 요청하는 끌어오기 요청(PR)을 여십시오.
다른 기여자들과 협업자(collaborator)들에게 여러분의 끌어오기 요청에 대해 알려주는 검토(review) 과정이 시작됩니다. 여러분은 이들의 의견과 제안에 적극적으로 대응해야 합니다.

참고

https://reflectoring.io/github-fork-and-pull/ 에서 깃허브의 포크&풀 워크플로에 대한 더 자세한 내용을 볼 수 있습니다.

참고

QGIS 프로젝트 깃허브 페이지 에서 QGIS 프로젝트 대부분을 (웹사이트, 문서, PyQGIS API, 플러그인 등등) 찾아볼 수 있으며, 동일한 과정을 따라 기여할 수 있습니다.

3.2.2. 저장소에 접근하기 

여러분의 로컬 디스크에서 여러분의 원격 포크와 QGIS 업스트림 저장소들 둘 다와 쌍방향 작업을 할 수 있게 하려면, 다음 작업을 해줘야 합니다:

여러분의 로컬 디스크 상에 여러분의 복사본의 클론을 생성해야 합니다:
```
cd path/to/store/the/repository
git clone https://github.com/<yourName>/QGIS.git
```
여러분의 저장소와 (upstream 이라는 이름을 붙일) QGIS 주 저장소를 연결해야 합니다:
```
git remote add upstream https://github.com/qgis/QGIS.git
```
연결된 원격 저장소들을 확인해야 합니다:
```
git remote -v
# origin   https://github.com/<YourName>/QGIS.git (fetch)
# origin   https://github.com/<YourName>/QGIS.git (push)
# upstream https://github.com/qgis/QGIS.git (fetch)
# upstream https://github.com/qgis/QGIS.git (push)
```
이제 여러분의 로컬 드라이브에서 온라인 저장소에 접근할 수 있으며, origin 이라는 이름을 사용해서 원격 저장소와 쌍방향 작업을 할 수 있습니다. qgis/QGIS 저장소에서 변경 사항을 가져오고 싶을 때마다 upstream 을 사용하십시오.

참고

QGIS는 현재 배포판 분기에 가장 안정적인 코드를 보관합니다. master 분기는 소위 ‘안정적이지 않은(unstable)’ 배포판들의 코드를 담고 있습니다. 정기적으로 마스터 분기로부터 배포판 분기를 생성한 다음, 안정화를 계속하고 마스터에 새로운 기능을 선택적으로 통합할 것입니다.

개발 버전 빌드 작업에 대한 전용 지침을 보고 싶다면 소스 트리에 있는 INSTALL 파일을 참조하세요.

3.2.3. 절차 

메일링 리스트 또는 문제점 저장소에 최초 발표:
개발을 시작하기 전에, 다른 개발자들이 이미 동일한 기능을 작업하고 있지는 않은지 파악하려면 개발자 메일링 리스트에 발표하십시오. 저장소에 문제점이 존재하는 경우 문제점 보고서에 여러분의 관심을 의견으로써 언급할 수도 있습니다. 새 기능을 사용하려면 QGIS 아키텍처를 변경해야 하는 경우, QGIS 개선 제안(QEP) 을 해야 합니다.
여러분의 로컬 저장소에 분기 생성:
마스터 분기의 최신 상태를 바탕으로, 새 기능을 개발하기 위한 새 깃 분기를 생성하십시오.
git fetch upstream master git checkout -b newfeature upstream/master
이제 개발을 시작할 수 있습니다:
여러분의 로컬 디스크에서 여러분이 보통 사용하는 IDE로 변경 사항의 코드를 작성하십시오. 적절한 경우, 여러분의 수정 사항에 대한 테스트 스위트를 작성하는 일을 잊지 마십시오.
깃 저장소에 변경 사항을 커밋:
커밋을 할 때 설명적인 주석을 추가하고, 파일 여러 개에 걸친 변경 사항들이 서로 관련이 없는 경우 소용량 커밋을 여러 번 하는 편이 좋습니다. 반대로, 서로 관련이 있는 변경 사항들은 단일 커밋으로 그룹화하는 편이 낫습니다.
git add path/to/your/files git commit -m "Add a comment describing your nice feature"
이제 여러분의 작업을 QGIS 커뮤니티 멤버들과 공유하고 싶을 수도 있습니다. 여러분의 온라인 저장소 포크에 새 기능을 다음과 같이 푸시하십시오:
```
git push origin newfeature
```
참고

해당 분기가 이미 존재하는 경우 그 분기에 변경 사항을 푸시할 것이고, 존재하지 않는 경우 해당 분기를 생성할 것입니다.
끌어오기 요청으로 변경 사항 제출
끌어오기 요청을 열면, 자동화된 테스트 스위트가 촉발되어 여러분의 변경 사항이 QGIS 코드 작업 지침을 준수하는지 그리고 기존 기능들과 충돌하지는 않는지 확인합니다. 업스트림에 여러분의 분기를 병합하기 전에 보고된 모든 문제점들을 수정해야 할 것입니다.

팁

저장소 상에서의 테스트 실행을 관리하기 위해 깃허브 액션 을 사용합니다. 편의를 위해 변경 사항을 푸시할 때 테스트가 실행되도록 저장소 상에서 액션을 활성화할 수 있습니다. 그 다음 테스트를 모두 통과한 뒤에 끌어오기 요청을 열면 검토 과정을 더 효율적으로 만들 수 있습니다.
정기적으로 업스트림 마스터로 업데이트:
마스터의 변경 사항들을 분기로 통합하기 위해 정기적으로 리베이스(rebase)할 것을 권장합니다. 향후 분기를 다시 마스터로 통합하기 쉬워질 것입니다. 리베이스 후 여러분의 저장소 분기에 git push -f 명령어를 실행해야 합니다.
git pull --rebase upstream master git push -f origin newfeature

참고

GIT 마스터가 되려면 다음 사이트들의 정보를 참조하세요.

3.2.4. 마스터에 다시 병합하기 전에 테스트하기 

여러분이 새 기능 개발을 완료하고 안정성에 만족했을 때, 개발자 메일링 리스트에 발표하십시오. 다시 병합하기 전에 개발자들과 사용자들이 변경 사항을 테스트할 것입니다.

3.3. 끌어오기 요청 제출하기 

패치와 끌어오기 요청을 QGIS로 쉽게 가져오고, 쉽게 사용하기 위해 전달된 패치를 처리하는 데 도움이 되는 몇 가지 지침이 있습니다.

일반적으로 개발자인 경우 깃허브 끌어오기 요청을 제출하는 편이 더 쉽습니다. 여기에서 끌어오기 요청을 설명하지는 않겠지만, 깃허브 끌어오기 요청 문서 를 참조해보세요.

여러분이 끌어오기 요청을 하는 경우 항상 업스트림 마스터 분기에 여러분의 끌어오기 요청 분기를 병합할 수 있도록 여러분의 끌어오기 요청 분기에 마스터 분기를 정기적으로 병합해줄 것을 요청합니다.

여러분이 개발자이고 끌어오기 요청 대기열(queue)을 평가하고자 하는 경우, 명령줄에서 이를 할 수 있게 해주는 도구 가 있습니다.

일반적으로 여러분이 끌어오기 요청을 제출할 때 완료 시점까지 따라가야 할 책임을 져야 합니다 — 다른 개발자들이 게시하는 질의에 응답하고, 끌어오기 요청이 실행되지 않는 것을 발견한 경우 여러분의 기능에 대한 ‘챔피언’을 찾아서 가끔씩 부드럽게 알려줘야 합니다. QGIS 프로젝트는 자발적인 노력으로 운영되기 때문에 사람들이 여러분의 끌어오기 요청에 즉각 참여하지 못할 수도 있다는 사실을 기억하십시오. 들어오는 끌어오기 요청을 모니터링하고 있지만 놓치는 경우도 가끔 있습니다. 기분이 상하거나 놀랄 필요는 없습니다. 여러분을 도와줄 수 있는 개발자를 찾아서 여러분의 패치를 살펴봐줄 수 있는지 요청해보십시오. 끌어오기 요청이 충분한 관심을 받지 못하고 있다고 느끼는 경우, 여러분이 이를 가속화시킬 수 있는 선택지는 (우선 순위대로) 다음과 같습니다:

다른 사람들의 끌어오기 요청을 검토해서 여러분의 끌어오기 요청을 할당받은 사람의 작업량이 줄도록 도와주십시오.
메일링 리스트에 여러분의 끌어오기 요청과 해당 요청이 코드 베이스에 포함되면 얼마나 멋질지를 ‘홍보하는’ 메시지를 전송하십시오.
끌어오기 요청 대기열에서 여러분의 끌어오기 요청을 할당받은 사람에게 메시지를 전송하십시오.
프로젝트 운영 위원회에 여러분의 끌어오기 요청을 코드 베이스로 통합시켜달라고 요청하는 메시지를 전송하십시오.

3.3.1. 끌어오기 요청을 생성하기 위한 모범 사례 

항상 현재 마스터로부터 기능 분기를 시작하십시오.
기능 분기의 코드를 작성하는 경우, 해당 분기에 어떤 것도 “병합”하지 마십시오. 오히려 다음 문장에서 설명하는 대로 리베이스시켜서 이력을 깔끔하게 유지하는 편이 낫습니다.
끌어오기 요청을 생성하기 전에 git fetch upstream 및 git rebase upstream/master 명령어를 실행하십시오. (upstream 이 QGIS 사용자 용 원격 분기이고 여러분 자신의 원격 분기가 아니라면, 여러분의 .git/config 을 확인하거나 git remote -v | grep github.com/qgis 명령어를 실행하십시오.)
(여러분의 분기의 목적이 마스터로 병합되는 것일 뿐인 한) 아무런 손상 없이 마지막 줄에서처럼 깃 리베이스(git rebase)를 반복할 수도 있습니다.
주의: 리베이스 이후 여러분의 저장소 포크에 git push -f 명령어를 실행해야 합니다. 핵심 개발자 여러분: QGIS 공개 저장소에 이 명령어를 실행하지 마십시오!

3.3.2. 문서 작성자에게 알리기 위한 특수 라벨 

검토자가 여러분의 끌어오기 요청에 특수 라벨(Needs Documentation)을 지정하면 끌어오기 요청이 병합되자마자 QGIS 문서 저장소에 문제점 보고서(issue report)를 자동으로 생성시킬 수 있습니다. 여러분의 기능이 이런 라벨을 가질 자격이 되는지 언급하는 것을 잊지 마십시오.

더불어, 문서 작성자에게 좀 더 많은 정보를 제공하기 위해 커밋 메시지에 특수 태그를 추가할 수 있습니다. 그러면 생성된 문제점 보고서에 커밋 메시지가 추가됩니다:

[needs-docs]: 기존 기능에 수정 사항 또는 추가 사항이 생긴 후 문서 작성자들에게 추가 문서를 작성할 것을 요청하는 태그입니다.
[feature]: 새 기능인 경우 사용하는 태그입니다. 여러분의 끌어오기 요청에 훌륭한 설명을 작성하는 것도 좋은 시작일 것입니다.

개발자 여러분은 (대소문자를 구분하지 않는) 이런 라벨들을 사용해서 문서 작성자들이 작업해야 할 문제점 및 해야 할 일에 대한 개요를 파악할 수 있도록 해주십시오. 그러나 커밋 또는 문서 자체 가운데 하나에 텍스트를 추가하는 데에도 시간을 내주십시오.

3.3.3. 주의 의무 

QGIS는 GPL에 따라 사용 허가가 부여됩니다. 충돌하는 지적 재산권으로 인해 방해받지 않는 패치만 제출하도록 모든 노력을 기울여야 합니다. 또한 GPL에 따라 제공해도 괜찮다고 생각하지 않는 코드는 제출하지 마십시오.

3.4. 깃 작성 접근 권한 얻기 

QGIS 소스 트리에 대한 쓰기 접근 권한은 초대를 통해 이루어집니다. 일반적으로 한 사람이 자신의 기본 역량과 C++ 및 QGIS 코딩 규칙에 대한 이해를 보여주는 실질적인 패치를 여러 개 (여기에는 정해진 숫자가 없습니다) 제출했을 때 프로젝트 운영 위원회(Project Steering Committee) 구성원 중 한 명이나 다른 기존 개발자가 그 사람을 PSC에 지명해서 쓰기 접근 권한을 부여할 수 있습니다. 지명자는 그 사람이 쓰기 권한을 얻어야 한다고 생각하는 이유에 대한 기본적인 홍보 문단을 제공해야 합니다. 비 C++ 개발자에게, 예를 들어 번역가나 문서 작성자에게 쓰기 권한을 부여할 때도 있습니다. 이런 경우, 그 사람도 여전히 패치를 제출할 능력이 있다는 것을 보여야 하고 이상적으로는 손상 없이 코드 베이스를 수정하는 것에 대한 이해를 보여주는 몇 가지 실질적인 패치를 제출해야 합니다.

참고

깃으로 옮긴 이후, QGIS의 포크를 생성한 다음 끌어오기 요청을 발행해서 깃허브 안에서 코드를 공유하는 것이 평범한 일이 되었기 때문에 우리가 새로운 개발자에게 쓰기 접근 권한을 부여할 가능성은 많지 않습니다.

커밋/끌어오기 요청을 하기 전에 모든 것이 컴파일되는지 항상 확인하십시오. 커밋으로 인해 다른 플랫폼과 이전/최신 버전의 라이브러리를 사용해서 빌드하는 사람들에게 발생할 수 있는 손상에 유의하도록 하십시오.