Qiskit 에 기여하기

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

코드 저장소 목록

Qiskit의 코드는 Qiskit GitHub organization 내에 있고, Qiskit을 구성하는 개별적인 프로젝트는 다음과 같다.

• Qiskit Terra

• Qiskit Aer

• Qiskit Ignis

• Qiskit Aqua

• Qiskit IBMQ Provider

• Qiskit 튜토리얼

• Qiskit API 문서

시작하기

Qiskit 커뮤니티 멤버들의 활동에 도움이 자료

• 행동 규칙 따르기

• 아이디어 논의 하기

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

• 커뮤니티 관련 소식 받기

• 일관된 스타일 유지

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

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

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

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

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

코드에 기여하기

스타일 가이드

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

기여자 라이센스 계약(CLA)

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

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

참고

당신의 기여가 고용을 통해 이뤄진 활동이거나, 고용자의 자산이라면, 기업 기여자 사용 계약 에 서명한 후, <qiskit@us.ibm.com>에 이메일로 발송한다.

Pull Request

커뮤니티는 Github pull request 을 통해 여러분의 기여를 받는다.

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

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

코드 검토

코드 검토는 공개적으로 이루어지고, 누구나 확인 가능하다. 병합 요청을 완결할 수 있는 권한은 관리자들만이 가지고 있지만, 그와 별도로 Pull request에 대한 커뮤니티 피드백은 매우 중요하다. 이는 코드를 기반한 커뮤니티의 원리를 배우는 좋은 방법이기도 하다. 현재 진행 중인 모든 pull request는 다음에서 확인할 수 있다.

구성요소	Pull Request
qiskit-terra	https://github.com/Qiskit/qiskit-terra/pulls
qiskit-aer	https://github.com/Qiskit/qiskit-aer/pulls
qiskit-ignis	https://github.com/Qiskit/qiskit-ignis/pulls
qiskit-aqua	https://github.com/Qiskit/qiskit-aqua/pulls
문서나 키스킷 메타-패키지	https://github.com/Qiskit/qiskit/pulls

Commit 메시지

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

검토자가 원래의 문제가 무었이었는지 알고 있다고 가정하지 않는다.

issue와 그에 해당하는 몇 개의 comment를 읽어 본다면 제기되었던 문제가 무엇인지 알게된다. commit 메시지는 원래 문제가 무엇인지 정확히 설명해야한다. bug는 단지 어떻게 문제가 인식이 되었는지에 대한 배경 설명에 불과하다. bug 티켓을 읽을 필요 없이 commit 메시지를 통해서 제안된 patch의 정확성 여부를 검토할 수 있어야 한다.

코드가 스스로 증명하거나(self-evident)/스스로 문서화가 충분하다고(self-documenting) 가정하지 않는다.

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

수정이 이루어진 이유를 명확히 기술한다.

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

Commit 메시지가 개선된 코드 구조를 보여주고 있는지 읽어본다.

종종 commit 메시지의 양이 많을 두 개 이상으로 나눠서 제출하는 것이 좋다. 이 경우 변경된 것을 원점에서 다시 여러 개의 pull request로 나누어 제출해도 된다.

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

GitHub가 새로운 pull request 제출에 대한 이메일 경고를 보낼 때, 커밋 메시지와 파일 변경 목록만 포함된 최소한의 정보만 포함된다. 많은 양의 패치로 인해 commit 메시지에는 향후 검토자가 검토해야하는 패치를 찾기에 충분한 정보가 포함되어 있어야 한다.

Commit의 첫 번째 문장이 가장 중요하다.

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

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

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

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

이슈에 참조를 포함한다.

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

Fixes #1234

해당 commit이 이슈를 해결하는 경우에 해당한다 (GitHub는 pull request가 병합될 때 이슈를 닫는다).

주요 규칙은 다음과 같다.

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

코드에 주석 달기

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

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

처음으로 Qiskit 에 기여하기

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

지원 중단 정책

Qiskit 사용자들은 기능이나 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)를 지원하지 않는다.

지원 중단 경고

지원 중단 경고를 보여주는 적절한 방법은 Python 표준 라이브라리의 경고 모듈 에서 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 이 적절한 값이다.

안정된 브랜치 정책

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

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

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

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

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

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

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

$ git cherry-pick -x $master_commit_id

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

Backported from: #master pr number

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

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

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

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

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

문서에 기여하기

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

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

문서 구조

Qiskit에서 문서가 조직된 방식은 가능한 많은 문서를 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 directive 에 의해서 실행된다(또는 qiskit.execute 의 경우와 같이 모듈이 간단한 경우에는 autodoc directives 로 직접 실행). autosummary directive는 다른 파이썬 요소들(클래스, 함수 등)을 각각의 autodoc directive를 호출할 필요 없이 직접 이런 요소들의 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
"""

참고

이것은 예일 뿐이며 dagcircuit 회로 모듈에 대한 실제 모듈 문서 문자열은 이와 다를 수 있다.

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

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

참고

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

문서 통합

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

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

문서 번역

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

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

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

2. Pull Request (PR) 를 생성하여 변경 사항을 merge한다. PR을 생성할 때는 template을 따르도록 한다.

   참고

   • 각 기여자는 자신의 PR 를 만들고, 기여자 사용 계약서 (CLA) 를 사인해야 한다.

   • PR 요약에 원하는 언어를 언급하기 바란다.

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

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

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

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

6. Qiskit-Docs Crowdin 프로젝트에서 기여를 원하는 언어를 선택한다.

   참고

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

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

Crowdin 프로젝트의 관리자가 요청을 검토하고 최대한 신속하게 액세스 권한을 부여해 줄 것이다.

소스 코드로부터 빌드하기

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

1. Qiskit 코드 저장소를 복제하라

   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 버전을 빌드한다.

소스 코드로부터 설치하기

소스 코드로부터 구성 요소들을 설치하는 것은 Python Package Index (PyPI) 코드 저장소로 부터 설치하는 것 대신에 가장 최신에 업데이트된 Qiskit 버전을 사용하도록 해준다. 이를 통해 손쉽게 Qiskit의 최신 코드를 확장하고 검사해 볼 수 있다.

소스 코드로부터 구성 요소나 성분을 설치할 때는 기본 설정으로 stable 버전 ( pip 패키지로 배포되기 때문에 같은 코드를 기반으로 함)이 아닌 development 버전 (이것은 깃 브랜치의 master 에 해당한다) 이 사용된다. development 버전의 구성요소나 성분들은 보통 새로운 기능과 변화를 가지고 있기 때문에, 나머지 항목들도 development 버전으로 설치하는 것을 권장한다.

참고

Terra와 Aer 패키지 모두 설치하기 전에 소스 코드로 부터 빌드하기 위해 컴파일러가 필요하다. Ignis, Aqua 그리고 IBM Quantum 공급자의 백엔드(backend) 는 컴파일러를 필요로 하지 않는다.

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

1. qiskit-terra

2. qiskit-aer

3. qiskit-ignis

4. qiskit-aqua

5. ref:qiskit-ibmq-provider <install-qiskit-ibmq-provider> (만약 IBM 양자 디바이스 혹은 온라인 시뮬레이터 장치에 접속하길 원하는 경우)

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

참고

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

가상화 개발 환경을 설정하기

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

소스 코드로부터 Terra 설치하기

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

Linux용 컴파일러

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

macOS용 컴파일러

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

clang --version

XCode와 Clang을 설치하기 위해서 다음 명령어를 사용하라.

xcode-select --install

윈도우용 컴파일러

Windows에서는 Build Tools for Visual Studio 2017 <https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2017> 에서 Visual C++ 컴파일러를 설치하는 것이 가장 쉬운 방법이다. Visual Studio 2015 나 2017 버전을 설치할 수 있고 C++ 컴파일러를 설치하는 옵션을 꼭 선택해 주어야 한다.

컴파일러가 설치되고 나면 Qiskit Terra를 설치할 준비가 된 것이다.

1. Terra 코드 저장소를 복제하라

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

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

   cd qiskit-terra
   

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

   pip install cython
   

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

   pip install -r requirements-dev.txt
   

5. qiskit-terra 를 설치.

   pip install .
   

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

pip install -e .

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

python examples/python/using_qiskit_terra_level_0.py

참고

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

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

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

소스 코드로부터 Aer 설치하기

1. Aer 저장소를 복제한다.

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

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

   pip install cmake scikit-build cython
   

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

Linux

3. 컴파일러 요구사항을 설치한다.

   Aer를 빌드 하려면 C++ 컴파일러와 헤더들을 필요하다.

   Fedora 혹은 이와 동등한 리눅스 배포판을 사용하는 경우에는 다음을 사용하여 설치한다:

   dnf install @development-tools
   

   Ubuntu나 Debian에서는 다음을 사용하여 설치한다:

   apt-get install build-essential
   

4. OpenBLAS 개발 헤더를 설치한다.

   Fedora 혹은 이와 동등한 리눅스 배포판을 사용하는 경우에는 다음을 사용하여 설치한다:

   dnf install openblas-devel
   

   Ubuntu나 Debian에서는 다음을 사용하여 설치한다:

   apt-get install libopenblas-dev
   

macOS

3. 종속 라이브러리 설치

   macOS에서 Clang compiler를 사용하기 위해서는 추가적으로 OpenMP 를 지원하는 library를 설치해야 한다. brew 를 사용하여 이러한 library 및 의존성 library들을 설치할 수 있다.

   brew install libomp
   

4. 다음으로 BLAS 구현을 설치한다; OpenBLAS 가 기본 선택이다.

   brew install openblas
   

   다음으로 Xcode Command Line Tools 을 설치한다.

   xcode-select --install
   

Windows

윈도우에서는 모든 종속 라이브러리를 설치하기 위해 Anaconda3 나 Miniconda3 를 사용해야 한다.

3. 컴파일러 요구사항을 설치한다.

   conda install --update-deps vs2017_win-64 vs2017_win-32 msvc_runtime
   

4. 바이너리를 설치하고 종속 라이브러리를 빌드한다.

   conda install --update-deps -c conda-forge -y openblas cmake
   

5. qiskit-aer를 직접 빌드하고 설치한다.

   만일 당신이 pip 버전 19.0.0 이하를 설치하였고 당신의 환경이 사용자 빌드를 요구하지 않으면 다음을 실행하세요:

   cd qiskit-aer
   pip install .
   

   이것은 바이너리를 빌드하고 Aer를 설치한다.

   만약 최신 버전의 pip가 설치되어 있거나 custom requirement를 가지고 있다면 Python wheel을 직접 build할 수도 있다.

   cd qiskit-aer
   python ./setup.py bdist_wheel
   

   만약 wheel build 중 custom option을 설정해야 할 필요가 있다면, 다음의 문서를 참조하라. 휠 제작 중 사용자 정의 옵션.

   Python wheel을 빌드하면 이는 Aer repository의 dist/ 디렉토리에 저장될 것이다. 정확한 버전은 상황에 따라 다르다.

   cd dist
   pip install qiskit_aer-*.whl
   

   출력되는 wheel file의 정확한 파일명은 현재 개발 중인 Aer의 버전에 따라 다를 것이다.

휠 제작 중 사용자 정의 옵션

Python interface에서 compilation을 실행하기 위하여 build할 때 Aer build system은 scikit-build 를 사용한다. 이는 CMake 를 호출하고 local system의 binaies를 compile하기 위하여 setuptools 를 위한 interface 역할을 한다.

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

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 <https://www.gnu.org/software/automake/>)에 컴파일할 때 8개의 프로세스를 병렬 처리로 사용하라는 -j8 이라는 옵션을 건네준다.

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

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

이 명령어는 씨메이크 (CMake) 에게 Aer를 컴파일할 때, 기본으로 쓰이는 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	숫자와 함께 사용되어서, 컴파일 시 사용할 프로세서의 수를 결정한다.
Linux	씨메이크(CMake)	-DCMAKE_CXX_COMPILER	특정 C++ 컴파일러를 명시하기 위해 사용된다. 이 옵션은 보통 기본 g++ 컴파일러가 너무 오래 되었을 때 사용된다.
OSX	셋업툴 (setuptools)	–plat-name	결과 Python 패키지에 나타나는 플랫폼 이름을 명시하기 위해 사용된다.
OSX	씨메이크(CMake)	-DSTATIC_LINKING	정적 연결을 사용할지 안 사용할지 결정하는데 사용된다.

참고

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

소스 코드로부터 Ignis 설치하기

1. Ignis 코드 저장소를 복제하라

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

2. 저장소 복제는 ``qiskit-ignis``이라는 이름의 로컬 디렉토리를 생성한다.

   cd qiskit-ignis
   

3. 만약 테스트하거나 철자법 검사를 하려면, 개발자 요구 사항을 설치하라. 이것은 소스로부터 qiskit-ignis 패키지를 설치하거나 사용할 때는 필요하지 않다.

   pip install -r requirements-dev.txt
   

4. Ignis 설치하기

   pip install .
   

만약, 프로젝트에 코드가 변화하였을 때 재설치가 필요하지 않는, 수정 가능한 모드로 설치하고자 한다면,

pip install -e .

소스 코드로부터 Aqua 설치하기

1. Aqua 코드 저장소를 복제하라

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

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

   cd qiskit-aqua
   

3. 만약 테스트하거나 철자법 검사를 하려면, 개발자 필수 요소를 설치하라. 이것은 소스로부터 qiskit-aqua 패키지를 설치하거나 사용할 때는 필요하지 않다.

   pip install -r requirements-dev.txt
   

4. Aqua 설치하기

   pip install .
   

만약, 프로젝트에 코드가 변화하였을 때 재설치가 필요하지 않는, 수정 가능한 모드로 설치하고자 한다면,

pip install -e .

소스 코드로부터 IBM 양자 제공자 설치하기

1. qiskit-ibmq-provider 코드 저장소를 복제하라

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

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

   cd qiskit-ibmq-provider
   

3. 만약 테스트하거나 철자법 검사를 하려면, 개발자 필수 요소를 설치하라. 이것은 소스로부터 qiskit-ibmq-provider 패키지를 설치하거나 사용할 때는 필요하지 않다.

   pip install -r requirements-dev.txt
   

4. qiskit-ibmq-provider 설치하기

   pip install .
   

만약, 프로젝트에 코드가 변화하였을 때 재설치가 필요하지 않는, 수정 가능한 모드로 설치하고자 한다면,

pip install -e .