EOS

Update Philosophy

The project follows the same philosophy as AdonisJS itself: this is a full application, not a plugin. That means the codebase is expected to be owned and maintained by your engineering team over time.

No In-App “Update Core” Button

There is intentionally no built-in CMS UI for updating the core. Updates are applied the same way you would update any other AdonisJS app:

  • Review upstream changes (AdonisJS, dependencies, and this repo if you forked it).

  • Apply updates via npm/pnpm and Git.

  • Run migrations, tests, and smoke tests.

  • Deploy through your existing CI/CD pipeline.

This keeps the operational model simple and predictable, and avoids surprising changes being pushed into production without review.

Sync-Safe Strategy (Core vs. Instance)

To ensure that your instance-specific customizations are not lost during core updates, we use a marker-based convention. This allows both human developers and AI agents to distinguish between "Core" logic and "Instance" customizations.

1. Making Instance-Specific Edits

When modifying existing core files (such as Models, Controllers, or PostType configurations) for a specific project instance, you must wrap your changes in markers.

Step-by-Step:

  1. Identify the file: Determine if it's a core file (e.g., app/models/post.ts) or an instance-only file (e.g., a new custom controller).

  2. Add markers: Wrap your new or modified code in @custom-start and @custom-end comments.

  3. Provide context: Optionally include a short reason or task name in the start marker.

Example (adding a custom field to a Post Model):

typescript 
export default class Post extends BaseModel {
  // ... core fields ...

  // @custom-start [Add instance-specific 'internalNote' field]
  @column()
  declare internalNote: string | null
  // @custom-end

  // ... rest of core model ...
}

2. Updating an Instance with Core Changes

When a new version of the upstream core is released, you can sync the changes into your instance.

Step-by-Step:

  1. Ensure a clean state: Commit or stash any pending changes in your instance.

  2. Run the sync script:

    bash 
    # Sync latest stable version from the core
node ace core:sync

# Sync latest beta tag
node ace core:sync --beta

# Sync latest beta branch
node ace core:sync beta

# Sync a specific version or tag
node ace core:sync v0.5.0

  3. Review the incoming changes: The command will pull core updates via git subtree. Git will attempt to auto-merge core changes with your marked instance changes.

3. Managing Conflicts

If the core update modifies the same lines you customized, a merge conflict will occur.

Step-by-Step:

  1. Check for conflicts: Run git status to identify conflicted files (marked as both modified).

  2. Open the conflicted file: Look for the standard Git conflict markers (<<<<<<<, =======, >>>>>>>).

  3. Resolve the conflict:

    • Prioritize markers: If the conflict is inside or adjacent to your @custom-start blocks, ensure your instance-specific logic is preserved.

    • Update core logic: If the core update introduced important security fixes or performance improvements, integrate them around your custom blocks.

  4. Mark as resolved: Once fixed, run git add <file> and then git commit.

Recommended Upgrade Approach

  • Maintain staging and production environments; apply upgrades to staging first.

  • Pin dependency versions and bump them intentionally with a short review of release notes.

  • Keep a simple upgrade runbook:

    1. Pull latest changes from your main branch or upstream.

    2. Update dependencies (npm install, npm outdated, deliberate bumps).

    3. Run migrations in a safe environment.

    4. Run automated tests and smoke tests.

    5. Deploy to staging, verify, then promote to production.

Syncing Fixes from the Starter Repository

The recommended approach for syncing bug fixes uses Git Subtree Merge.

How It Works

The sync command uses git subtree pull to merge changes from the core repository into your project. This approach:

  • Preserves your project's git history.

  • Allows selective syncing (you choose when to pull).

  • Shows you exactly what changed before applying.

  • Handles conflicts gracefully (you resolve them manually using the marker strategy).

Alternative: Manual Git Subtree

If you prefer to run the git commands manually:

bash 
# Add core as remote (first time only)
git remote add core https://github.com/spaced-man/adonis-eos-starter.git

# Fetch latest
git fetch core

# Merge specific version
git subtree pull --prefix=. core main --squash -m "Sync fixes from core"