Master Genesis Laravel Package

Technical Evaluation

Evidence base is thin — treat this as a risk-flagged provisional review. The only artefact supplied for v2.0.3 is a changelog link (1.0.6...v2.0.3) with no enumerated changes, no migration guide, and no deprecation notices. The assessment below is therefore driven almost entirely by one high-confidence signal: a major-version jump from 1.0.6 to 2.0.3.

Architecture fit

• medigeneit/master-genesis is a Laravel package; adoption hinges on whether it plugs in via a service provider and config publish (php artisan vendor:publish) or imposes its own conventions on models, migrations, or directory layout. Unverified.
• The 1.x → 2.x boundary is the point where packages typically change their extension points (interfaces, base classes, published config keys, migration stubs). Any of these breaks downstream customisations, not just the package itself.
• Fit cannot be confirmed until we know whether v2 requires a minimum Laravel/PHP version above our floor.

Integration feasibility

• Feasible to evaluate cheaply: install into a throwaway Laravel app, publish assets, diff the published config and stubs against our 1.0.6 baseline. This is a half-day spike, not a project.
• Infeasible to commit on the current evidence — no changelog body, no upgrade notes, no stated support window.

Technical risk (ranked)

1. Silent breaking changes. A 1.x → 2.x bump with an empty changelog body is the worst-case signal: we know something broke, not what. Highest risk.
2. Skipped intermediate versions. Jumping 1.0.6 → 2.0.3 folds two majors (and 2.0.0–2.0.2 patches) into one hop. If we are on 1.0.6, there is no incremental path.
3. Maintainer/bus factor. Single-vendor namespace (medigeneit); release cadence and responsiveness unknown. A major bump with no notes is mild evidence of low release discipline.
4. Patch churn post-major. Already at 2.0.3 — three patches after a major suggests v2.0.0 shipped rough. Budget for instability.
5. Ecosystem lag. Third-party docs, tutorials, and Stack Overflow answers will still describe 1.x. Support cost shifts onto us.

Key questions for the maintainer / spike

• What is the full 1.0.6 → 2.0.3 change list, and which entries are breaking?
• Is there an upgrade guide, and does a codemod or Rector rule exist?
• Minimum PHP and Laravel versions for v2; is 1.x still receiving security fixes, and until when?
• Are published config keys, migration stubs, and public interfaces renamed or removed?
• Is the repo actively maintained (commit cadence, issue response, tagged releases with notes)?

Integration Approach

Stack fit

• Presumed compatible with a standard Laravel app; unconfirmed for our specific PHP/Laravel versions. Verify before any design work — a version-floor mismatch ends the evaluation immediately.
• If the package is scaffolding/codegen rather than runtime, integration risk concentrates in build-time artefacts (generated files, stubs) rather than production request paths. That is a meaningfully cheaper failure mode — generated code can be reviewed and hand-corrected.

Migration path

• Baseline first: pin and document our current 1.0.6 usage — which published config keys, stubs, and extension points we actually depend on. Without this inventory we cannot scope the 2.x delta.
• Branch, don't merge: attempt the upgrade on a disposable branch against a scratch database. Publish v2 assets to a temp directory and diff against v1 output.
• No incremental route exists. We cannot stage through 2.0.0 → 2.0.3 meaningfully; treat the hop as atomic.
• Exit criteria: if the upgrade guide is absent and the config/stub diff is materially large, do not migrate. Stay on 1.0.6 with a documented pin and revisit when notes are published.

Compatibility

• Lockfile pinning is the immediate control: constrain to ^1.0 in composer.json so no environment silently resolves to 2.x. Do this now, before anything else.
• Check transitive constraints — a v2 that raises illuminate/* requirements can force a framework upgrade we did not plan.
• If we have forked or extended package internals (overridden base classes, subclassed generators), assume breakage until proven otherwise.

Sequencing

1. Pin to ^1.0 across all environments (today, low effort, immediate risk reduction).
2. Request the changelog body and upgrade guide from the maintainer; open an issue if none exists.
3. Timeboxed spike: install v2 in a scratch app, diff published artefacts, confirm PHP/Laravel floors.
4. Decide: migrate / defer / replace. Record the decision and the pin.
5. If migrating — one non-production environment first, generated artefacts reviewed by hand, then promote.

Operational Impact

Maintenance

• Low ongoing burden if the package is build-time only; moderate-to-high if it is runtime and we depend on its conventions.
• A maintainer who ships a major with a bare changelog link tends to under-document. Assume we will be reading source to answer our own questions, and budget accordingly.
• Expect to carry our own upgrade notes internally — do not rely on upstream documentation.

Support

• Internal, not vendor. Single-namespace packages rarely offer commercial support; escalation path is GitHub issues with unknown SLA.
• If the project stalls, we own the fork. Assess now whether the codebase is small enough to fork comfortably — this is the decisive question for whether the dependency is acceptable at all.

Scaling

• If build-time/scaffolding: effectively no runtime scaling concern.
• If runtime (query builders, generators invoked per-request, caching layers): profile before relying on it. Unverified.
• The real scaling constraint is organisational — how many teams adopt it and how many inherit the 1.x/2.x split. Version fragmentation across teams is the likely scaling failure, not throughput.

Failure modes

• Silent resolution to 2.x on a fresh composer install where the constraint is loose. Mitigated by the pin in step 1.
• Half-migrated state: some services on 1.x, others on 2.x, shared config assumptions. Avoid by treating migration as all-or-nothing per environment.
• Generated-code drift: v1-generated artefacts left in the repo after a v2 upgrade, diverging from new stubs. Requires an explicit regenerate-and-review pass.
• Abandonment: repo goes quiet mid-migration. Detectable via commit cadence during the spike; the mitigation is forkability.
• Patch-regression churn: 2.0.3 arriving shortly after 2.0.0 suggests instability. Pin to an exact patch version in production, not a floating ^2.0.

Ramp-up

• Engineer spike: ~0.5 day to establish version floors and diff published artefacts.
• Full migration effort: not estimable without the changelog body and an inventory of our 1.0.6 dependencies. Do not commit a date.
• Documentation and team enablement: minimal if build-time, 1–2 days if runtime and conventions change.

TPM recommendation: Do not adopt v2.0.3 on current evidence. Pin to ^1.0 immediately, request the change list from the maintainer, and run the half-day spike. Re-assess when — and only when — a real changelog and upgrade guide exist.