Jak wspierać Open Source bez znajomości frameworka?

Jak wniosłem wkład do projektu open source, nie znając frameworka

Jestem deweloperem Ruby on Rails z kilkuletnim doświadczeniem w różnych projektach i technologiach. Dwa tygodnie temu, po zakończeniu jednego z projektów, mój CTO wspomniał o Open Mercato — opowiedział, kto stoi za tą inicjatywą, jak szybko się rozwija i dlaczego jego zdaniem warto się w nią zaangażować.

Projekt koncentruje się na oprogramowaniu ERP — obszarze zdominowanym przez przestarzałe systemy, które często nie wspierają nawet podstawowych integracji. Open Mercato podchodzi do tego tematu z nowoczesnym stosem technologicznym, silnym naciskiem na otwartość i możliwości integracyjne oraz aktywnym wsparciem dla najnowszych technik agentowego kodowania opartych na LLM. Firma, w której pracuję, aktywnie wspiera inicjatywy open source — szczególnie te, które mają potencjał stać się gamechangerem w swojej dziedzinie.


Dla mnie osobiście były trzy powody, by spróbować. Po pierwsze — chciałem poszerzyć swoją perspektywę techniczną. Uważam, że deweloper, który rozumie więcej niż jeden ekosystem, po prostu lepiej rozwiązuje problemy. Po drugie — projekt jest zbudowany w TypeScript i Next.js, a ja chciałem zdobyć praktyczne doświadczenie w środowisku JavaScript. TypeScript znam, więc sam język nie był barierą, ale Next.js był dla mnie nowym terytorium. Po trzecie — chciałem świadomie rozwijać swoje umiejętności w zakresie AI-assisted coding. Nie chodzi o to, żeby AI pisało za mnie kod, ale o nauczenie się efektywnego wykorzystywania tych narzędzi jako elementu workflow.

Początek

Po uruchomieniu projektu lokalnie nie rzuciłem się od razu na zgłoszenia. Najpierw chciałem zrozumieć, z czym mam do czynienia. Przeanalizowałem codebase przy użyciu Claude zainstalowanego w IDE, rozszerzonego o dedykowane wtyczki do czytania, analizowania i implementowania kodu. To był świadomy wybór — odpowiednie narzędzia naprawdę robią tu różnicę. Poprosiłem o rozpisanie struktury projektu: jakie moduły są używane, jak zorganizowana jest architektura, jakie są ogólne konwencje. Zapytałem też, czy projekt posiada jakieś pliki z wytycznymi dotyczącymi AI.

Tu pojawiło się pierwsze zaskoczenie — projekt ma rozbudowaną dokumentację AI. Jasne wytyczne dotyczące pisania testów, implementacji kodu, formatu PR-ów. To znacząco przyspieszyło wdrożenie się w projekt.


Mając klarowny obraz architektury i rozumiejąc konwencje, zacząłem szukać pierwszego zadania. Wybrałem coś, co wydawało się dobrze zdefiniowane i zrozumiałe. Znalezienie odpowiedniej części codebase nie było trudne — projekt jest dobrze przetestowany, a same testy działają jak dokumentacja. Po ich przeczytaniu łatwo było wyizolować problematyczny obszar.

Wróciłem wtedy do Claude — poprosiłem o analizę konkretnego fragmentu kodu w kontekście zgłoszenia. Analiza potwierdziła moje przypuszczenia. Kolejny krok: plan naprawy. Zanim jednak przystąpiłem do implementacji, poprosiłem Claude o sprawdzenie, czy funkcje, które zamierzałem modyfikować, są używane w innych częściach projektu — żeby upewnić się, że naprawiając jedną rzecz, nie zepsuję innej. Plan obejmował zarówno samo rozwiązanie, jak i wytyczne AI zdefiniowane w projekcie.

Pierwsze PR-y

Pierwsze zgłoszenie dotyczyło maili z powiadomieniami — linki w wysyłanych wiadomościach były niepoprawne, gdy APP_URL było źle skonfigurowane. System używał ogólnego linku do panelu zamiast konkretnego adresu przypisanego do danego typu powiadomienia. Dodatkowo brak APP_URL skutkował wysyłaniem maili z uszkodzonymi linkami zamiast całkowitego zablokowania wysyłki.


Drugie zgłoszenie dotyczyło modułu schedulera działającego w domyślnej konfiguracji deweloperskiej (QUEUE_STRATEGY=local). Trzy problemy: kliknięcie „Run Now” zwracało ogólny błąd zamiast czytelnego komunikatu, strona szczegółów schedulera crashowała przy próbie pobrania danych niedostępnych w tej konfiguracji, a pole JSON w formularzach korzystało ze zwykłego textarea zamiast z dedykowanego komponentu dostępnego już w projekcie.


Warto wspomnieć o jednej świadomej decyzji: część zgłoszenia została celowo pominięta — analiza wykazała, że jej implementacja wymagałaby zmian architektonicznych wykraczających daleko poza zakres bugfixa. Zostało to udokumentowane w PR i zgłoszone jako osobna propozycja funkcjonalności. Uważam, że taka transparentność jest elementem dobrej kultury współpracy.

Zgodnie z dokumentacją projektu zacząłem od forka. Zanim otworzyłem PR do głównego repozytorium, przeprowadziłem wewnętrzny review z naszym zespołem. PR był dobrze opisany — problem, przyczyna, rozwiązanie — zgodnie z formatem wymaganym przez projekt. Co warte podkreślenia: nasz zespół nie miał wcześniejszej znajomości codebase, a mimo to dzięki szczegółowej dokumentacji kodu i funkcjonalności — wspieranej przez Claude — był w stanie szybko się wdrożyć, przeprowadzić sensowny review, odnieść się do proponowanej architektury i implementacji oraz wnieść realną wartość do procesu. Wewnętrzny feedback sprowadził się do jednego punktu: upewnić się, że poprawione funkcje nie wpływają na inne części systemu. Zająłem się tym i tego samego dnia uzyskałem wewnętrzną akceptację.

Tego samego dnia otworzyłem PR-y w oryginalnym repozytorium. Następnego dnia — zaakceptowane bez uwag. Oba zmergowane.

Do czego to się sprowadza

Wejście w nowy projekt, nowy framework, nową społeczność — brzmi jak dużo. Ale przy odpowiednim podejściu bariera wejścia jest znacznie niższa, niż się wydaje.

Kilka rzeczy, które pomogły:

• rozpoczęcie od zrozumienia projektu przed dotykaniem zgłoszeń,
  
• traktowanie testów jako dokumentacji,
  
• świadome używanie AI jako narzędzia do analizy i planowania zamiast generatora kodu,
  
• wybranie na start czegoś małego i dobrze zdefiniowanego.