Skip to content

UPDATING.md

Latest commit

 

History

History
210 lines (144 loc) · 5.35 KB

UPDATING.md

File metadata and controls

210 lines (144 loc) · 5.35 KB

receive Updates

You can update your project from the starter-kit (merge a tagged release)

This guide explains a safe, repeatable workflow for fetching a specific tagged release from the starter-kit (for example v0.1.0 - Latest) and merging it into your project.

Assumption: you started your project from the starter-kit and added the starter-kit repo as the upstream remote:

git remote -v
origin    https://github.com/you/your-app.git (fetch)
upstream  https://github.com/devsbuddy/laravel-react-starter-kit.git (fetch)

Quick checklist (before you start)

  1. Commit or stash all local changes on your project. Never merge while you have uncommitted work.
  2. Create a backup branch (optional but recommended):
git checkout main
git checkout -b backup-before-update-$(date +%Y%m%d)
git push origin HEAD
# switch back to your working branch, e.g. main
git checkout main
  1. Make sure your local main (or primary branch) is up-to-date with your remote origin:
git pull origin main

Step-by-step: fetch the tag and merge it safely

Below are two safe options. Use Option A if your project shares history with the starter-kit (the usual case when you used the repo as a template). Use Option B if you prefer to create a temporary branch and test the merge before applying it to your main branch.

Option A — direct merge (fast & common)

  1. Fetch tags from upstream:
git fetch upstream --tags
  1. Verify the tag exists locally:
git tag --list | grep v0.1.0
  1. Ensure you are on your local main (or your app's primary branch):
git checkout main
git pull origin main
  1. Merge the tag into main:
git merge --no-ff v0.1.0 -m "Merge upstream v0.1.0"
  • If Git performs a fast-forward merge it will simply move your branch pointer.
  • If there are conflicts, Git will stop and you must resolve them. See Resolving conflicts below.
  1. Run project update steps (see Post-merge checklist). Then push the result to your origin:
git push origin main

Option B — test-first: merge in a temporary branch (recommended for bigger updates)

  1. Fetch tags:
git fetch upstream --tags
  1. Create a temporary branch from your up-to-date main:
git checkout main
git pull origin main
git checkout -b upstream-merge-v0.1.0
  1. Merge the tag into the temporary branch:
git merge --no-ff v0.1.0 -m "Merge upstream v0.1.0 (test)"

  1. Resolve conflicts if any (see below). Run your tests and local checks.

  2. If everything looks good, switch back to main and merge the temporary branch:

git checkout main
git merge --no-ff upstream-merge-v0.1.0 -m "Apply upstream v0.1.0 merge"
git push origin main
  1. Delete the temporary branch locally and remotely (optional):
git branch -d upstream-merge-v0.1.0
# if you pushed it upstream and want to delete on remote:
# git push origin --delete upstream-merge-v0.1.0

Resolving conflicts

If Git reports conflicts during the merge:

  1. Open each conflicted file and look for conflict markers <<<<<<<, =======, >>>>>>>.
  2. Decide how to reconcile changes: keep your version, take upstream changes, or combine them.
  3. After resolving all files:
git add <resolved-files>
git commit --no-edit
  1. Re-run your local checks/tests and the Post-merge checklist.

Tip: If the conflicts are numerous and complex, consider doing a git merge --abort and performing a manual three-way merge approach, or use a visual merge tool (VSCode, Meld, Beyond Compare, etc.).

Post-merge checklist (run after a successful merge)

  1. Composer dependencies — If the starter-kit changed composer.json:
composer install
composer dump-autoload
  1. Node packages / build — If package.json or frontend assets changed:
# if you use npm
npm install
npm run dev
# or yarn/pnpm equivalents
  1. Migrations — If the update added or changed migrations:
php artisan migrate
# If migrations are destructive, inspect them first or run in a safe environment

  1. Config / env — Check config/* and .env.example for new keys. Merge them into your .env carefully.

  2. Clear caches:

php artisan config:clear
php artisan cache:clear
php artisan view:clear
php artisan route:clear
  1. Run tests & manual QA — Run your test suite and smoke-test the app locally.

When histories are unrelated (rare edge-case)

If your repository and the starter-kit do not share common commit history (Git will warn about unrelated histories), merging a tag may fail. In that case:

  • Consider copying the specific files you need from the starter-kit release into your project manually.
  • Or use git format-patch / git am from the upstream to apply a sequence of commits.

Helpful commands summary

# 1. Fetch upstream tags
git fetch upstream --tags

# 2. Test-first approach
git checkout main && git pull origin main
git checkout -b upstream-merge-v0.1.0
git merge --no-ff v0.1.0 -m "Merge upstream v0.1.0 (test)"
# resolve conflicts, run tests, then
git checkout main
git merge --no-ff upstream-merge-v0.1.0
git push origin main

# 3. Direct merge approach
git checkout main && git pull origin main
git merge --no-ff v0.1.0 -m "Merge upstream v0.1.0"
# resolve conflicts, run post-merge tasks, then
git push origin main