Prispievanie

Pull requesty sú vítané v tomaj/hermes. Pravidlá projektu sú v CONTRIBUTING.md. Táto stránka sa s týmto súborom zhoduje. Účasť sa riadi kódexom správania.

Zmeny, ktoré vieme zlúčiť

• Dodržiavajte PER Coding Style. composer phpcs kontroluje src, tests a examples.
• Ku každej zmene správania pridajte testy.
• Zmeny správania zdokumentujte v README.md, CHANGELOG.md a v tejto príručke (v angličtine aj v slovenčine pod docs/sk/). Príklady držte na signatúrach v src/ a opisujte, čo tento kód robí, nie plánovanú neskoršiu verziu. Kam patrí neskoršia verzia, hovorí Verzie dokumentácie.
• Sémantické verzovanie. Aktuálna stabilná rada je 6.x. Nekompatibilné zmeny čakajú na ďalšiu hlavnú verziu.
• Jeden pull request na zmenu, z feature vetvy. Neotvárajte ho z master.

Kontroly

composer install
composer phpunit
composer phpcs
composer phpstan
composer rector

Integračné testy komunikujú so skutočnými brokermi a preskočia sa, ak nie je nastavená ich premenná: HERMES_TEST_REDIS (tcp://127.0.0.1:6379), HERMES_TEST_RABBITMQ (host, port 5672, používateľ guest), HERMES_TEST_SQS (SQS endpoint, napríklad moto na http://127.0.0.1:4566) a HERMES_TEST_KAFKA (bootstrap servery, 127.0.0.1:9092; Kafka testy potrebujú aj ext-rdkafka). S HERMES_REQUIRE_SERVICES=1 chýbajúci alebo nedostupný broker test zlyhá namiesto preskočenia. compose.yaml spustí rovnaké verzie brokerov ako CI a composer test:integration nastaví všetkých päť premenných:

docker compose up -d --wait
composer test:integration

composer phpunit a composer test:integration vypínajú Xdebug a nezbierajú coverage, takže lokálny Xdebug v predvolenom režime develop beh nespomalí ani nezhodí. composer coverage a composer infection coverage zapnú, keď ho potrebujete.

Pokrytie:

composer coverage

GitHub Actions spúšťa PHPUnit s Redisom, RabbitMQ, moto (SQS) a Kafka na PHP 8.4, 8.4 s najnižšími závislosťami a 8.5 (s kontrolou 95 % coverage), takže sa nepreskočí žiadny integračný test. Beží aj nočný build PHP 8.6, ale jeho zlyhanie nezhodí workflow. CI ďalej spúšťa štýl kódu, Rector, PHPStan na úrovni max, composer audit, Infection, CodeQL, OpenSSF Scorecard a kontroly diagramov a odkazov v dokumentácii.

Diagramy

Ručne kreslené diagramy sa generujú. SVG súbory needitujte ručne.

• Zdroj je docs/diagrams/<name>.json: ručne rozmiestnený zoznam tvarov, textov, šípok a malých ikon s presnými súradnicami.
• npm run diagrams v docs/ premení každý zdroj na scénu Excalidraw (docs/diagrams/<name>.excalidraw) a na docs/public/diagrams/<name>-light.svg a <name>-dark.svg. Ručne písaný font Excalifont je vložený v každom SVG.
• Stránka zobrazí diagram cez <Diagram name="<name>" alt="Čo diagram ukazuje" />. Svetlý alebo tmavý súbor sa riadi témou stránky. Stránka ho zobrazí najviac 420 pixelov vysoký a kliknutie ho otvorí na celú obrazovku.
• Skript potrebuje Chrome alebo Chromium. Ak je nainštalovaný na nezvyčajnom mieste, nastavte CHROME_PATH.
• Commitnite zdroj aj všetky tri vygenerované súbory. npm run docs:links (kontrola dokumentácie v CI) najprv spustí npm run diagrams:check a zlyhá, keď nie sú aktuálne.

cd docs
npm ci
npm run diagrams

Súbor .excalidraw sa dá otvoriť na excalidraw.com na prezretie diagramu, ale zmeny urobené tam sa pri ďalšom behu prepíšu. Namiesto toho zmeňte zdroj .json.

Vydania

Tag verzie (6.0.0, bez prefixu v) spustí workflow vydania: vezme poznámky k vydaniu zo sekcie danej verzie v CHANGELOG.md, zostaví archívy zdrojového kódu, overí pôvod ich zostavenia a publikuje vydanie na GitHube. Kroky sú v RELEASING.md.

Bezpečnosť

Pre zraniteľnosť neotvárajte verejné issue. Použite súkromné hlásenie zraniteľností alebo, ak formulár nie je dostupný, e-mail tomasmajer@gmail.com. Podporované verzie sú v SECURITY.md. 6.x je podporovaná rada; 5.x dostáva len bezpečnostné opravy, do 2027-04-19.

Licencia

Príspevky sú pod licenciou MIT.

Časté otázky

Ktoré kontroly musia prejsť?

PHPUnit (so všetkými integračnými testami), PHP-CS-Fixer, PHPStan na úrovni max, Rector, composer audit, Infection a kontroly diagramov a odkazov v dokumentácii.

Ako zmeniť diagram?

Upravte docs/diagrams/<name>.json, spustite npm run diagrams v docs/ a commitnite zdroj aj tri vygenerované súbory.

Môžem zdokumentovať plánovanú funkciu neskoršej hlavnej verzie?

Na týchto stránkach nie: opisujú kód v src/. Pozrite Verzie dokumentácie.

Z ktorej vetvy má pull request prísť?

Z feature vetvy, jedna zmena na pull request.

Ako sa publikuje vydanie?

Pushnutím tagu verzie. Workflow vydania publikuje vydanie na GitHube s overenými archívmi; pozrite RELEASING.md.

Kde si pozriem náhľad dokumentácie?

Spustite npm run docs:dev v docs/.