Udostępnij za pośrednictwem

Współtworzenie jądra semantycznego

  • Artykuł

Możesz współtworzyć jądro semantyczne, przesyłając problemy, rozpoczynając dyskusje i przesyłając żądania ściągnięcia (PRs). Współtworzenie kodu jest bardzo doceniane, ale po prostu zgłaszanie problemów, które napotykasz, jest również doskonałym sposobem na współtworzenie, ponieważ pomaga nam skupić nasze wysiłki.

Zgłaszanie problemów i opinii

Zawsze mile widziane są raporty o błędach, propozycje interfejsu API i ogólna opinia. Ponieważ używamy usługi GitHub, możesz użyć kart Problemy i dyskusje , aby rozpocząć rozmowę z zespołem. Poniżej przedstawiono kilka wskazówek dotyczących przesyłania problemów i opinii, abyśmy mogli odpowiedzieć na Twoją opinię tak szybko, jak to możliwe.

Raportowanie problemów

Nowe problemy dotyczące zestawu SDK można zgłaszać na naszej liście problemów, ale przed zgłoszeniem nowego problemu wyszukaj listę problemów, aby upewnić się, że jeszcze nie istnieje. Jeśli masz problemy z dokumentacją jądra semantycznego (w tej witrynie), zgłoś problem w repozytorium dokumentacji jądra semantycznego.

Jeśli znajdziesz istniejący problem dotyczący tego, co chcesz zgłosić, dołącz własną opinię do dyskusji. Zdecydowanie zalecamy również głosowanie (👍 reakcja) oryginalnego postu, ponieważ pomaga nam to określić priorytety popularnych problemów na naszej liście prac.

Pisanie dobrego raportu o błędach

Dobre raporty o usterkach ułatwiają konserwatorom weryfikowanie i przyczynę problemu podstawowego. Tym lepiej raport o usterce, tym szybciej można rozwiązać problem. W idealnym przypadku raport o usterce powinien zawierać następujące informacje:

  • Ogólny opis problemu.
  • Minimalna reprodukcja, tj. najmniejszy rozmiar kodu/konfiguracji wymaganej do odtworzenia niewłaściwego zachowania.
  • Opis oczekiwanego zachowania, w przeciwieństwie do rzeczywistego zachowania zaobserwowanego.
  • Informacje na temat środowiska: system operacyjny/dystrybucja, architektura procesora CPU, wersja zestawu SDK itp.
  • Dodatkowe informacje, np. Czy jest to regresja z poprzednich wersji? Czy istnieją znane obejścia?

Problem z tworzeniem

Przesyłanie opinii

Jeśli masz ogólną opinię na temat semantycznego jądra lub pomysłów na to, jak go ulepszyć, podziel się nim na naszej tablicy dyskusyjnej. Przed rozpoczęciem nowej dyskusji wyszukaj listę dyskusji, aby upewnić się, że jeszcze nie istnieje.

Zalecamy użycie kategorii pomysłów, jeśli masz konkretny pomysł, który chcesz udostępnić i kategorię pytań i odpowiedzi, jeśli masz pytanie dotyczące jądra semantycznego.

Możesz również rozpocząć dyskusje (i podzielić się swoją opinią) w społeczności Discord, dołączając do serwera Niezgody jądra semantycznego.

Rozpocznij dyskusję

Pomóż nam ustalić priorytety opinii

Obecnie używamy głosów w celu ułatwienia nam określania priorytetów problemów i funkcji na naszej liście prac, więc zagłosuj na wszelkie problemy lub dyskusje, które chcesz rozwiązać.

Jeśli uważasz, że inni skorzystają z funkcji, zachęcamy również do proszenia innych o głosowanie nad tą kwestią. Pomaga to ustalić priorytety problemów, które mają wpływ na większość użytkowników. Możesz poprosić współpracowników, znajomych lub społeczność w Discord o głosowanie nad problemem, udostępniając link do problemu lub dyskusji.

Przesyłanie żądań ściągnięcia

Zapraszamy do udziału w semantycznym jądrze. Jeśli masz poprawkę błędów lub nową funkcję, którą chcesz współtworzyć, wykonaj poniższe kroki, aby przesłać żądanie ściągnięcia. Następnie osoby odpowiedzialne za projekt przejrzy zmiany kodu i scalą je po zaakceptowaniu.

Zalecamy użycie następującego przepływu pracy w celu współtworzenia jądra semantycznego (jest to ten sam przepływ pracy używany przez zespół jądra semantycznego):

  1. Utwórz problem dotyczący pracy.
    • Ten krok można pominąć w przypadku trywialnych zmian.
    • Użyj ponownie istniejącego problemu w temacie, jeśli istnieje.
    • Uzyskaj umowę od zespołu i społeczności, że proponowana zmiana jest dobra, korzystając z dyskusji w tym problemie.
    • Jasno określ problem, który zostanie wdrożeniu. Dzięki temu możemy przypisać ci problem i zagwarantować, że ktoś inny nie przypadkowo na nim działa.
  2. Utwórz osobiste rozwidlenie repozytorium w usłudze GitHub (jeśli jeszcze go nie masz).
  3. W rozwidleniu utwórz gałąź poza gałęzią main (git checkout -b mybranch).
    • Nazwij gałąź, aby wyraźnie komunikowała twoje intencje, takie jak "issue-123" lub "githubhandle-issue".
  4. Wprowadź i zatwierdź zmiany w gałęzi.
  5. Dodaj nowe testy odpowiadające zmianie, jeśli ma to zastosowanie.
  6. Skompiluj repozytorium przy użyciu zmian.
    • Upewnij się, że kompilacje są czyste.
    • Upewnij się, że wszystkie testy przechodzą, w tym nowe testy.
  7. Utwórz żądanie ściągnięcia względem głównej gałęzi repozytorium.
    • Stan w opisie, jaki problem lub poprawa zmiany dotyczy.
    • Sprawdź, czy wszystkie testy ciągłej integracji są pomijane.
  8. Poczekaj na opinię lub zatwierdzenie zmian ze strony wykonawców kodu.
  9. Gdy właściciele obszaru się podpisali, a wszystkie kontrole są zielone, żądanie ściągnięcia zostanie scalone.

Dos i Don'ts podczas współtworzenia

Poniżej znajduje się lista funkcji Dos i Nie zaleca się, aby współtworzyć jądro semantyczne, aby ułatwić nam szybkie przeglądanie i scalanie zmian.

Czy:

  • Postępuj zgodnie ze standardowym stylem kodowania platformy .NET i stylem kodu w języku Python
  • Należy przyznać priorytet bieżącemu stylowi projektu lub pliku, który zmienia się, jeśli różni się on od ogólnych wytycznych.
  • Uwzględnij testy podczas dodawania nowych funkcji. Podczas naprawiania usterek zacznij od dodania testu, który podkreśla, jak bieżące zachowanie jest uszkodzone.
  • Należy skupić się na dyskusjach. Gdy pojawia się nowy lub powiązany temat, często lepiej jest utworzyć nowy problem niż śledzić dyskusję.
  • Należy wyraźnie stwierdzić problem, który zamierzasz wdrożyć.
  • Czy blog i/lub tweet o swoich wkładach!

Zakazów:

  • Nie zaskakuj zespołu dużymi żądaniami ściągnięcia. Chcemy wspierać współautorów, dlatego zalecamy złożenie problemu i rozpoczęcie dyskusji, abyśmy mogli uzgodnić kierunek, zanim zainwestujesz dużo czasu.
  • Nie zatwierdzaj kodu, którego nie zapisano. Jeśli znajdziesz kod, który uważasz za dobry do dodania do jądra semantycznego, zgłoś problem i rozpocznij dyskusję przed kontynuowaniem.
  • Nie przesyłaj żądań ściągnięcia, które zmieniają pliki lub nagłówki powiązane z licencjonowaniem. Jeśli uważasz, że wystąpił problem, zgłoś problem i chętnie go omówimy.
  • Nie wprowadzaj nowych interfejsów API bez zgłaszania problemu i najpierw omawiaj z zespołem. Dodanie nowego obszaru powierzchni publicznej do biblioteki jest bardzo ważne i chcemy upewnić się, że mamy to prawo.

Zmiany powodujące niezgodność

Współtworzenie musi obsługiwać sygnaturę interfejsu API i zgodność behawioralną. Jeśli chcesz wprowadzić zmianę, która spowoduje przerwanie istniejącego kodu, zgłoś problem w celu omówienia pomysłu lub zmiany, jeśli uważasz, że zmiana powodująca niezgodność jest uzasadniona. W przeciwnym razie zmiany powodujące niezgodność zostaną odrzucone.

Proces ciągłej integracji

System ciągłej integracji (CI) automatycznie wykonuje wymagane kompilacje i uruchamia testy (w tym te, które należy również uruchamiać lokalnie) dla żądania ściągnięcia. Kompilacje i przebiegi testowe muszą być czyste, zanim będzie można scalić żądanie ściągnięcia.

Jeśli kompilacja ciągłej integracji zakończy się niepowodzeniem z jakiegokolwiek powodu, problem z żądaniem ściągnięcia zostanie zaktualizowany za pomocą linku, którego można użyć do określenia przyczyny awarii, aby można było go rozwiązać.

Współtworzenia dokumentacji

Akceptujemy również współtworzenie repozytorium dokumentacji jądra semantycznego.