Tài liệu này thảo luận về cách tạo trình bổ trợ mới. Mặc dù quy trình này mô tả cách tạo trình bổ trợ của bên thứ nhất, nhưng bạn có thể sử dụng quy trình này làm nguyên tắc để tạo trình bổ trợ của bên thứ ba.
Để biết thông tin tổng quan về trình bổ trợ, hãy xem phần Trình bổ trợ.
Để biết thông tin giới thiệu nhanh về cách tạo trình bổ trợ, hãy xem bài nói chuyện về Cách tạo trình bổ trợ (2021).
Bên thứ nhất so với bên thứ ba
Người dùng mục tiêu của một trình bổ trợ là nhà phát triển tìm thấy và sử dụng trình bổ trợ thông qua npm.
Trình bổ trợ của bên thứ nhất được nhóm Blockly hỗ trợ và phát hành trong phạm vi @blockly trên npm. Các thành phần này được thiết kế để có thể sử dụng trong nhiều ứng dụng Blockly, đồng thời ổn định và dễ sử dụng. Các mẫu này được lưu trữ trong blockly-samples. Trường để đặt tốc độ động cơ có thể được sử dụng trong nhiều dự án robot và là một ứng cử viên phù hợp cho trình bổ trợ của bên thứ nhất.
Trình bổ trợ của bên thứ ba được duy trì và phát hành một cách độc lập. Các hàm này có thể phức tạp hơn, mang tính thử nghiệm hơn hoặc nhắm đến một phạm vi ứng dụng Blockly hẹp hơn. Tốt hơn là bạn nên dùng trình bổ trợ của bên thứ ba làm trường để chỉnh sửa một đối tượng cụ thể do giản đồ cơ sở dữ liệu xác định.
Tiêu chí của bên thứ nhất
Trình bổ trợ của bên thứ nhất phải đáp ứng các yêu cầu sau:
- Hoạt động trên tất cả các nền tảng chính, trừ phi nhóm Blockly cấp trường hợp miễn trừ.
- Chrome, Firefox, Safari, Edge
- Có một tác giả sẵn sàng xử lý lỗi trong năm đầu tiên.
- Không sửa lỗi Blockly.
- Có API được xác định và ghi lại rõ ràng.
- Không gọi các hàm riêng tư hoặc gói từ lõi Blockly, trừ khi nhóm Blockly cấp quyền miễn trừ.
- Bạn được phép ghi đè các hàm gói trên một lớp con mà bạn xác định.
- Nếu bạn muốn được miễn trừ, hãy hỏi chúng tôi trong một vấn đề trên blockly-samples.
- Có bài kiểm thử.
Quy trình
Trình bổ trợ trải qua 4 giai đoạn: đề xuất, thảo luận, triển khai và phát hành.
Đề xuất
Trình bổ trợ bắt đầu dưới dạng một đề xuất. Bạn có thể đề xuất một trình bổ trợ bằng cách tạo một vấn đề mới bằng mẫu Yêu cầu tính năng.
Đọc về cách viết yêu cầu về tính năng
Ngoài thông tin cơ bản về yêu cầu tính năng, đề xuất trình bổ trợ phải bao gồm:
- API mà trình bổ trợ sẽ hiển thị.
- Các API cần được thêm hoặc thay đổi trong Blockly cốt lõi để hỗ trợ trình bổ trợ.
- Ảnh chụp màn hình, ảnh GIF hoặc bản minh hoạ nếu trình bổ trợ có các tính năng giao diện người dùng.
- Nội dung giải thích lý do trình bổ trợ phải là trình bổ trợ của bên thứ nhất thay vì trình bổ trợ của bên thứ ba.
Nhóm Blockly sẽ xem xét các đề xuất khi nhận được và đóng vấn đề hoặc đồng ý rằng đó sẽ là một trình bổ trợ phù hợp của bên thứ nhất.
Thảo luận
Tiếp theo, trình bổ trợ sẽ chuyển sang giai đoạn thảo luận. Giai đoạn này bao gồm:
- Làm rõ chức năng mong muốn.
- Làm rõ API của trình bổ trợ.
- Lên kế hoạch triển khai.
- Lập kế hoạch kiểm thử.
- Thảo luận về các thay đổi đối với API trong Blockly cốt lõi.
- Chia các trình bổ trợ lớn thành các bước triển khai.
- Đặt tên trình bổ trợ, dựa trên quy ước đặt tên của chúng tôi.
- Xác nhận rằng bạn sẽ đáp ứng tất cả các tiêu chí của bên thứ nhất.
Cuộc thảo luận này thường diễn ra trên vấn đề GitHub. Phạm vi của trình bổ trợ càng nhỏ thì giai đoạn thảo luận càng nhanh. Các trình bổ trợ lớn hơn có thể thu hút sự chú ý của cộng đồng và ý kiến mạnh mẽ về Giải pháp phù hợp. Nếu điều này xảy ra với vấn đề của bạn, xin chúc mừng! Bạn đã tìm thấy một chủ đề mà mọi người quan tâm.
Mục tiêu là khi kết thúc giai đoạn thảo luận, tất cả các quyết định thiết kế chính đều đã được đưa ra và có một danh sách rõ ràng về các bước triển khai. Cả hai đều phải được ghi lại trong phần bình luận về vấn đề.
Trong quá trình thảo luận, chúng ta có thể quyết định rằng một trình bổ trợ phải là trình bổ trợ của bên thứ ba và không được phát hành trong phạm vi @blockly. Trong trường hợp đó, chúng tôi sẽ giải thích lý do và đóng vấn đề.
Khi cuộc thảo luận kết thúc, một thành viên trong nhóm Blockly sẽ ghi chú rằng cuộc thảo luận đã sẵn sàng để triển khai.
Triển khai
Các bước triển khai bao gồm:
- Chạy
npx @blockly/create-packageđể thiết lập trình bổ trợ và thư mục của trình bổ trợ đó từ một mẫu. Tìm hiểu thêm... - Triển khai logic cốt lõi cho trình bổ trợ.
- Triển khai giao diện người dùng nếu cần.
- Kiểm thử trình bổ trợ bằng Mocha.
- Ghi lại trình bổ trợ, bao gồm cả
README.
Nếu một trình bổ trợ được đề xuất đã được phê duyệt để triển khai và bạn muốn làm việc trên trình bổ trợ đó, hãy bình luận về vấn đề này và hỏi xem trình bổ trợ đó có còn nhận đóng góp hay không.
Nhiều cộng tác viên có thể triển khai song song. Bạn có thể triển khai trình bổ trợ theo cách cộng tác trên nhánh riêng hoặc thông qua các yêu cầu kéo đối với kho lưu trữ này. Nếu bạn muốn cộng tác trên một trình bổ trợ trong kho lưu trữ này, hãy yêu cầu nhóm Blockly tạo một nhánh tính năng cho bạn.
Bạn nên thêm trình bổ trợ vào tệp gh-pages/index.md trong nhánh master của blockly-samples. Điều này sẽ giúp các trình bổ trợ xuất hiện trên trang web Trình bổ trợ của chúng tôi. Trình bổ trợ của bên thứ nhất phải trỏ đến trang kiểm thử của họ. Bạn cũng có thể thêm trình bổ trợ của bên thứ ba vào trang này và có thể trỏ đến đường liên kết do chủ sở hữu của trình bổ trợ chọn, chẳng hạn như bản minh hoạ được lưu trữ hoặc trang npm.
Xuất bản
Cuối cùng, hãy xuất bản. Nhóm Blockly sử dụng Lerna để quản lý việc tạo phiên bản và phát hành cho tất cả các trình bổ trợ.
Vào thứ Năm hằng tuần, mọi trình bổ trợ đã thay đổi kể từ bản phát hành gần đây nhất sẽ được phát hành. Nếu bạn cần thay đổi được xuất bản sớm hơn, vui lòng ghi chú điều đó vào yêu cầu lấy dữ liệu.
Trang web Trình bổ trợ cũng được cập nhật mỗi khi có trình bổ trợ được phát hành.
Các trình bổ trợ chưa sẵn sàng phát hành phải được đánh dấu là private trong package.json. Điều này có thể xảy ra nếu một trình bổ trợ dựa vào một thay đổi chưa được phát hành trong Blockly cốt lõi. Core Blockly được phát hành vào tuần cuối cùng của mỗi quý (3 tháng một lần).