Nova Help Laravel Package

Technical Evaluation

Architecture fit clevyr/nova-help is a Nova tool package — it slots into the existing Nova service-provider/tool registration model rather than introducing a parallel extension mechanism. That is a good architectural fit for any application already running Nova: no new runtime, no new datastore, no separate auth surface. It is additive UI (in-panel help/documentation) rather than a change to domain logic, so blast radius is inherently small.

The v3.0.0 change is almost entirely a platform-coupling decision: the package now tracks Nova 5 exclusively. That is fine architecturally but it converts a low-risk peripheral dependency into a hard constraint on the Nova major version of every consuming application.

Integration feasibility Low effort if the host application is already on Nova 5. For Nova 4 estates the work is not "integrate the package" — it is "upgrade Nova," which is a materially larger programme with its own Laravel version floor, asset pipeline changes, and third-party tool compatibility review.

The "minimal footprint" build is a genuine, if modest, positive: a smaller asset payload for an admin panel is a small win on page weight and build times, and it suggests the maintainer is actively trimming rather than accumulating.

Technical risk

• Hard version gate. No dual-support branch. Applications on Nova 4 cannot take v3.0.0 patches, including any future security or bug fixes. This splits the user base and puts v2.x on an implicit maintenance-only track.
• Thin release signal. The notes describe one PR and a breaking constraint; they do not state whether the tool's public API (tool class, config keys, publishable assets, markdown source configuration) changed. Absence of evidence is not evidence of absence — must verify.
• Single-maintainer concentration. One new contributor and a small PR surface. Bus factor and long-term maintenance cadence are unproven.
• Transitive exposure. Nova itself is commercial and licensed; the package's support window is now chained to Clevyr's responsiveness to Nova 6 and to Nova's own release cadence.

Key questions

1. Does v3.0.0 change the tool's public surface — class names, config file keys, published asset paths, markdown source location?
2. Is v2.x formally end-of-life, or will it receive bug/security fixes for a defined window? What is that window?
3. Does Nova 5 impose a Laravel/PHP floor that our target application does not currently meet?
4. Is the "minimal footprint" build a behavioural change (lazy-loaded assets, changed publish tags) or purely a bundle-size reduction?
5. Which other Nova tools and custom Nova components in our estate are pinned to Nova 4?

Integration Approach

Stack fit Requires a commercial Nova 5 licence and the Laravel/PHP versions Nova 5 supports. Confirm our application's Laravel and PHP versions clear that floor before scoping anything. If we are on Nova 4, this package is not adoptable until Nova itself is upgraded — sequencing must respect that dependency, not the package's.

Migration path

• Greenfield / already on Nova 5: install ^3.0 directly. Treat as a new integration, not a migration.
• On Nova 4: stay on ^2.0 and pin explicitly in composer.json. Do not allow a floating constraint to pull v3.0.0 into a Nova 4 application — the failure mode is a boot-time class/contract error in the admin panel, which is loud but disruptive. Add an explicit constraint and, if warranted, a Composer conflict rule.
• Planning a Nova 5 upgrade: sequence the Nova upgrade first, validate existing tools, then take nova-help ^3.0 as a trailing, low-risk step. Do not bundle the package bump into the Nova upgrade PR — keep it as an independent, revertable change.

Compatibility Verify the package's declared constraints against our composer.json before merge. Check whether any config or published file needs republishing after the major bump (run the publish command into a scratch path and diff against the current published copy rather than overwriting in place).

Sequencing

1. Confirm Nova major version and licence status per application.
2. Diff published assets/config between v2.x and v3.0.0 in a branch.
3. Upgrade in a non-production environment; smoke-test the help panel render and markdown sourcing.
4. Update the version pin and document the Nova 5 precondition in the repo's dependency notes.
5. Only then retire any v2.x-specific workarounds.

Operational Impact

Maintenance Low ongoing maintenance for a UI-only tool — no migrations, no background jobs, no external services. The real maintenance cost is the coupled upgrade cadence: every Nova major will now gate a nova-help major. Budget for this as a recurring line item rather than a one-off. Note that ^3.0 currently has a one-release history; expect early-patch churn.

Support Support is community/upstream only — no vendor SLA. For a help/documentation panel the acceptable-downtime bar is low, but the failure visibility is high: it lives inside the admin panel, so a break is immediately visible to internal staff. Have a documented rollback (pin back to a known-good version) and confirm the tool can be disabled via config/nova.php tool registration without a full deploy.

Scaling Effectively a non-issue. Static content rendered on demand; no data volume, no concurrency concerns. The minimal-footprint build marginally improves admin panel load, which matters only at large internal user counts and even then trivially.

Failure modes

• Composer resolves v3.0.0 into a Nova 4 app → Nova boot error, admin panel unavailable to staff. Mitigate with an explicit ^2.0 or ^3.0 pin and CI composer validate.
• Unpublished/mismatched assets after major bump → help panel renders blank or unstyled. Mitigate by diffing published output before deploy.
• Config key rename → help content silently missing. Mitigate by asserting panel content in a smoke test, not just an HTTP 200.
• Upstream abandonment or slow Nova 6 support → forced pin to an ageing version. Mitigate by evaluating whether the same outcome is achievable with a Nova custom page/resource, and keeping that as a fallback.
• v2.x left unpatched → any future defect fix is unavailable to Nova 4 consumers. Track explicitly as accepted risk.

Ramp-up Near-zero for a Laravel developer familiar with Nova tools — install, publish, register, populate markdown. Half a day including verification. The ramp-up cost sits with the Nova 5 upgrade, not with this package; that is a multi-sprint effort owned by the platform team, and this package should be treated as a passenger on that work rather than a driver of it.

Recommendation: adopt ^3.0 where Nova 5 is already in place — the change is small, the footprint improvement is real, and the operational burden is negligible. Where Nova 4 is still in production, pin ^2.0, record the constraint, and revisit only when the Nova upgrade is scheduled. Do not let this package's major version become the reason a Nova upgrade gets pulled forward.