Dokumentacja deweloperska Orbit (Polski)

Ten folder zawiera przewodniki krok po kroku, gotowe do skopiowania, dotyczące rozszerzania podsystemów w tym repozytorium. Odpowiada na pytania typu "jak dodać X" — to nie jest przegląd architektury (ten należy do CLAUDE.md) ani dokumentacja API (od tego jest czytanie kodu).

Angielska wersja każdego z tych przewodników znajduje się w ../en/, zachowując dokładnie tę samą strukturę plik-po-pliku. Zobacz ../README.md, jak obie wersje są utrzymywane w synchronizacji.

Struktura

Jeden podfolder na podsystem/obszar funkcjonalny. Każdy podfolder ma własny README.md indeksujący znajdujące się w nim przewodniki.

documentation/
  README.md                  <- indeks językowy (English/Polski)
  en/
    README.md                <- angielska wersja tego pliku
    integrations/            <- angielskie tłumaczenie każdego przewodnika poniżej
    permissions/             <- angielskie tłumaczenie każdego przewodnika poniżej
    notifications/           <- angielskie tłumaczenie każdego przewodnika poniżej
    alerts/                  <- angielskie tłumaczenie każdego przewodnika poniżej
    theme-colors/            <- angielskie tłumaczenie każdego przewodnika poniżej
    accent-colors/           <- angielskie tłumaczenie każdego przewodnika poniżej
    avatars/                 <- angielskie tłumaczenie każdego przewodnika poniżej
    architecture/            <- angielskie tłumaczenie każdego przewodnika poniżej
    settings-tabs/           <- angielskie tłumaczenie każdego przewodnika poniżej
    shortcuts/               <- angielskie tłumaczenie każdego przewodnika poniżej
    command-palette/         <- angielskie tłumaczenie każdego przewodnika poniżej
    storybook/               <- angielskie tłumaczenie każdego przewodnika poniżej
    redis/                   <- angielskie tłumaczenie każdego przewodnika poniżej
    content-moderation/      <- angielskie tłumaczenie każdego przewodnika poniżej
    project-invitations/     <- angielskie tłumaczenie każdego przewodnika poniżej
    activity-log/            <- angielskie tłumaczenie każdego przewodnika poniżej
    saved-filters/           <- angielskie tłumaczenie każdego przewodnika poniżej
    dropdowns/               <- angielskie tłumaczenie każdego przewodnika poniżej
    labels/                  <- angielskie tłumaczenie każdego przewodnika poniżej
    priorities/              <- angielskie tłumaczenie każdego przewodnika poniżej
    issue-types/             <- angielskie tłumaczenie każdego przewodnika poniżej
    issue-views/             <- angielskie tłumaczenie każdego przewodnika poniżej
    rich-text-editor/        <- angielskie tłumaczenie każdego przewodnika poniżej
    backup/                  <- angielskie tłumaczenie każdego przewodnika poniżej
    project-onboarding/      <- angielskie tłumaczenie każdego przewodnika poniżej
  pl/
    README.md                <- ten plik
    integrations/
      README.md              <- indeks tej kategorii
      01-add-a-new-integration.md
      02-add-integration-settings.md
      03-add-a-new-event-type.md
      04-frontend-backend-wiring-overview.md
      05-add-an-import-integration.md
    permissions/
      README.md              <- indeks tej kategorii
      01-add-a-new-permission.md
      02-add-a-new-role-tier.md
      03-grant-a-custom-role-in-bulk.md
    notifications/
      README.md              <- indeks tej kategorii
      01-add-a-new-notification-type.md
      02-send-a-notification-from-your-code.md
      03-frontend-backend-wiring-overview.md
      04-add-a-dedicated-transactional-email.md
    alerts/
      README.md              <- indeks tej kategorii
      01-trigger-an-alert-from-the-backend.md
      02-trigger-an-alert-from-the-frontend.md
      03-add-a-new-alert-type.md
      04-customize-alert-behavior.md
      05-testing-components-that-use-alerts.md
    theme-colors/
      README.md              <- indeks tej kategorii
      01-how-theme-switching-works.md
      02-add-a-new-theme-color-token.md
      03-use-a-theme-color-in-a-component.md
      04-theme-colors-in-emails.md
    accent-colors/
      README.md              <- indeks tej kategorii
      01-add-a-new-accent-color.md
      02-use-the-accent-color-in-a-component.md
    avatars/
      README.md              <- indeks tej kategorii
      01-add-a-new-avatar-face.md
    architecture/
      README.md              <- indeks tej kategorii
      01-tech-stack-and-project-structure.md
      02-backend-layered-architecture.md
      03-frontend-architecture-and-atomic-design.md
      04-docker-doppler-and-deployment.md
      05-scope-and-non-goals.md
    settings-tabs/
      README.md              <- indeks tej kategorii
      01-flip-a-placeholder-tab-live.md
      02-add-a-brand-new-settings-tab.md
    shortcuts/
      README.md              <- indeks tej kategorii
      01-register-a-component-scoped-shortcut.md
      02-register-a-global-shortcut.md
    command-palette/
      README.md              <- indeks tej kategorii
      01-add-a-global-command.md
      02-add-a-contextual-command-with-nested-steps.md
      03-add-a-search-source.md
    content-moderation/
      README.md              <- indeks tej kategorii
      01-add-moderation-to-a-new-upload-point.md
      02-configure-and-tune-moderation.md
    project-invitations/
      README.md              <- indeks tej kategorii
      01-invite-multiple-emails-at-once.md
    activity-log/
      README.md              <- indeks tej kategorii
      01-log-a-new-kind-of-activity.md
      02-surface-the-activity-log-in-the-ui.md
    saved-filters/
      README.md              <- indeks tej kategorii
      01-extract-the-service-layer.md
      02-make-context-scope-which-filters-show.md
    labels/
      README.md              <- indeks tej kategorii
      01-add-a-new-default-label.md
      02-expose-project-labels-to-a-new-page.md
    priorities/
      README.md              <- indeks tej kategorii
      01-change-the-starter-priorities.md
      02-show-priorities-on-a-new-page.md
    issue-types/
      README.md              <- indeks tej kategorii
      01-add-a-new-default-issue-type.md
      02-add-a-workflow-status-category.md
      03-extend-required-fields.md
      04-add-a-new-list-column.md
    issue-views/
      README.md              <- indeks tej kategorii
      01-add-a-new-issue-view.md
      02-load-view-data-lazily.md
    rich-text-editor/
      README.md              <- indeks tej kategorii
      01-add-a-new-tiptap-extension.md
    backup/
      README.md              <- indeks tej kategorii
      01-run-configure-and-restore-database-backups.md
    project-onboarding/
      README.md              <- indeks tej kategorii
      01-add-a-tour-step.md
      02-add-an-interactive-tour-step.md
    dropdowns/
      README.md              <- indeks tej kategorii
      01-add-a-dropdown.md
    automation/
      README.md              <- indeks tej kategorii
      01-add-a-new-trigger-type.md
      02-add-a-new-action-type.md
    authentication/
      README.md              <- indeks tej kategorii
      01-add-an-oauth-provider.md
    storybook/
      README.md              <- indeks tej kategorii
      01-write-a-story.md
      02-mock-inertia-and-network.md
      03-theme-accent-and-docker.md
      04-stories-as-vitest-tests.md
    redis/
      README.md              <- indeks tej kategorii
      01-run-and-operate-redis.md
      02-cache-a-value-and-invalidate-it.md
      03-sessions-on-redis.md

Kiedy dodać lub zaktualizować przewodnik

Zawsze, gdy budujesz coś naprawdę nowego — nowy podsystem, nowy rodzaj rzeczy rozszerzalnej ("podłącz tu nowe X"), nową kategorię uprawnień, nowy przepływ oparty na eventach — dodaj przewodnik (albo nowy numerowany krok w istniejącej kategorii), który pokazuje, na prawdziwym kodzie z tego repozytorium, dokładnie jak rozszerzyć to następnym razem. Zrób to zanim uznasz funkcję za skończoną.

Małe, jednorazowe zmiany w istniejącym kodzie nie wymagają nowego przewodnika — dokumentuj tylko faktycznie nowy punkt rozszerzenia, gdy już istnieje, żeby następna osoba (albo kolejna sesja) nie musiała odtwarzać go z diffa.

Przewodniki muszą:

Być plikami .md.
Być faktycznie krok po kroku (numerowane kroki, w kolejności, w jakiej naprawdę byś je wykonywał).
Zawierać pełny, działający kod — nie fragmenty z lukami // ... — skopiowany z (lub napisany dokładnie w stylu) prawdziwych plików w tym repo, z ich prawdziwymi ścieżkami.
Wskazywać na konkretne pliki testów do zaktualizowania/dodania, nie tylko na kod produkcyjny.
Istnieć w obu folderach, en/ i pl/, pod tą samą względną ścieżką. Napisz najpierw wersję angielską, potem dodaj/zaktualizuj jej polski odpowiednik w tym samym commicie — zobacz ../README.md po zasadę tłumaczenia (bloki kodu zostają dosłownie po angielsku; tłumaczona jest tylko proza).

Zobacz integrations/README.md po przykład tego formatu w praktyce.