🔃Updating your project

How to Update Your LightningRails Project

This guide shows you how to safely update your existing LightningRails project to get the latest features, bug fixes, and improvements.

You can decide to update the whole project with our Update Script, or cherry-pick specific Pull requests.

📋 Prerequisites

Before you start, make sure you have:

• ✅ A clean git working directory (commit or stash your changes)

• ✅ A backup of your project (or be on a feature branch)

• ✅ 5-10 minutes of time

• ✅ Basic familiarity with git commands

📃 UPDATE SCRIPT (Heavy conflicts resotution)

🚨 For Projects Before v1.5.0 (Before July 2025)

If your LightningRails project was created before v1.5.0, you won't have the update script yet. Don't worry - we'll get you set up!

Option 1: Download the Script (Recommended)

From your project's root directory

# Make generators directory
mkdir generators

# One-time setup per user
gh auth login

# Fetch the update file and add it to your folder
gh api repos/LightningRails/lightning-rails/contents/generators/update_project.sh \
  --jq '.content' | base64 -d > generators/update_project.sh

# Commit this change
ga . && gc -m "Added generator folder"

# You're ready to go!
bash generators/update_project.sh

🚀 How to Use the Update Script

Step 1: Choose to Apply Updates

When prompted, choose option 1 to apply all updates.

Step 3: Resolve Conflicts (If Any)

If you get merge conflicts, here's the general rule of thumb:

📁 For View Files (your customizations):

• Keep YOUR CURRENT changes in app/views/ files

• These contain your branding and custom content

⚙️ For Config Files (framework updates):

• Keep Most INCOMING changes in config/ files

• These contain important framework updates

🔍 Always check case by case - don't blindly accept all changes from either side.

Step 4: Complete the Update

After resolving conflicts, commit the merge

git commit -m "Update: Merge latest LightningRails improvements"

Install any new dependencies

bundle install

Run any new migrations

rails db:migrate

Test your application

dev

🍒 Cherry picking specific PRs

If you don't want to update the whole project, but bring a specific PR to your project.

1. Add the Lightning Rails repo as a remote:

git remote add lightning-rails https://github.com/LightningRails/lightning-rails.git
git fetch lightning-rails

1. Find the commit(s) in the PR:

From the PR page: https://github.com/LightningRails/lightning-rails/pull/128 At the time of writing, the main commit is likely something like:

# Example (replace with actual commit SHA from the PR)
git cherry-pick abcdef1234567890

You can see this by clicking the “Commits” tab in the PR and grabbing the SHA(s).

1. Resolve any conflicts and commit the changes.

2. Remove the remote (optional):

git remote remove lightning-rails

🆘 Quick Troubleshooting

If something breaks after updating:

Return to your backup

git checkout backup-before-update-[timestamp]

If you're unsure about a conflict:

• When in doubt, keep your current changes for anything customer-facing

• Keep incoming changes for technical/framework files

💡 Pro Tips

• Update regularly - smaller, frequent updates are easier than big ones

• Test immediately - catch issues early

• Update during low-traffic times - be safe with production updates

That's it! The script handles the complex parts - you just need to make smart decisions about which changes to keep.

---

Remember: Your customizations in views are precious - protect them. Framework updates in config files are usually safe to accept.

Happy updating!