EOS

Sync-Safe How-To Guide

This guide provides practical steps for maintaining a project instance while staying compatible with upstream core updates.

For Developers & AI Agents

1. Making a Change (Instance Mode)

When you need to modify a file that exists in the core repository:

  1. Open the file (e.g., app/controllers/posts/posts_crud_controller.ts).

  2. Add your logic using the markers:

    typescript 
    // @custom-start [Task: Custom Redirect after Update]
return response.redirect().toPath('/custom-success-page')
// @custom-end

  3. Verify that the file still passes linting and tests.

Note for AI Agents: Unless you see the Core: prefix in the user's request, you MUST use these markers for all modifications to core files.

2. Contributing to Core (Core Mode)

If you are a core maintainer or fixing a bug that should be shared with all users:

  1. Prefix your request with Core: when talking to AI agents.

  2. Make the change directly without markers.

  3. Test thoroughly, as this change will affect all downstream projects.

For System Administrators

1. Syncing from Upstream

To bring in the latest features and security fixes from the upstream core:

bash 
# 1. Ensure clean git status
git status

# 2. Run the sync command
node ace core:sync (Latest stable)
node ace core:sync --beta (Latest beta tag)
node ace core:sync beta (Latest beta branch)
node ace core:sync v0.5.0 (Specific version)

2. Handling Merge Conflicts

If you see CONFLICT (content): Merge conflict in [filename]:

  1. Open the file in your editor.

  2. Locate your @custom-start block.

  3. If Git placed conflict markers (<<<<<<<) around it, verify if the new core code should replace, complement, or be ignored in favor of your custom code.

  4. Resolve:

    • Keep your code within the markers.

    • Accept relevant core changes outside the markers.

  5. Finish:

    bash 
    git add [filename]
git commit -m "chore: resolve core sync conflicts"

Best Practices

  • Atomic Blocks: Keep your @custom-start blocks as small as possible. Wrapping an entire function is harder to merge than wrapping a single line or a small block.

  • Task Names: Use descriptive task names in markers to help future developers (or yourself) understand why the customization exists.

  • Don't Marker New Files: If you create a file that doesn't exist in the core repo, don't use markers. It's implicitly "yours."