Getting Started

Install the package with composer require relaticle/comments, then publish and run its migrations (php artisan vendor:publish --tag="comments-migrations" and php artisan migrate). Check the package config file after publishing — it is where the commenter model, key type, and mention behavior are wired up.
The first use case to reach for is attaching comments to an existing Eloquent model (e.g. a Post or Ticket). Add the package's commentable trait to that model and you get a comments() relation you can render and create against.
v1.1.1 is a patch release; treat it as the current baseline. The only functional change is a fix for mention IDs being dropped when the commenter model uses ULID/UUID keys — relevant if your User/author model does not use auto-incrementing integers.
Look first at: the published config (commenter + key settings), the migration stubs (nullable commenter/morph columns), and the trait on your commentable model. These three drive most day-to-day behavior.

Implementation Patterns

Morph commenting: Attach the trait to any model you want commentable. Use the morph relation for listing and $model->comments()->create([...]) for writes; keep the commenter resolved from the authenticated user in a controller/action rather than scattering it in views.
Threaded replies / mentions: If your UI supports @-mentions, resolve mentioned users server-side and pass IDs through the package's expected input. The v1.1.1 fix confirms mentions are keyed off the commenter's primary key — so make sure the IDs you pass match your actual key type (ULID/UUID strings, not integers).
ULID/UUID projects: If your author/commenter model uses HasUuids/HasUlids, upgrade to at least v1.1.1 so mention IDs persist correctly. This is the main reason to bump from v1.1.
Authorization: Wrap creation/deletion in policies or gates. The package stores comments; enforcement of "who can comment on what" is your application's responsibility, typically via a form request + policy check before calling the create action.
Rendering: Eager-load comments.commenter (and reply relations if used) on the commentable model to avoid N+1 when displaying threads. Sanitize rendered comment bodies since they contain user input, including mention tokens.

Key-type mismatch is the classic pitfall. The v1.1.1 bug — mention IDs dropped for ULID/UUID commenter keys — bites projects with non-integer authors. Verify mention round-tripping with a ULID/UUID user after upgrading, and ensure any mention IDs passed from the frontend are strings, not cast to int.
Morph map consistency: If you use Relation::enforceMorphMap(), the morph alias stored on comments must match what you registered. Changing an alias later silently orphans existing comments — decide the alias early.
Config after publish: The package config is published once; later package updates may add new keys that won't appear in your existing published copy. Diff the vendor config against yours after upgrades.
Debugging dropped mentions: If mention IDs vanish, check (1) the commenter model's key type in config, (2) that your form/request isn't casting IDs to integers, and (3) that the commenter records actually exist before persisting.
Extension points: Prefer decorating via your own action/service classes and model observers over editing vendor files, so patch upgrades like v1.1.1 apply cleanly. Keep an eye on the changelog for behavior changes in mention parsing given this is the actively-fixed area.