Wnoszenie wkładu

Dziękujemy za zainteresowanie wnoszeniem wkładu. Ten przewodnik opisuje, jak uczestniczyć, co akceptujemy i jak zacząć.

Sposoby wnoszenia wkładu

Zgłoszenia (nie wymagają konfiguracji)

• Zgłoszenia błędów - Coś nie działa? Otwórz zgłoszenie błędu wraz z krokami do odtworzenia problemu.
• Propozycje funkcji - Masz pomysł? Rozpocznij dyskusję, aby społeczność mogła się wypowiedzieć i oddać na nią głos.
• Problemy z tłumaczeniami - Zauważyłeś błędne lub brakujące tłumaczenie? Otwórz zgłoszenie dotyczące tłumaczenia.
• Problemy z dokumentacją - Coś jest nie tak w dokumentacji? Otwórz zgłoszenie dotyczące dokumentacji.

Kod (wymaga CLA)

Akceptujemy pull requesty dotyczące:

Typ	Proces
Poprawki błędów	Otwórz PR bezpośrednio (podlinkuj zgłoszenie, jeśli istnieje)
Nowe tłumaczenia	Otwórz PR bezpośrednio (zobacz Przewodnik po tłumaczeniach)
Ulepszenia dokumentacji	Otwórz PR bezpośrednio
Ulepszenia pokrycia testami	Otwórz PR bezpośrednio
Nowe narzędzia lub funkcje	Najpierw rozpocznij dyskusję; opiekun projektu zamienia zatwierdzone pomysły w śledzone zgłoszenie, zanim zaczniesz pisać kod
Refaktoryzacje lub zmiany architektury	Najpierw rozpocznij dyskusję i poczekaj na akceptację opiekuna projektu, zanim zaczniesz pisać kod

Czego nie zaakceptujemy

• Zmian w przepływach CI/CD, konfiguracji wydań lub konfiguracji lintera/kompilatora
• PR-ów bez podpisanej Umowy licencyjnej współtwórcy
• PR-ów zmieniających ponad 400 wierszy (podziel dużą pracę na mniejsze PR-y)
• Funkcji, które nie zostały wcześniej przedyskutowane i zatwierdzone
• Zmian w packages/ai/ bez wcześniejszej dyskusji

Umowa licencyjna współtwórcy

Zanim będziemy mogli scalić Twój pierwszy PR, musisz podpisać naszą Indywidualną umowę CLA. Jest to wymóg jednorazowy.

Dlaczego: SnapOtter ma podwójną licencję (AGPLv3 + komercyjna). CLA daje nam prawo do dystrybucji Twojego wkładu na obu licencjach. Zachowujesz pełne prawa autorskie do swojej pracy.

Jak: Gdy otworzysz swój pierwszy PR, bot CLA Assistant doda komentarz z odnośnikiem. Kliknij go, zapoznaj się z umową i podpisz ją za pomocą swojego konta GitHub. Zajmuje to 30 sekund.

Jeśli wnosisz wkład w imieniu swojego pracodawcy, a pracodawca zachowuje prawa własności intelektualnej do Twojej pracy, skontaktuj się z [email protected], aby przygotować firmową umowę CLA przed przesłaniem wkładu.

Pierwsze kroki

Wymagania wstępne

• Node.js 22+
• pnpm 9+
• Python 3.11+ (tylko dla narzędzi AI)
• Docker (opcjonalnie, do pełnego testowania integracyjnego)

Konfiguracja

# Fork and clone
git clone https://github.com/<your-username>/snapotter.git
cd snapotter

# Start Postgres + Redis for local dev
docker compose -f docker-compose.dev.yml up -d

# Install dependencies
pnpm install

# Start dev servers (web on :1349, API on :13490)
pnpm dev

Uruchamianie sprawdzeń

Przed przesłaniem PR-a upewnij się, że wszystkie sprawdzenia przechodzą lokalnie:

pnpm lint          # Biome lint + format check
pnpm typecheck     # TypeScript across monorepo
pnpm test          # Vitest unit + integration tests

Proces pull requesta

1. Sforkuj repozytorium i utwórz gałąź z main (feat/my-feature lub fix/issue-123)
2. Wprowadź zmiany w skupionych, łatwych do przejrzenia commitach, używając konwencjonalnych commitów
3. Dodaj lub zaktualizuj testy dla swoich zmian
4. Uruchom pnpm lint && pnpm typecheck && pnpm test lokalnie
5. Otwórz PR względem main i wypełnij szablon
6. Podpisz CLA, jeśli zostaniesz o to poproszony
7. Poczekaj, aż CI przejdzie, a opiekun projektu przejrzy zmiany

Czego oczekiwać podczas przeglądu

• Staramy się odpowiadać na PR-y w ciągu 7 dni
• Małe, skupione PR-y są przeglądane szybciej
• Jeśli nie otrzymasz odpowiedzi w ciągu 7 dni, zostaw komentarz przywołujący wątek
• Możemy poprosić o zmiany, zasugerować inne podejście lub zamknąć PR, jeśli nie jest zgodny z kierunkiem projektu

Po scaleniu Twojego PR-a

Twój wkład zostanie uwzględniony w kolejnym wydaniu i wymieniony w dzienniku zmian.

Dobre pierwsze zgłoszenia

Szukasz czegoś do zrobienia? Sprawdź nasze dobre pierwsze zgłoszenia w poszukiwaniu zadań przyjaznych dla początkujących lub potrzebna pomoc w przypadku większych zadań, przy których docenimy pomoc społeczności.

Styl kodu

• Biome zajmuje się formatowaniem i lintowaniem (cudzysłowy podwójne, średniki, wcięcie 2 spacje)
• Hook pre-commit automatycznie uruchamia biome check --write na plikach ze staging
• Jeśli linter zgłasza uwagi, popraw kod (nie modyfikuj konfiguracji Biome)
• Moduły ES wszędzie (import/export)
• Konwencjonalne commity: feat:, fix:, refactor:, docs:, test:, chore:

Pełne informacje o architekturze znajdziesz w Przewodniku dla programistów.

Bezpieczeństwo

Nie otwieraj publicznego PR-a ani zgłoszenia dla luk bezpieczeństwa. Zgłaszaj je prywatnie poprzez GitHub Security Advisories lub e-mailem na [email protected]. Pełne szczegóły znajdziesz w SECURITY.md.

Pytania?

• Dokumentacja
• Discord
• GitHub Discussions