Dodawanie wtyczki

Z tego dokumentu dowiesz się, jak utworzyć nowy wtyczkę. Chociaż opisany proces dotyczy tworzenia własnych wtyczek, możesz go wykorzystać jako wskazówkę do tworzenia wtyczek innych firm.

Omówienie wtyczek znajdziesz w artykule Wtyczki.

Krótkie wprowadzenie do tworzenia wtyczki znajdziesz w prezentacji How to Build a Plugin (2021) (Jak tworzyć wtyczki (2021)).

Własne i inne listy odbiorców

Docelowy użytkownik wtyczki to programista, który znajduje i używa wtyczki za pomocą npm.

Wtyczki własne są obsługiwane przez zespół Blockly i publikowane w zakresie @blockly w npm. Zostały zaprojektowane tak, aby można było ich używać w szerokim zakresie aplikacji Blockly. Są stabilne i łatwe w użyciu. Są one przechowywane w pliku blockly-samples. Pole do ustawiania prędkości silnika może być używane w wielu projektach robotyki i jest dobrym kandydatem na wtyczkę własnego producenta.

Wtyczki innych firm są obsługiwane i publikowane niezależnie. Mogą być bardziej złożone, bardziej eksperymentalne lub kierowane na węższy zakres aplikacji Blockly. Pole do edycji konkretnego obiektu zdefiniowanego przez schemat bazy danych lepiej nadaje się jako wtyczka innej firmy.

Kryteria własne

Wtyczki własne muszą spełniać te wymagania:

  • pracować na wszystkich głównych platformach, chyba że zespół Blockly udzieli Ci zwolnienia;
    • Chrome, Firefox, Safari, Edge
  • Autor musi być gotowy do rozwiązywania problemów przez pierwszy rok.
  • Nie modyfikuj kodu źródłowego Blockly.
  • mieć wyraźnie zdefiniowany i udokumentowany interfejs API;
  • Nie wywołuj funkcji prywatnych ani funkcji pakietu z rdzenia Blockly, chyba że zespół Blockly udzieli Ci odpowiedniego zwolnienia.
    • Dozwolone jest zastępowanie funkcji pakietu w określonej przez Ciebie podklasie.
    • Jeśli chcesz uzyskać zwolnienie, poproś nas o to w problemie dotyczącym blockly-samples.
  • Testy.

Procedura

Wtyczki przechodzą przez 4 etapy: sugestia, dyskusja, implementacja i publikowanie.

Sugestia

Wtyczka zaczyna się od sugestii. Aby zaproponować wtyczkę, utwórz nowy problem za pomocą szablonu Prośba o funkcję.

Dowiedz się, jak przesłać prośbę o dodanie funkcji

Oprócz podstawowych informacji o prośbie o funkcję wtyczka powinna zawierać:

  • Interfejs API, który wtyczka udostępnia.
  • Interfejsy API, które należy dodać lub zmienić w podstawowym programie Blockly, aby obsługiwać wtyczkę.
  • zrzuty ekranu, GIF-y lub makiety, jeśli wtyczka zawiera funkcje interfejsu użytkownika;
  • wyjaśnienie, dlaczego powinna to być wtyczka firmy Google, a nie wtyczka innej firmy;

Zespół Blockly sprawdza otrzymywane sugestie i zamyka zgłoszenie lub zgadza się, że jest to dobry wtyczek własny.

Dyskusja

Następnie wtyczka przechodzi do fazy dyskusji. Ta faza obejmuje:

  • wyjaśnienie pożądanej funkcji;
  • wyjaśnienie interfejsu API wtyczki.
  • Planowanie wdrożenia.
  • planowanie testów,
  • Dyskusja na temat zmian w interfejsie API w podstawowej wersji Blockly.
  • Podziel duże wtyczki na etapy implementacji.
  • Nazewnictwo wtyczek zgodnie z naszą konwencją nazewnictwa.
  • Potwierdź, że wszystkie kryteria własne zostaną spełnione.

Dyskusja odbywa się zazwyczaj na stronie problemu w GitHub. Im węższy zakres wtyczki, tym szybciej może przebiegać faza dyskusji. Większe wtyczki mogą przyciągać uwagę społeczności i wywoływać zdecydowane opinie na temat właściwego rozwiązania. Jeśli tak się stało, gratulacje! Znaleźli coś, co jest ważne dla innych.

Celem jest, aby pod koniec fazy dyskusji zostały podjęte wszystkie najważniejsze decyzje projektowe i uzyskano przejrzystą listę kroków wdrażania. Oba te elementy powinny być opisane w komentarzach dotyczących problemu.

Podczas dyskusji możemy zdecydować, że wtyczka powinna być wtyczką innej firmy i nie powinna być publikowana w ramach @blockly. W takim przypadku wyjaśnimy, dlaczego tak się stało, i zamkniemy zgłoszenie.

Po zakończeniu dyskusji członek zespołu Blockly informuje, że funkcja jest gotowa do wdrożenia.

Implementacja

Etapy wdrażania:

  • Uruchomienie npx @blockly/create-package w celu skonfigurowania wtyczki i jej katalogu na podstawie szablonu. Więcej informacji
  • Implementacja logiki podstawowej wtyczki.
  • W razie potrzeby wdrożenie interfejsu użytkownika.
  • testowanie wtyczki za pomocą platformy Mocha.
  • Dokumentacja wtyczki, w tym README.

Jeśli sugerowany wtyczka została zatwierdzona do wdrożenia, a chcesz nad nią pracować, dodaj komentarz do zgłoszenia i zapytaj, czy nadal można dodawać do niej swój wkład.

Wdrożenie może być przeprowadzane równolegle przez wielu współtwórców. Możesz wdrożyć wtyczkę w ramach współpracy w swojej własnej gałęzi lub za pomocą żądań pull w tym repozytorium. Jeśli chcesz współpracować nad wtyczką w tym repozytorium, poproś zespół Blockly o utworzenie dla Ciebie gałęzi funkcji.

Wtyczki należy dodać do pliku gh-pages/index.md w gałęzi master w blokly-samples. Dzięki temu pojawią się one na naszej stronie z wtyczkami. Własne wtyczki powinny wskazywać na stronę testową. Na tej stronie możesz też dodawać wtyczki innych firm, które mogą wskazywać na link wybrany przez właściciela, np. na stronę demonstracyjną lub stronę npm.

Publikowanie

Na koniec opublikuj. Zespół Blockly używa Lerna do zarządzania wersjami i publikowaniem wszystkich wtyczek.

Każdego czwartku publikowane są wszystkie wtyczki, które uległy zmianie od czasu ostatniej publikacji. Jeśli chcesz, aby zmiana została opublikowana wcześniej, zaznacz to w prośbie o przeniesienie.

Strona Wtyczki jest też aktualizowana za każdym razem, gdy publikowane są nowe wtyczki.

Wtyczki, które nie są gotowe do opublikowania, powinny być oznaczone symbolem private w polu package.json. Może się tak zdarzyć, jeśli wtyczka opiera się na zmianie, która nie została jeszcze opublikowana w głównym kodzie Blockly. Wersja podstawowa Blockly jest publikowana w ostatnim tygodniu każdego kwartału (raz na 3 miesiące).