Keeping Merges Clean

A kit update merges cleanly or it doesn't, almost entirely based on decisions you made while building your product, not decisions the kit's authors made while shipping the update. Three habits keep the merge painless.

Don't edit the plumbing in place

Extend through the documented seams instead of modifying kit files directly: add a new integration in app/adapters/, add a new feature by copying the example slice's shape rather than editing it, add configuration rather than rewriting an initializer's internals. A kit file you never touched merges cleanly by definition; there's nothing for git to reconcile. See The Adapter+Fake Pattern and Adding a Resource for the seams themselves.

Keep your product code in clearly separate files

Your own models, controllers, and views, living in files the kit itself never touches, rarely conflict with an incoming update no matter how much the kit changes elsewhere. The risk isn't in adding new files; it's in editing shared ones.

Expect conflicts to concentrate in files you customized

The landing page, the design tokens, app_identity.rb: these are exactly the files Making It Yours told you to edit, and they're also the files most likely to see a conflict on a future merge, since both you and a kit update might touch the same lines. That's expected, not a sign something went wrong. Resolve those by hand, favoring your own product-specific values, and the rest of the merge fast-forwards without any intervention.

Next

See where kit changes are actually documented: Release Notes.