Przewodnik dla współtwórców¶
Niniejszy przewodnik reguluje przepływ pracy współtwórców oraz operacje publikacyjne. Gwarancje architektoniczne pozostają w Architecture & Specification; konwencje stron Web Awesome pozostają w component authoring guide.
Narzędzia i źródło prawdy¶
Projekt i spis treści:
myst.ymlZablokowane dystrybucje Python:
requirements.lockLokalny sterownik kompilacji:
tools/build.shWeryfikacja wstępna:
tools/check_profile.pyPrzepływ pracy publikacji:
.github/workflows/deploy.yml
Lokalny rozwój¶
Przygotuj środowisko, korzystając z przypiętej konfiguracji środowiska Python w repozytorium, a następnie zainstaluj zależności JavaScript za pomocą npm ci. Docelowym środowiskiem uruchomieniowym jest CPython 3.12.14 na systemie Linux x86-64. Walidator wymaga aktywnego środowiska wirtualnego, zarejestrowanego specyfikatora jądra jb2-python oraz jawnego pliku BASE_URL (pusty plik jest poprawny).
Z głównego katalogu repozytorium, po aktywacji zablokowanego środowiska:
npm ci
node scripts/check-node-dependencies.mjs
BASE_URL="" sh tools/build.shSterownik kompilacji sprawdza profil, weryfikuje pochodzenie tłumaczenia, buduje wszystkie włączone wersje językowe, przygotowuje zasoby Web Awesome oraz waliduje wynikowy artefakt publikacji. Nie jest to alternatywa dla uruchamiania zautomatyzowanych zestawów testów repozytorium.
Edycja podręcznika¶
Edytuj istniejące, wiążące źródło w języku angielskim w formacie Markdown lub jako notatnik. Nie wklejaj kopii plików implementacyjnych repozytorium do dokumentacji narracyjnej.
W przypadku nowej strony dodaj dokładnie jeden wpis
project.toci zweryfikuj jego kanoniczną ścieżkę.Używaj wbudowanych elementów języka MyST oraz zatwierdzonych dyrektyw Web Awesome do prezentacji przykładów oraz dostępnego interfejsu użytkownika.
Zgłaszaj aktualizacje tłumaczeń z poprawnym pochodzeniem (provenance) podczas modyfikowania stron już zlokalizowanych. Nowe strony opcjonalne mogą być publikowane najpierw w języku angielskim, jednak strony obowiązkowe w
i18n/locales.ymlpozostają objęte ścisłymi wymaganiami.Utrzymuj głębokie linki (deep links) do laboratoriów skierowane do ich niezależnych domen.
Przegląd i publikacja¶
Przepływ pracy GitHub Actions opiera się na main i wdraża zaakceptowaną witrynę statyczną na GitHub Pages. Najpierw należy przejrzeć zmiany w gałęzi (branch) lub pul requestcie. Opublikowana strona główna nie może sugerować wykonywania notatników po stronie przeglądarki; kod i wyniki muszą w dalszym ciągu pochodzić ze zweryfikowanej kompilacji.
Aby zapoznać się z implementacją niskiego poziomu i kontrolami bezpieczeństwa, skorzystaj z sekcji Architecture & Specification.