Skip to content

CALIBER_LEARNINGS.md

Latest commit

 

History

History
25 lines (23 loc) · 7.37 KB

CALIBER_LEARNINGS.md

File metadata and controls

25 lines (23 loc) · 7.37 KB
Raw

Caliber Learnings

Accumulated patterns and anti-patterns from development sessions. Auto-managed by caliber — do not edit manually.

  • [gotcha:project] The existing test files (tests/EventTest.php, tests/IgnoredActionsThrowTest.php, tests/UnknownActionTest.php, tests/IgnoredEventTest.php) all reference IrcConverter and DiscordConverter classes that no longer exist in src/ — running vendor/bin/phpunit produces 61 errors about missing classes. These tests are stale and need to be rewritten against GithubWebhook directly.
  • [fix:project] vendor/bin/phpunit fails with "No such file or directory" if vendor/ is not present — always run composer install first. The vendor directory is gitignored and absent after a fresh clone.
  • [gotcha:project] composer.json has no autoload, autoload-dev, or scripts sections — there is no PSR-4 autoloader and no composer test shortcut. Classes (GithubWebhook, IgnoredEventException, etc.) are loaded via manual require statements. Tests must bootstrap these manually or via a PHPUnit bootstrap file.
  • [pattern:project] Real GitHub webhook payloads live in log/ as JSON files with structure {"repo": "...", "event": "...", "data": {...payload...}}. The data key holds the raw webhook payload — use these as authoritative source material when creating new fixtures under tests/events/.
  • [gotcha:project] In the push event handler, $Msg['alias'] is set from $Message['head_commit']['author']['name'] (commit author name), not $Message['pusher']['name']. These differ when CI or bots push commits authored by a human. Code that compares commit authors against the pusher must use $Msg['alias'], not $Message['pusher']['name'].
  • [fix:project] phpunit.xml must have bootstrap="tests/bootstrap.php" set — without it PHPUnit cannot load source classes since there is no PSR-4 autoloader. The bootstrap file manually requires all src/ classes.
  • [gotcha:project] composer.json now has a scripts section — composer test, composer analyse, composer cs-fix, and composer cs-check all work. The old stale learning about no scripts is now superseded.
  • [convention:project] Test fixture directories under tests/events/{event_name}/ now use 3 files: payload.json, type.txt, and expected_text.txt (plain text, no IRC color codes). The old 4-file format with expected.bin and discord.json was for the removed IrcConverter/DiscordConverter — do NOT create those files.
  • [pattern:project] GithubMessageBuilder (in src/GithubMessageBuilder.php) handles all message formatting. The switch ($EventType) block in web/github.php is now routing-only: call $Builder->build() before the switch, then each case just decides whether to call SendToChat or skip it. Do NOT rebuild $Msg inside individual cases.
  • [gotcha:project] release edited events have a changes key in the payload that is an empty array [] — GitHub does not populate what fields changed. There is no from/to data available for release edits; the message can only show the current release state, not what was modified.
  • [gotcha:project] status events (CI status from AppVeyor, Scrutinizer, Travis, etc.) are NOT ignored in the current codebase — they fall through to default: which emits a generic "triggered a status event" message. The payload has rich fields: state (success/failure/error/pending), description (CI message), context (CI service name), target_url (link to build), and commit.commit.message. Add a dedicated case 'status': handler in GithubMessageBuilder::buildText() to surface these fields.
  • [pattern:project] Real GitHub webhook payloads live in log/ as JSON files with structure {"repo": "...", "event": "...", "data": {...payload...}}. The data key holds the raw webhook payload — use these as authoritative source material when creating new fixtures under tests/events/. Why: payload.json files in tests/events use the unwrapped payload, not the wrapped log structure — extract data when copying. How to apply: when adding fixtures or analyzing past events, jq/python-extract the data key.
  • [gotcha:project] composer.json has a scripts section — composer test, composer analyse, composer cs-fix, and composer cs-check all work. The old stale learning about no scripts is superseded.
  • [convention:project] Test fixture directories under tests/events/{event_name}/ use 3 files: payload.json, type.txt, and expected_text.txt (plain text, no IRC color codes). The old 4-file format with expected.bin and discord.json was for the removed IrcConverter/DiscordConverter — do NOT create those files.
  • [pattern:project] GithubMessageBuilder (in src/GithubMessageBuilder.php) handles most message formatting via its buildText() switch, but new event types with rich payload fields (e.g. case 'status': for CI state/context/target_url) have been added directly to the switch ($EventType) block in web/github.php instead of the builder. Why: quick custom handlers can live in web/github.php without modifying the shared builder. How to apply: check both GithubMessageBuilder::buildText() AND the switch in web/github.php when looking for an event handler — adding to either is valid, but prefer the builder for consistency.
  • [gotcha:project] status events (CI status from AppVeyor, Scrutinizer, Travis, etc.) have a dedicated case 'status': handler in web/github.php that surfaces state, description, context, target_url, and commit.commit.message — they are NOT ignored despite the README/exception-handling docs claiming so. Both Webhook docstrings and the IgnoredEventException description still mention status as ignored, but it actually flows through to a custom handler.
  • [fix:project] vendor/bin/phpstan analyse fails with Constant GITHUB_WEBHOOKS_SECRET not found because src/config.php is gitignored. Fix: create phpstan-bootstrap.php that stubs the constant (if (!defined('GITHUB_WEBHOOKS_SECRET')) { define('GITHUB_WEBHOOKS_SECRET', ''); }) and reference it from phpstan.neon via bootstrapFiles: - phpstan-bootstrap.php. Without this, every PHPStan run fails on a fresh checkout.
  • [gotcha:project] The actual class in src/GithubWebhook.php is named GithubWebhook (capital G, lowercase rest until W), but web/github.php and web/github-old.php historically called new GitHubWebHook() (mixed case). PHPStan's class-case check flags this as Class GithubWebhook referenced with incorrect case: GitHubWebHook. Always use new GithubWebhook() to match the class declaration exactly — PHP itself is case-insensitive for classes but PHPStan is not.
  • [gotcha:project] The repo's PHPStan is pinned to phpstan/phpstan: ^0.12.53 (very old, last updated Sep 2021). Output spews PHP Deprecated: Return type of ... jsonSerialize() should ... warnings on every run — filter them with vendor/bin/phpstan analyse 2>&1 | grep -v "Deprecated\|deprecated\|ReturnTypeWillChange\|phpstan.phar" to see only real errors.
  • [gotcha:project] SendToChat() in web/github.php uses an uninitialized $Code variable when neither $useRC nor $useTeams are true — PHPStan flags Variable $Code might not be defined. Initialize $Code = 0; at the top of SendToChat() before the conditional curl blocks.