키스킷에 기여하기

키스킷은 다양한 배경지식을 가진 사람들이 양자 컴퓨팅을 사용할 수 있게 하는 오픈소스 프로젝트다. 이 페이지는 당신이 키스킷 커뮤니티에 참여할 수 있는 방법을 설명한다.

코드 저장소 목록

키스킷의 코드는 키스킷 깃허브 조직 내에 있고, 키스킷을 구성하는 개별적인 프로젝트는 다음과 같다.

• 키스킷 테라

• 키스킷 에어

• 키스킷 이그니스

• 키스킷 아쿠아

• 키스킷 IBMQ 공급자

• 키스킷 사용 지침서

• 키스킷 API 문서

시작하기

키스킷 커뮤니티 멤버들의 활동에 도움이 되는 자료는 다음과 같다

• 행동 규칙

• 아이디어 논의

• 어려운 문제에 직면했을 때 도움 받기

• 커뮤니티 관련 뉴스 보기

• 프로그래밍 스타일 일치시키기

• 소스코드에서 키스킷 패키지 빌드하기

버그 보고와 기능 개선 요청하기

문제를 발견하면 해당되는 코드 저장소의 이슈 트래커에 이슈를 만든다.

구성요소	이슈 트래커
키스킷-테라	https://github.com/Qiskit/qiskit-terra/issues
키스킷-에어	https://github.com/Qiskit/qiskit-aer/issues
키스킷-이그니스	https://github.com/Qiskit/qiskit-ignis/issues
키스킷-아쿠아	https://github.com/Qiskit/qiskit-aqua/issues
문서나 키스킷 메타-패키지	https://github.com/Qiskit/qiskit/issues

새로운 기능에 대한 아이디어가 있다면, 해당되는 코드 저장소의 이슈 트래커에 개선(Enhancement) 이슈를 등록한다. 이슈를 등록하는 것은 아이디어가 어떻게 프로젝트에 적합하고, 그것이 어떻게 구현될 수 있는지에 대해서 대해 팀과 논의를 시작한다.

코드에 기여하기

스타일 가이드

프로젝트에서 일관된 코드 스타일을 유지하기 위해서 Pylint 와 pycodesytle 를 사용하여 기여된 코드가 프로젝트의 코드 스타일 가이드에 일치하는지 확인한다. 변경한 코드가 스타일 가이드와 부합하는지 확인하기 위하여 tox -elint 를 실행한다.

기여자 라이센스 계약서

코드를 제출할 수 있기 전에 모든 코드 기여자는 기여자 라이센스 계약서(CLA)에 서명해야만 한다. 기여자 라이센스 계약서에 서명함으로써 본인이 기여 코드의 작성자이며, 아파치-2.0 라이센스의 조건 하에서 자유롭게 기여를 함을 인증한다.

키스킷 프로젝트에 새로운 풀 리퀘스트를 기여할 때, 로봇이 기여자 사용 계약서에 서명을 했는지 자동으로 확인한다. 서명이 필요한 경우, 로봇은 풀 리퀘스트에 계약서를 수용하는 링크를 포함한 주석을 자동으로 생성한다. 개인 기여자 사용 계약서 문서는 PDF로 확인할 수 있다.

참고

당신의 기여가 고용된 작업의 일부이거나, 고용자의 자산이라면, 기업 기여자 사용 계약서 에도 서명하고, <qiskit@us.ibm.com>에 이메일로 송부 할 필요가 있을 것이다.

풀 리퀘스트

깃허브 풀 리퀘스트 를 사용하여 당신의 기여를 수락할 수 있다.

꼭 필요한 사항은 아니지만 풀 리퀘스트를 제출하기 전에 본인이 수정 중인 버그나 개발 중인 기능에 대한 새로운 이슈를 만드는 것은 커뮤니티에서 논의를 시작하는 중요한 과정이다. 이슈는 아이디어와 어떻게 코드에서 함께 구현을 할 수 있을지에 대해 논의하는 공간을 제공한다. 더불어 본인이 하는 일을 커뮤니티가 알 수 있게 하고, 도움이 필요한 경우에 다른 커뮤니티와 팀 멤버들이 이슈를 참고 할 수 있다.

코드를 작성했지만, 마무리하는데 도움이 필요하거나, 마무리 하기 전에 초기 피드백을 받길 원하거나, 구현을 마치기 전에 공유하고, 논의하기 원하는 경우에 진행 중(Work in Progress) 풀 리퀘스트를 제출할 수 있다. 풀 리퀘스트를 제출할 때, 제목 앞에 [WIP] (진행중을 의미) 태그를 추가한다. 이는 검토자에게 풀 리퀘스트에 포함된 코드는 최종 상태가 아니며, 변경될 것임을 알려준다. 또한 최종 마무리 전에는 커미트(commit) 를 병합하지 않을 것임을 의미한다. 본인 혹은 검토자는 병합을 위해서 완전히 검토될 준비가 된 경우에는 [WIP] 태그를 제거할 수 있다.

코드 검토

코드 검토는 공개적으로 이루어지고, 누구나 확인 가능하다. 오직 관리자들만 커미트를 병합할 수 있는 권한이 있지만, 풀 리퀘스트에 대한 커뮤니티 피드백은 극히 중요하다. 이는 전체 코드에 대해 배우는 좋은 방법이기도 하다. 현재 진행 중인 모든 풀 리퀘스트는 다음에서 확인할 수 있다.

구성요소	풀 리퀘스트
키스킷-테라	https://github.com/Qiskit/qiskit-terra/pulls
키스킷-에어	https://github.com/Qiskit/qiskit-aer/pulls
키스킷-이그니스	https://github.com/Qiskit/qiskit-ignis/pulls
키스킷-아쿠아	https://github.com/Qiskit/qiskit-aqua/pulls
문서나 키스킷 메타-패키지	https://github.com/Qiskit/qiskit/pulls

커미트 메시지

변경 사항을 설명하는 커미트 메시지의 내용은 변경 자체 만큼이나 중요하다. 커미트 메시지는 코드 검토 뿐만 아니라 깃 로그의 변경 기록에 대한 맥락을 제공한다. 자세한 커미트 메시지는 코드 검토를 쉽게 하고, 향후에 누군가가 변경된 코드를 확인하는 경우에 맥락을 제공하는 역할도 한다. 커미트 메시지를 작성할 때, 다음 중요한 사항을 기억하면 도움이 될 것이다.

검토자가 원래 문제가 무엇인지 이해할 것이라고 가정하지 않는다.

이슈와 그에 해당하는 몇 개의 코멘트를 읽어 본 후에는 대체로 근본적인 문제가 무엇인지 알게된다. 커미트 메시지는 원래 문제가 무엇인지 정확히 서술해야 한다. 버그는 단지 어떻게 문제가 인식이 되었는지에 대한 흥미로운 배경 설명에 불과하다. 버그 티켓을 읽을 필요 없이 커미트 메시지를 통해서 제안된 패치의 정확성 여부를 검토할 수 있어야 한다.

코드 자체가 자명하거나 자체로 문서화되었다고 가정하지 않는다.

누군가에게 자명한 것이 다른 이에게는 그렇지 않을 수 있다. 너무 뻔한 오자 정정이나 공백만을 포함하는 커미트를 제외하고는 항상 원래 문제가 무엇이었고, 어떻게 수정되었는지 문서화 한다.

변경한 이유를 명확히 서술한다.

일반적인 실수는 개발자가 왜 그런식으로 변경했는지에 대한 설명 없이 코드가 작성된 방법만을 서술하는 것이다. 물론, 특히 큰 변화에 대해서는 전체적인 코드의 구조를 설명해야 하지만, 더욱 중요한 것은 변경을 한 의도와 동기를 설명하는 것이다.

코드를 개선할 수 있는 여지가 있는지 알아보기 위해 커미트 메시지를 읽어본다.

종종 큰 커미트 메시지를 설명할 때면 커미트가 두 개 이상으로 쪼개져야 했다는 것이 명확해진다. 이 경우 변경된 것을 원점에서 다시 여러 개의 풀 리퀘스트로 나누어 제출해도 된다.

검토를 진행할지 여부를 결정하기 위해 충분한 정보를 확보한다.

깃허브가 새로운 풀 리퀘스트 제출에 대한 이메일 경고를 보낼 때, 커미트 메시지와 파일 변경 목록만 포함된 최소한의 정보만 포함된다. 많은 양의 패치로 인해 커미트 메시지에는 잠재적인 검토자가 검토해야하는 패치를 찾기에 충분한 정보가 포함되어 있어야 한다.

커미트의 첫 번째 문장이 가장 중요하다.

깃 커미트에서 커미트 메시지의 첫 번째 줄은 특별한 중요성을 가진다. 즉, 풀 리퀘스트의 기본 제목, 이메일 알림 제목, 깃 주석 메시지, gitk 보기 주석, 병합(merge) 커미트 메시지 등 공간이 제한된 많은 곳에 사용된다. 코드 변경 자체만를 요약하는 것에 더하여 코드의 어떤 부분이 영향을 받는지 상세히 기술할 필요가 있다.

게다가 커미트 메시지의 첫 번째 줄은 해당 풀 리퀘스트가 주요 코드에 포함되는 경우 변경로그(changelog)의 입력으로 사용된다. 따라서 명확하고, 간결한 요약을 작성하는 것은 매우 중요하다.

현재 코드의 모든 한계를 기술한다.

변경되는 코드가 여전히 향후에 개선될 여지가 있거나 어떤 한계가 있는 경우 커미트 메시지에 기술한다. 이런 내용은 검토자에게 넓은 관점에서 고려했다는 것과 장기적인 관점 대비 단기적인 목표의 관점에서 어떤 절충을 했는지 설명한다.

이슈에 참조를 포함한다.

커미트 수정이 이슈와 관련이 있다면 커미트 메시지에 해당 이슈의 주석을 단다. 다음 문법을 사용한다:

Fixes #1234

해당 커미트가 이슈를 해결하는 경우에 해당한다 (깃허브는 풀 리퀘스트가 병합될 때 이슈를 닫는다).

여기서 주요 규칙은 다음과 같다.

커미트 메시지는 패치를 완전히 이해하고, 검토하는데 필요한 모든 정보를 정확하게 포함해야만 한다. 내용이 간략하다고 좋은 것만은 아니다.

코드에 주석 달기

코드의 어느 부분을 변경한다면, 해당 코드 저장소의 docs/apidocs 아래 있는 문서 부분의 관련된 docstrings 를 업데이트 한다. 문서와 관련된 부분을 본인의 컴퓨터에서 컴파일과 빌드하기 위해서는 tox -edocs 를 실행하면 결과는 docs/_build/html 로 저장된다. 추가적으로 애저(Azure) 파이프라인의 Docs CI 작업은 이 과정을 자동으로 실행하고, 결과를 사용자가 다운로드 하고, 자신의 컴퓨터에서 확인할 수 있도록 압축 파일로 호스팅한다.

Qiskit/qiskit repo 에서 관리되는 합쳐진 문서 와 관련한 이슈가 있거나, 문서 관련 버그를 발견하거나, 문서 작업이 필요한 새로운 기능이 있거나, 현재 문서에 내용이 추가되어야 한다고 생각하는 경우에는 문서 이슈 를 만들 수 있다.

처음으로 키스킷에 기여하기

키스킷에 기여하길 원하지만, 어디서 시작해야 할지 모른다면, 프로젝트의 이슈에 좋은 첫번째 이슈(good first issue) 레이블이 프로젝트에 새로 참여한 사람들에게 적절한 아이템임을 표시하는 역할을 한다. 좋은 첫번째 이슈들은 기여자들이 이미 검토를 하고, 레이블을 단 것이기 때문에 새로운 기여자가 다룰 수 있다. 다시 말해서 키스킷에 대한 깊은 이해가 이슈를 수정하는데 필수요소는 아니다.

지원 중단 정책

키스킷 사용자들은 기능이나 API가 향후에도 계속해서 지원이 될 것인지 인지할 필요가 있다. 프로젝트가 어떤 조건 하에서 기능이나 API를 제거할 수 있는지 이해하는 것은 사용자에게 중요하다. 기대치를 맞추기 위해서 다음 정책은 키스킷에서 API와 기능 지원 중단/제거가 관리되는 방법을 정의한다.

1. Features, APIs, or configuration options are marked deprecated in the code. Appropriate DeprecationWarning class warnings will be sent to the user. The deprecated code will be frozen and receive only minimal maintenance (just so that it continues to work as-is).

2. A migration path will be documented for current users of the feature. This will be outlined in the both the release notes adding the deprecation, and the release notes removing the feature at the completion of the deprecation cycle. If feasible, the warning message will also include the migration path. A migration path might be 《stop using that feature》, but in such cases it is necessary to first judge how widely used and/or important the feature is to users, in order to determine a reasonable obsolescence date.

3. An obsolescence date for the feature will be set. The feature must remain intact and working (although with the proper warning being emitted) in all releases pushed until after that obsolescence date. At the very minimum, the feature (or API, or configuration option) should be marked as deprecated (and continue to be supported) for at least three months of linear time from the release date of the first release to include the deprecation warning. For example, if a feature were deprecated in the 0.9.0 release of Terra, which was released on August 22, 2019, then that feature should still appear in all releases until at least November 22, 2019. Since releases do not occur at fixed time intervals, a deprecation warning may only occur in one release prior to removal.

이정도의 지연은 최소시간임을 알기 바란다. 중요한 기능에 대해서는 지원 중단 기능을 적어도 최소시간의 2배의 시간만큼 표시되는것 것을 권고한다. 또한 안정된 브랜치 정책에 따르면 기능 중단에 의한 제거는 부 버전(minor version) 릴리즈에서만 반영할 수 있다. 지원 중단 제거는 이전 버전을 수정하는 백포트(backport)를 지원하지 않는다.

지원 중단 경고

지원 중단 경고를 보여주는 적절한 방법은 파이썬 표준 라이브라리의 경고 모듈 에서 warn 함수를 사용하는 것이다. 경고 범주 클래스는 DeprecationWarning 이어야 한다. 예제는 다음과 같다:

import warnings

def foo(input):
    warnings.warn('The qiskit.foo() function is deprecated as of 0.9.0, and '
                  'will be removed no earlier than 3 months after that '
                  'release date. You should use the qiskit.bar() function '
                  'instead.', DeprecationWarning, stacklevel=2)

여기서 한 가지 주의할 사항은 warn() 호출에서 stack_level kwarg이다. 이 전달 인자는 콜 스택의 어떤 수준에서 경고를 시작하는 줄로 사용될 것인지를 명시하는데 활용된다. 일반적으로 경고가 발생되는 컨텍스트를 호출하는 줄을 보여줄 것이기 때문에 stack_level 은 2로 설정되어야 한다. 앞의 예제에서 foo() 의 호출자가 될 것이다. 이를 설정하지 않았다면, 경고는 foo() 함수의 줄에서 발생되었다고 보여줄 것이고, 이는 지원 중단 호출의 근원 코드를 알아 내는데 도움이 되지 않는다. 하지만 이 값은 warn() 이 호출되는 장소와 콜 스택에 따라서 조정될 것이다. 예를 들어, 경고가 오직 하나의 호출자만 가지는 비공개 메소드에 의해서 발생하는 경우에는 stack_level=3 이 적절한 값이다.

안정된 브랜치 정책

안정된 브랜치는 이전 릴리즈 이후에 마스터 브랜치에 수정된 높은 영향의 버그나 보안 관련 이슈의 수정이 적용된 안전한 소스 코드를 유지하는 것을 목표로 한다. 안정된 브랜치의 풀 리퀘스트를 검토 할 때는 안정된 브랜치의 사용자에게 제공하는 가치와 제공된 패치의 위험성 사이에 균형을 유지해야 한다. 오직 제한된 종류의 변경 사항만 안정된 브랜치에 포함하는 것이 적절할 것이다. 주요한 이슈에 대한 크고 위험한 패치가 타당할 수 있고, 마찬가지로 상당히 이해하기 힘든 오류 처리에 대한 사소한 수정이 경우에 따라서 안정된 브랜치에 포함될 수 있다. 안정된 브랜치의 변경을 고려할 때는 다음과 같은 요소들을 고려해야만 한다.

• 퇴행의 위험: 정말 작은 변경도 프로그램의 동작을 망칠 수 있는 위험이 있고, 안정된 브랜치의 퇴행을 피하기를 원한다.

• 사용자에 보이는 이득: 사용자가 실제로 알아차릴 만한 것들을 수정하고 있는가? 그렇다면 그 변경은 얼마나 중요한 것인가?

• 수정이 얼마나 자립적인가: 중요한 이슈를 수정하지만 동시에 많은 코드를 변경하는 경우에는 다소 덜 위험한 수정으로 변경할 수 없는지 생각해볼 가치가 있을 것이다.

• 수정이 이미 마스터 브랜치에 있는지 여부: 변경 사항이 단순히 마스터 브랜치에서 타당하지 않은 경우가 아니라면, 수정 사항은 마스터 브랜치에 이미 병합된 이전 버전을 수정하는 백포트(backport)여야만 한다.

이전 버전을 수정하는 백포트 과정:

마스터 브랜치에서 안정된 브랜치로 패치하는 백포트를 할 때, 마스터 브랜치에 변경에 대한 참조를 유지하길 원한다. 안정된 브랜치에 풀 리퀘스트를 만드는 경우 다음 명령어를 사용하기 바란다.

$ git cherry-pick -x $master_commit_id

하지만 이것은 마스터 브랜치의 작은 자립적인 패치에만 적용된다. 마스터 브랜치에서 더 큰 커미트의 하위 집합 (예: 함축된 풀 리퀘스트)에 대해 이전 버전을 수정하는 백포트(backport) 해야하는 경우에는 수동으로 백포트를 해야 한다. 이 경우 다음을 추가한다.

Backported from: #master pr number

특별히 선별된 내용이 의미가 통하지 않더라도 변경된 부분의 원래 소스 코드를 추적할 수 있다.

새롭게 제안하는 패치가 정확히 선별하지 않더라도 스스로 상충되는 부분을 해결하고, 결과로 초래된 패치를 제안함으로써 도움을 줄 수 있다. 안정된 패치의 검토를 돕기 위해서 커미트 메시지에 상충됨(Conflicts)을 표시하기 바란다.

이전 버전을 수정하는 백포트(backport) 레이블

``잠재적인 안정된 백포트(stable backport potential)``로 태그된 버그나 풀 리퀘스트는 안정된 릴리즈에 적용되는 버그이며, 마스터 브랜치에 머지되는 순간 이전 버전을 수정하는 백포트(backport) 로써 적합할 수 있다. 백포트가 제안되면, 해당 태그는 제거되어야 한다.

대상 브랜치를 안정되었다고 설정하는 표시는 실수가 아니기 때문에 안정된 브랜치에 대한 풀 리퀘스트의 제목에는 [Stable] 을 포함시킨다. 또한, 마스터 브랜치에 머지된 풀 리퀘스트 참조번호를 추가한다.

문서에 기여하기

키스킷 문서는 코드로써의 문서 규칙을 따르며, 이는 주로 키스킷 코드 커멘트인 API 문서의 스타일 에서 가져온 것이다.

문서는 Sphinx 를 사용하여 Qiskit/qiskit/docs 의 마스터 브랜치에서 만들어진다. API Reference 에 있는 대부분의 문서는 코드 저장소 목록 에 나열된 코드 저장소의 코드 코멘트에서 가져온 것이다.

문서 구조

키스킷에서 문서가 조직된 방식은 가능한 많은 문서를 docstring으로 입력하는 것이다. 이 방식은 문서 자체가 코드와 함께 존재하기 때문에 개발 과정에서 문서를 추가하거나, 수정하는 것을 쉽게 만든다. 테라의 일반적인 문서 구조에는 세 개의 레벨이 있다:

docs/apidocs 에 위치한 .rst 파일들

이 파일들은 Sphinx에게 어떤 모듈이 제공되는 문서에 포함되는지 알려주는데 사용된다. 이 파일 형식은 두 가지 정보를 가진다: 문서 내에서 내부 링크에 사용될 수 있는 모듈의 내부 참고 나 외부 참고 와 주어진 임포트 파일에서 모듈 docstring을 분석하는데 사용되는 automodule directive 이 해당된다. 예를 들어, dagcircuit.rst 파일은 다음을 포함한다:

.. _qiskit-dagcircuit:


.. automodule:: qiskit.dagcircuit
   :no-members:
   :no-inherited-members:
   :no-special-members:

이런 형식과 다른 유일한 .rst 파일은 목차를 포함하는 qiskit.rst 이다. 새로운 모듈의 문서에 대한 .rst 파일을 추가한다면, 해당 파일에 toctree 을 추가해야 한다.

모듈-레벨 docstring

이 docstring은 rst 파일의 automodule 지시자에 명시된 모듈에 대한 모듈 레벨에 있다. 명시된 모듈이 디렉토리/명칭 공간라면, docstring은 그 디렉토리의 __init__.py 에 명시되어야 한다. 이 모듈-레벨의 docstring은 문서화된 모듈에 대한 더 많은 세부정보를 포함한다. 이 docstring의 일반적인 구조는 모듈에 포함된 공개 API의 모든 클래스와 함수를 나열하는 것이다. 이는 일반적으로 autosummary 지시자 에 의해서 실행된다(또는 qiskit.execute 의 경우와 같이 모듈이 간단한 경우에는 autodoc 지시자들 로 직접 실행). autosummary 지시자는 다른 파이썬 요소들(클래스, 함수 등)을 각각의 autodoc 지시자를 호출할 필요 없이 직접 이런 요소들의 autodoc을 실행하는데 사용된다. 모듈-레벨 docstring은 모듈이 제공하는 기능에 대한 높은 수준의 개요를 제공한다. 이는 주로 공개 API의 다른 컴포넌트를 여러 세부항목으로 묶음으로서 이루어진다.

예를 들어, 이전에 제시된 dagcircuit 모듈 예제에서 qiskit/dagcircuit/__init__.py 에 대한 모듈 docstring의 내용은 다음과 같을 것이다:

"""
=======================================
DAG Circuits (:mod:`qiskit.dagcircuit`)
=======================================
.. currentmodule:: qiskit.dagcircuit
DAG Circuits
============
.. autosummary::
   :toctree: ../stubs/
   DAGCircuit
   DAGNode
Exceptions
==========
.. autosummary::
   :toctree: ../stubs/
   DAGCircuitError
"""

참고

이는 예제에 해당하고, 방향성 비사이클 그래프 회로 모듈에 대해서 실제 모듈 docstring이 이것에서 분기될 수 있다.

모듈 docstring에 나열된 요소들에 대한 실제 docstring

개발자들은 필요한 경우에 예제를 사용하여 노출된 모든 공개 인터페이스를 철저하게 문서화하기위해 노력해야 한다. docstring은 구글 파이썬 스타일 Docstring 이 사용된다. 이후 문서는 나폴레옹 스핑크스 확장판 을 사용하여 분석된다. 나폴레옹 문서 는 docstring이 어떻게 형식화되어야 하는지에 대한 좋은 예제를 포함한다.

참고

필요한 곳에 스핑크스나 rst 포맷형식을 사용할 수 있다. 예를 들어, 한 가지 공통적으로 사용되는 확장은 jupyter-execute 지시자이며, 이는 주피터(Jupyter) 에서 코드 블록을 실행하고, 코드와 결과를 보여주는데 사용된다. 이는 시각화에 특히 매우 유용하다.

문서 통합

https://qiskit.org/documentation/에 제공되는 문서는 전체 키스킷 프로젝트를 다룬다. 테라는 그 중 단지 하나의 컴포넌트에 해당한다. 엄밀한 의미로 호스트되는 버전에 대한 문서 빌드는 키스킷 메타-패키지 저장소 https://github.com/Qiskit/qiskit에 의해서 만들어진다. 커미트가 해당 저장소로 머지될 때, 스핑크스 빌드의 결과는 qiskit.org 웹사이트로 전송된다. 이런 스핑크스 빌드는 해당 시점에 메타-패키지에 의해 설치된 키스킷 요소의 버전에서 문서로 불러오도록 설정되어 있다. 예를 들어, 메타-패키지 버전이 현재 0.13.0인 경우, 테라의 0.10.0 릴리즈에서 문서를 복사할 것이다. 메타-패키지의 요구사항이 서로 충돌하는 경우, 새로운 버전에서 문서를 가지고 오기 시작할 것이다. 이는 잘못된 API 문서에 대한 수정은 새로운 릴리즈에 포함될 필요가 있음을 의미한다. 문서 수정은 안정된 브랜치 정책(다음 절을 참고)에 의해서 안정된 패치 릴리즈에 대해서 유효한 이전 버전을 수정하는 백포트(backport)에 해당한다.

빌드 과정에서 각 요소의 docs/apidocs/ 내용은 모든 다른 요소와 함께 메타-패키지 저장소에 있는 doc/apidocs/ 의 공유된 복사본에 재귀적으로 복사된다. 이렇게 함으로써, 릴리즈의 각 요소에서 docs/apidocs의 최상위에 있는 것은 https://qiskit.org/documentation/apidoc/의 최상위에 있게 된다.

문서 번역

키스킷 문서는 조직적으로 번역 프로젝트를 관리하고, 자료를 번역하기 위해 커뮤니티와 협력하기 위한 소프트웨어와 웹 지역화 플랫폼인 크라우인을 사용하여 번역(지역화)된다. 크라우드인 번역자 커뮤니티가 하나의 문장을 다른 문장으로 해석하고, 비슷한 문장을 번역하는 과정에서 축적되는 경험을 자동적으로 재사용함으로써 효율을 극대화하게 한다. 크라우드인은 문장의 위치를 옮기거나, 아예 다른 파일로 옮기는 것과 같은 다양한 변화에 대해서 자동 해석처리 된다.

키스킷 지역화 요청은 Qiskit Translations 코드 저장소에서 처리된다. 키스킷 지역화에 기여하려면 다음 단계를 따른다.

1. LOCALIZATION_CONTRIBUTORS 파일에 이름 (또는 ID)을 추가한다.

2. 풀 리퀘스트 (PR) 을 작성하여 변경 사항을 병합한다. 풀 리퀘스트을 열기 위해서는 템플릿을 따라야한다.

   참고

   • 각 기여자는 자신의 풀 리퀘스트를 만들고, 기여자 사용 계약서(CLA)에 사인해야 한다.

   • 풀 리퀘스트 요약에 원하는 언어를 언급하기 바란다.

   • 새로운 언어 요청에 대한 오픈 이슈가 있다면, 풀 리퀘스트에 이슈 링크를 추가하기 바란다.

3. 키스킷 기여자 사용 계약서(CLA)에 서명 요청이 있을 것이다. 사인하기 바란다.

4. 지역화 프로젝트에 새로운 언어를 추가하기 위해 관리자로부터 공식 지원을 받으려면 언어 당 최소 3 명의 기야자가 필요하다.

5. 지역화 프로젝트 기여자 그룹 중 관리자와의 연락을 담당하는 번역 리드를 식별해야 한다. 그리고 번역 리드는 Yuri Kobayashi (yurik@jp.ibm.com)에게 이메일로 문의해야 한다.

6. 키스킷-문서 크라우드인 프로젝트에서 기여를 원하는 언어를 선택한다.

   참고

   Qiskit in my language is Qiskit 블로그 포스트에서 언급했듯이, 우리는 번역된 언어가 번역가, 교정자, 번역 책임자로 번역팀을 구성할 수 있는 충분한 커뮤니티 지원을 받고 있는지 확인하고 싶다. 만약 번역 책임자가 되기를 희망하거나 새로운 번역 프로젝트 팀에 참여하고 싶다면, 키스킷 팀과의 논의를 시작하고, 프로젝트 멤버들을 모집을 위하여 깃허브 이슈 를 생성하면 된다.

7. 가입 버튼을 클릭하고, 왜 크라우드인(Crowdin) 프로젝트에 참여하기를 원하는지 이유를 묻는 대화 상자에 자신의 풀 리퀘스트의 URL을 복사하여 붙여넣기한다.

크라우드인 프로젝트의 관리자들은 요청을 검토하고 가능한 한 빨리 접근 권한을 제공할 것이다.

소스 코드로부터 빌드하기

Qiskit/qiskit 코드 저장소의 지역 복제로부터 문서들의 복사본을 빌드하기 위해서는 다음 명령어를 이용한다.

1. 키스킷 코드 저장소 복제.

   git clone https://github.com/Qiskit/qiskit.git
   

2. 저장소 복제는 qiskit 라는 이름의 지역 디렉토리를 생성한다.

   cd qiskit
   

3. Qiskit/qiskit 지역 복제본으로 이동하여 터미널 창에서 다음 명령을 실행하여 문서를 빌드한다.

   tox -edocs
   

   tox 명령이 설치되어 있지 않은 경우 다음을 실행하여 설치한다.

   pip install tox
   

지역 RST 파일을 변경하면 /doc/ 로 이동하여 터미널 창에서 다음을 실행하여 HTML 파일을 업데이트 할 수 있다.

tox -edocs

이 명령어는 /docs/_build/html/ 의 하위 디렉토리 안에 지역 문서의 코드 저장소를 스타일에 맞춘 HTML 버전으로 빌드 한다.

소스로부터 설치하기

소스 코드로부터 구성 요소들을 설치하는 것은 파이썬 패키지 색인 (PyPI) 코드 저장소로부터 설치하는 것 대신에 가장 최근에 업데이트된 키스킷 버전을 사용하도록 한다. 이를 통해 손쉽게 키스킷의 최신 코드로 확장하고 검사해 볼 수 있다.

소스 코드로 부터 구성 요소나 성분을 설치할 때는 기본 설정으로 개발 버전 (이것은 깃 브랜치의 마스터 에 해당한다) 이 사용되고 안정 버전 ( pip 패키지로 설치되는 같은 코드를 기반으로 하는) 과 대응을 이룬다. 개발 버전의 구성요소나 성분들은 보통 새로운 기능과 변화를 가지고 있기 때문에, 나머지 아이템들도 개발 버전으로 설치하는 것을 권장한다.

참고

테라와 에어 패키지 모두 설치하기 전에 소스 코드로 부터 빌드하기 위해 컴파일러가 필요하다. 이그니스, 아쿠아 그리고 IBMQ 공급자의 백엔드(backend) 는 컴파일러를 필요로 하지 않는다.

소스 코드로 부터 구성 요소들을 설치하기 위해서는, pip 버전이 소스 코드 버전보다 오래된 것일 경우 필요로 하는 구성 요소의 버전도 낮을 수 있기 때문에 설치 시에 바른 순서를 따르는 것이 필요하다.

1. 키스킷-테라

2. 키스킷-에어

3. 키스킷-이그니스

4. 키스킷-아쿠아

5. 키스킷-IBMQ 공급자 (만약 IBM 양자 디바이스 혹은 온라인 시뮬레이터 장치에 접속하길 원하는 경우)

몇몇 개의 구성 요소나 요소를 동시에 사용하고자 한다면 각각의 요소에 대해 다음 단계를 거치도록 하라.

참고

파이썬에서 명칭 공간의 패키지 사용법 때문에 패키지를 설치할 때 주의를 기울여야 한다. 만약 소스로부터 어떤 요소를 설치하고자 할 때, 키스킷 메타-패키지를 사용하지 말라. 또한 이 가이드를 따라 개발을 위해 따로 마련한 가상 환경을 이용하라. 만약 개발을 위해 이미 존재하고 있는 설치 패키지와 섞어서 사용하기 원한다면, 함께 사용할 수 있는 설치 방법의 조합을 설명한 이 문서 (https://github.com/pypa/sample-namespace-packages/blob/master/table.md)를 참조하라.

가상화 개발 환경 설정하기

conda create -y -n QiskitDevenv python=3
conda activate QiskitDevenv

소스로부터 테라 설치하기

소스에서 설치하려면 C++11을 지원하는 시스템에서 C++ 컴파일러가 있어야 한다.

리눅스용 컴파일러

대부분의 리눅스 플랫폼에서는 필요한 GCC 컴파일러가 이미 설치되어 있다.

맥OS용 컴파일러

만약 맥오에스를 사용하고 있다면, XCode를 설치하면 Clang 컴파일러를 설치할 수 있다. XCode와 Clang이 설치되어 있는지 확인하기 위해서는 터미널을 열고 다음 명령어를 입력한다.

clang --version

다음 명령어를 사용하여 XCode와 Clang을 설치한다.

xcode-select --install

윈도우용 컴파일러

윈도우에서는 비주얼 스튜디오 2017를 위한 개발툴 <https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2017> 에서 비주얼 C++ 컴파일러를 설치하는 것이 가장 쉬운 방법이다. 비주얼 스튜디오 2015 나 2017 버전을 설치할 수 있고 C++ 컴파일러를 설치하는 옵션을 꼭 선택해 주어야 한다.

컴파일러가 설치되고 나면 키스킷 테라를 설치할 준비가 된 것이다.

1. 테라 코드 저장소를 복제.

   git clone https://github.com/Qiskit/qiskit-terra.git
   

2. 저장소를 복제하면 qiskit-terra 라는 이름의 지역 디렉토리가 생성된다.

   cd qiskit-terra
   

3. qiskit-terra 디렉토리에 필요한 파이썬 라이브러리를 설치한다.

   pip install cython
   

4. 만약 테스트 코드를 실행하거나 스타일 검사를 하고자 한다면, 개발자 요구사항 라이브러리를 설치한다.

   pip install -r requirements-dev.txt
   

5. qiskit-terra 를 설치.

   pip install .
   

수정 가능한 모드로 설치, 즉 프로젝트에 코드가 변화하였을 때 재설치가 필요하지 않는 경우 다음의 명령어를 사용한다.

pip install -e .

테라를 설치한 이후에 예제 코드들을 실행해 볼 수 있다. 이를 위해서는 다음 명령어를 실행한다.

python examples/python/using_qiskit_terra_level_0.py

참고

만약 다른 구성 요소들을 설치하려 하지 않는다면, 키스킷-테라는 키스킷-에어와 키스킷-IBMQ 공급자가 설치되지 않았다는 RuntimeWarning 경고를 할 것이다. 이것은 사용자들이 대부분 다른 구성요소를 사용할 의사가 있지만, 그것들을 설치하지 않았다는 것을 모르기 때문이거나 에어나 IBMQ 공급자가 어떠한 이유로 올바르게 설치되지 않았기 때문이다. 이러한 경고들을 억제하고 싶다면, 다음의 명령어를 추가하라.

import warnings
warnings.filterwarnings('ignore', category=RuntimeWarning,
                        module='qiskit')

코드에 임포트 qiskit 들을 수행하기 전에 입력하라. 이것은 키스킷-에어나 키스킷-IBMQ 공급자가 설치되지 않았다는 경고를 억제할 것이다. 하지만 키스킷이나 다른 패키지의 경고들은 계속 표시될 것이다.

소스로부터 에어 설치하기

1. 에어 저장소를 복제한다.

   git clone https://github.com/Qiskit/qiskit-aer
   

2. 빌드 요구사항을 설치한다.

   pip install cmake scikit-build cython
   

이 후 에어 설치 단계는 사용중인 운영 체제에 따라 다르다. 에어는 Python 인터페이스를 가진 컴파일 된 C ++ 프로그램이므로 운영 체제에 따라 바이너리 파일을 빌드하기 위해 Python과 관련없으나 필요한 필수 종속 프로그램/라이브러리가 있다.

5. 키스킷-에어를 직접 빌드하고 설치한다.

   pip 버전 19.0.0 이하를 설치하였고, 본인의 환경이 사용자 빌드를 요구하지 않으면 다음을 실행한다:

   cd qiskit-aer
   pip install .
   

   이는 바이너리를 빌드하고 에어를 설치한다.

   그렇지 않으면 최신 pip가 설치되어 있거나, 사용자 지정 요구 사항이 있으면 파이썬 휠을 직접 빌드 할 수 있다.

   cd qiskit-aer
   python ./setup.py bdist_wheel
   

   휠 빌드 중 사용자 옵션을 선택해야 하는 경우 휠 빌드 중 사용자 정의 옵션 을 참고한다.

   파이썬 휠을 빌드 하면 에어 저장소 안의 디렉토리 dist/ 에 저장이 된다. 정확한 버전은 상황에 따라 다르며 설치 명령어는

   cd dist
   pip install qiskit_aer-*.whl
   

   출력 휠 파일의 정확한 파일 이름은 개발중인 에어의 현재 버전에 따라 다르다.

휠 빌드 중 사용자 정의 옵션

파이선 인터페이스를 이용해서 에어를 빌드할때 아르 빌드 시스템은 컴파일하기 위해 scikit-build 을 사용한다. 이것은 CMake 를 사용하는 setuptools 의 인터페이스로 작용을 하고, 로컬 시스템에 바이너리 파일을 컴파일한다.

바이너리 파일을 컴파일 하는 것은 복잡하기 때문에 빌드 과정 중의 특정 부분에 옵션을 따로 정해줘야 할 수도 있다. 변수들을 전달하는 방법은 다음과 같다.

python setup.py bdist_wheel [skbuild_opts] [-- [cmake_opts] [-- build_tool_opts]]

꺽쇠 괄호 안에 있는 요소들은 선택적인 것이고, skbuild_opts, cmake_opts, build_tool_opts 는 당신의 플래그 선택에 따라 참 혹은 거짓 값을 가질 수 있다. CMake 의 옵션 리스트는 여기서 (https://cmake.org/cmake/help/v3.6/manual/cmake.1.html#options) 찾아 볼 수 있다. 예를 들어, 다음과 같이 실행할 수 있다.

python setup.py bdist_wheel -- -- -j8

이 명령어는 기반이 되는 빌드 시스템 (이 경우 오토메이크(Automake))에 컴파일 시 8개의 프로세스를 병렬 처리로 사용하라는 -j8 이라는 플래그를 전달한다.

예를 들어, 리눅스에서 이러한 플래그들의 일반적인 활용 예시는 사용할 C++ 컴파일러의 특정 버전을 구체적으로 명시하는 것이다. (대게 기본 설정으로 쓰이는 컴파일러가 너무 오래된 것일 때 사용한다.)

python setup.py bdist_wheel -- -DCMAKE_CXX_COMPILER=g++-7

이 명령어는 씨메이크 (CMake) 에게 에어를 컴파일 할 때, 기본으로 쓰이는 g++ 컴파일러를 사용하지 말고 g++-7 컴파일러를 사용하라는 의미이다.

환경에 따라 이러한 옵션을 사용하는 또 다른 경우는 당신의 플랫폼 이름을 구체적으로 명시하고 정적 연결(static linking) 을 금지하기 위한 경우이다.

python setup.py bdist_wheel --plat-name macosx-10.9-x86_64 \
-- -DSTATIC_LINKING=False -- -j8

여기서 --plat-name 은 패키지 메타 정보에서 사용되는 플랫폼 이름을 정해주기 위해 setuptools에 보내지는 옵션이다. 그리고 -DSTATIC_LINKING 은 씨메이크(CMake) 를 사용하여 라이브러리 정적 연결을 꺼주기 위한 옵션이고, -j8 은 오토메이크(Automake) 가 컴파일 할 때 8개의 프로세서를 사용하라는 플래그이다.

플랫폼에 따라 일반적으로 사용되는 옵션의 목록은 다음과 같다:

플랫폼	도구	옵션	활용 예시
전체	오토메이크(Automake)	-j	옵션 이후에 숫자가 뒤이어 오고, 컴파일 시 사용할 프로세서의 수를 결정한다.
리눅스	씨메이크(CMake)	-DCMAKE_CXX_COMPILER	특정 C++ 컴파일러를 명시하기 위해 사용된다. 이 옵션은 보통 기본 g++ 컴파일러가 너무 오래 되었을 때 사용된다.
OSX	셋업툴(setuptools)	–plat-name	결과 파이썬 패키지에 나타나는 플랫폼 이름을 명시하기 위해 사용된다.
OSX	씨메이크(CMake)	-DSTATIC_LINKING	정적 연결(static linking)을 사용할지 안 사용할지 결정하는데 사용된다.

참고

이러한 몇몇 옵션들은 플랫폼에 좌우되지 않는다. 이러한 특정 플랫폼이 여기 나열된 이유는 보통 일반적으로 사용되는 환경이기 때문이다. 더 많은 정보를 위해서는 도구 문서를 참조한다.

소스로부터 이그니스 설치하기

1. 이그니스 코드 저장소를 복제.

   git clone https://github.com/Qiskit/qiskit-ignis.git
   

2. 저장소를 복제하면 qiskit-ignis 라는 이름의 지역 디렉토리가 생성된다.

   cd qiskit-ignis
   

3. 만약 테스트를 하거나 스타일 검사를 하려면, 개발자 필수 요소를 설치한다. 이것은 소스에서 키스킷-이그니스 패키지를 설치하거나 사용할 때는 필요하지 않다.

   pip install -r requirements-dev.txt
   

4. 이그니스 설치하기.

   pip install .
   

수정 가능한 모드로 설치, 즉 프로젝트에 코드가 변화하였을 때 재설치가 필요하지 않는 경우:

pip install -e .

소스로부터 아쿠아 설치하기

1. 아쿠아 코드 저장소를 복제.

   git clone https://github.com/Qiskit/qiskit-aqua.git
   

2. 저장소 복제는 qiskit-aqua 이라는 이름의 지역 디렉토리를 생성한다.

   cd qiskit-aqua
   

3. 만약 테스트를 하거나 스타일 검사를 하려면, 개발자 필수 요소를 설치하라. 이는 소스로부터 설치하는 경우 키스킷-아쿠아 패키지를 설치하거나 사용할 필요가 없다.

   pip install -r requirements-dev.txt
   

4. 아쿠아 설치하기.

   pip install .
   

수정 가능한 모드로 설치, 즉 프로젝트에 코드가 변화하였을 때 재설치가 필요하지 않는 경우:

pip install -e .

소스로부터 IBMQ 공급자 설치하기.

1. 키스킷-IBMQ 공급자 코드 저장소를 복제.

   git clone https://github.com/Qiskit/qiskit-ibmq-provider.git
   

2. 저장소 복제는 qiskit-ibmq-provider 이라는 이름의 지역 디렉토리를 생성한다.

   cd qiskit-ibmq-provider
   

3. 만약 테스트를 하거나 스타일(linting) 검사를 하려면, 개발자 필수 요소를 설치하라. 이때 소스로부터 설치하는 경우에는 키스킷-IBMQ 공급자 패키지를 설치하거나 사용할 필요가 없다.

   pip install -r requirements-dev.txt
   

4. 키스킷-IBMQ 공급자 설치하기.

   pip install .
   

수정 가능한 모드로 설치, 즉 프로젝트에 코드가 변화하였을 때 재설치가 필요하지 않는 경우:

pip install -e .