Tài liệu này trình bày cách tạo một trình bổ trợ mới. Mặc dù quy trình này mô tả cách tạo các 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 hướng dẫn để tạo các 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 một trình bổ trợ, hãy xem Bài nói về cách tạo trình bổ trợ (2021) của chúng tôi.
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 và sử dụng trình bổ trợ thông qua npm.
Các trình bổ trợ của bên thứ nhất được nhóm Blockly hỗ trợ và xuất bản trong phạm vi @blockly trên npm. Các khối 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 tệp này được lưu trữ trong blockly-samples. Trường để thiết lập tốc độ động cơ có thể được dùng trong nhiều dự án về robot và là một lựa chọn phù hợp cho trình bổ trợ của bên thứ nhất.
Các trình bổ trợ của bên thứ ba được duy trì và xuất bản độc lập. Chúng 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 hẹp hơn của các ứng dụng Blockly. Trường để chỉnh sửa một đối tượng cụ thể do lược đồ cơ sở dữ liệu của bạn xác định sẽ phù hợp hơn khi là một trình bổ trợ của bên thứ ba.
Tiêu chí của bên thứ nhất
Các 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 được nhóm Blockly 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 monkeypatch Blockly.
- Có một 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 hàm gói từ lõi Blockly, trừ phi được nhóm Blockly 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 yêu cầu chúng tôi trong một vấn đề trên blockly-samples.
- Có bài kiểm tra.
Quy trình
Các trình bổ trợ trải qua 4 giai đoạn: đề xuất, thảo luận, triển khai và xuất bản.
Đề 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. Để biết thêm thông tin, hãy đọc bài viết 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 về 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, GIF hoặc bản mô phỏng nếu trình bổ trợ có các tính năng giao diện người dùng.
- Giải thích lý do nên dùng 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ợ tốt của bên thứ nhất.
Thảo luận
Tiếp theo, một 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ập kế hoạch triển khai.
- Lập kế hoạch cho các bài kiểm tra.
- 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 cho 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 đá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 đề của 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à những ý kiến mạnh mẽ về Giải pháp phù hợp. Nếu vấn đề của bạn thuộc trường hợp này, xin chúc mừng! Bạn đã tìm thấy nội dung mà mọi người quan tâm.
Mục tiêu là đến cuối giai đoạn thảo luận, tất cả các quyết định quan trọng về thiết kế đề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 tôi 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 xuất bản 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.
- Tài liệu về 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 vấn đề đó có còn mở để đóng góp hay không.
Nhiều người đóng góp có thể triển khai song song. Bạn có thể triển khai một trình bổ trợ cùng nhau trên nhánh riêng của mình 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 các 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ẽ khiến các plugin đó xuất hiện trên trang web Plugins 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 chúng. Bạn cũng có thể thêm các trình bổ trợ của bên thứ ba vào trang này và có thể trỏ đến một đườ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 là xuất bản. Nhóm Blockly sử dụng Lerna để quản lý việc lập phiên bản và xuất bản cho tất cả các trình bổ trợ.
Vào mỗi thứ Năm, mọi trình bổ trợ đã thay đổi kể từ lần phát hành gần đây nhất đều được xuất bản. Nếu bạn cần xuất bản thay đổi sớm hơn, vui lòng lưu ý điều này trong yêu cầu kéo của bạn.
Trang web Trình bổ trợ cũng được cập nhật mỗi khi trình bổ trợ được xuất bản.
Bạn nên đánh dấu private cho những trình bổ trợ chưa sẵn sàng xuất bản 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 xuất bản trong Blockly cốt lõi. Blockly cốt lõi được xuất bản vào tuần cuối cùng của mỗi quý (3 tháng một lần).