이 문서에서는 새 플러그인을 만드는 방법을 설명합니다. 이 문서에서 설명하는 프로세스는 퍼스트 파티 플러그인을 만들기 위한 것이지만 서드 파티 플러그인을 만드는 가이드라인으로 사용할 수 있습니다.
플러그인 개요는 플러그인을 참고하세요.
플러그인 만들기에 대한 간략한 소개는 플러그인 빌드 방법(2021)을 참고하세요.
퍼스트 파티와 서드 파티의 차이
플러그인의 타겟 사용자는 npm을 통해 플러그인을 찾아 사용하는 개발자입니다.
서드 파티 플러그인은 Blockly팀에서 지원하며 npm의 @blockly 범위로 게시됩니다. 이러한 블록은 다양한 Blockly 애플리케이션에서 사용할 수 있도록 설계되었으며 안정적이고 사용하기 쉽습니다. 이러한 파일은 blockly-samples에 저장되어 있습니다. 모터 속도를 설정하는 필드는 많은 로봇 공학 프로젝트에서 사용할 수 있으며 퍼스트 파티 플러그인에 적합합니다.
서드 파티 플러그인은 독립적으로 유지관리되고 게시됩니다. 더 복잡하거나, 더 실험적이거나, 더 좁은 범위의 Blockly 애플리케이션을 타겟팅할 수 있습니다. 데이터베이스 스키마로 정의된 특정 객체를 수정하는 필드는 서드 파티 플러그인으로 사용하는 것이 좋습니다.
퍼스트 파티 기준
퍼스트 파티 플러그인은 다음 요구사항을 충족해야 합니다.
- Blockly팀에서 예외를 부여하지 않는 한 모든 주요 플랫폼에서 작동해야 합니다.
- Chrome, Firefox, Safari, Edge
- 첫해에 버그를 처리할 의향이 있는 작성자가 있어야 합니다.
- Blockly에 몽키패치를 적용하지 마세요.
- 명확하게 정의되고 문서화된 API가 있어야 합니다.
- Blockly 팀에서 예외를 허용하지 않는 한 Blockly 코어에서 비공개 또는 패키지 함수를 호출하지 마세요.
- 정의한 서브클래스에서 패키지 함수를 재정의하는 것은 허용됩니다.
- 면제를 받으려면 blockly-samples의 문제에서 문의하세요.
- 테스트 제공
절차
플러그인은 제안, 토론, 구현, 게시의 네 단계를 거칩니다.
추천
플러그인은 추천으로 시작됩니다. 기능 요청 템플릿으로 새 문제를 만들어 플러그인을 제안할 수 있습니다. 자세한 내용은 기능 요청 작성 방법을 참고하세요.
기본 기능 요청 정보 외에도 플러그인 제안에는 다음이 포함되어야 합니다.
- 플러그인이 노출할 API입니다.
- 플러그인을 지원하기 위해 핵심 Blockly에 추가하거나 변경해야 하는 API
- 플러그인에 UI 기능이 포함된 경우 스크린샷, GIF 또는 모형
- 서드 파티 플러그인이 아닌 퍼스트 파티 플러그인이어야 하는 이유에 대한 설명
Blockly팀은 제안이 접수되면 이를 검토하고 문제를 종료하거나 서드 파티 플러그인이 적합하다고 판단합니다.
토론
다음으로 플러그인이 토론 단계로 이동합니다. 이 단계에는 다음이 포함됩니다.
- 원하는 기능에 대한 설명
- 플러그인의 API를 명확하게 설명합니다.
- 구현 계획
- 테스트 계획
- 핵심 Blockly의 API 변경사항에 관한 토론
- 큰 플러그인을 구현 단계로 나누기
- Google의 이름 지정 규칙에 따른 플러그인 이름 지정
- 모든 퍼스트 파티 기준이 충족되는지 확인합니다.
이 토론은 일반적으로 GitHub 문제에서 이루어집니다. 플러그인의 범위가 작을수록 토론 단계를 더 빨리 진행할 수 있습니다. 큰 플러그인은 커뮤니티의 관심을 끌고 올바른 솔루션에 대한 강력한 의견을 불러일으킬 수 있습니다. 이러한 상황이 문제에 발생하면 축하드립니다. 사람들이 관심을 갖는 것을 찾은 것입니다.
목표는 토론 단계가 끝날 때 모든 주요 설계 결정이 내려지고 구현 단계의 명확한 목록이 있는 것입니다. 두 가지 모두 문제에 대한 댓글에 문서화되어야 합니다.
토론 중에 플러그인이 서드 파티 플러그인이어야 하고 @blockly 범위로 게시되지 않아야 한다고 결정할 수 있습니다. 이 경우 이유를 설명하고 문제를 종료합니다.
토론이 완료되면 Blockly 팀 구성원이 구현할 준비가 되었다고 언급합니다.
구현
구현 단계는 다음과 같습니다.
- 템플릿에서 플러그인과 디렉터리를 설정하기 위해
npx @blockly/create-package를 실행합니다. 자세히 알아보기 - 플러그인의 핵심 로직을 구현합니다.
- 필요한 경우 UI 구현
- Mocha를 사용하여 플러그인을 테스트합니다.
README를 포함한 플러그인 문서화
추천 플러그인이 구현 승인을 받았고 이를 작업하고 싶다면 문제에 댓글을 달아 아직 기여가 가능한지 문의하세요.
여러 기여자가 동시에 구현할 수 있습니다. 자체 포크에서 공동으로 플러그인을 구현하거나 이 저장소에 대한 풀 요청을 통해 구현할 수 있습니다. 이 저장소에서 플러그인을 공동작업하려면 Blockly팀에 기능 브랜치를 만들어 달라고 요청하세요.
플러그인은 blockly-samples의 master 브랜치에 있는 gh-pages/index.md 파일에 추가해야 합니다. 이렇게 하면 플러그인 사이트에 표시됩니다. 퍼스트 파티 플러그인은 테스트 페이지를 가리켜야 합니다. 이 페이지에 서드 파티 플러그인을 추가할 수도 있으며, 호스팅된 데모나 npm 페이지와 같이 소유자가 선택한 링크를 가리킬 수 있습니다.
게시
마지막으로 게시입니다. Blockly팀은 Lerna를 사용하여 모든 플러그인의 버전 관리 및 게시를 관리합니다.
매주 목요일 마지막 출시 이후 변경된 플러그인이 게시됩니다. 변경사항을 더 빨리 게시해야 하는 경우 풀 요청에 이를 명시해 주세요.
플러그인이 게시될 때마다 플러그인 사이트도 업데이트됩니다.
게시할 준비가 되지 않은 플러그인은 package.json에서 private로 표시해야 합니다. 플러그인이 아직 게시되지 않은 핵심 Blockly의 변경사항을 사용하는 경우 이러한 문제가 발생할 수 있습니다. 핵심 Blockly는 분기 마지막 주에 게시됩니다 (3개월에 한 번).