Pull Updates

Keep your Plainform project up to date with the latest features and fixes

Plainform periodically releases updates with new features, bug fixes, and improvements. This guide shows you how to safely sync your project with the upstream repository while preserving your customizations.

Always pull updates into a new branch first to avoid disrupting your main codebase. This allows you to test changes before merging.

Prerequisites

  • Git installed and configured
  • Your Plainform project initialized as a Git repository
  • Your custom code committed to your own repository
  • Working tree clean before starting (git status shows no uncommitted changes)
  • Basic understanding of Git branching and merging

Overview

Keeping your project synchronized with upstream updates ensures you benefit from the latest improvements while maintaining your custom features. The process involves adding the upstream repository as a remote, fetching updates, resolving any conflicts, and merging changes into your main branch.

Step-by-Step Guide

Set Up the Upstream Repository

Add the Plainform repository as a remote to pull updates from. This only needs to be done once per project.

Add upstream remote
git remote add upstream https://github.com/GeluHorotan/plainform-essentials.git

Verify the remote was added successfully:

Verify remotes
git remote -v

You should see both origin (your repository) and upstream (Plainform repository) listed.

Create a New Branch for Updates

Start from your current main branch, make sure it is up to date, then create a dedicated update branch:

Create update branch
git switch main
git pull origin main
git switch -c update/plainform-latest

Never pull updates directly into your main branch. Always use a separate branch to test changes first.

Fetch and Merge Updates

Fetch the latest changes from the upstream repository:

Fetch upstream changes
git fetch upstream main

Merge the updates from the upstream main branch:

Merge upstream changes
git merge upstream/main

This pulls the latest commits from Plainform into your update branch.

Resolve Merge Conflicts

If your project has customizations, merge conflicts may occur. Git will pause the merge and mark conflicting files.

To resolve conflicts:

  1. Open the affected files in your code editor (VS Code will highlight conflicts)
  2. Look for conflict markers: <<<<<<<, =======, and >>>>>>>
  3. Review each conflict and decide which changes to keep
  4. Remove the conflict markers after resolving
  5. Mark files as resolved:
Mark file as resolved
git add <file-name>
  1. Complete the merge:
Complete merge
git commit

Common conflict areas include app/, components/, config/, and package.json. Take care to preserve your customizations while integrating updates.

Test Your Application

Before merging into main, install dependency changes, apply any new migrations, and run the project checks:

Install dependencies
npm install
Apply migrations
npx prisma migrate dev
Run checks
npm run lint
npm run build

Then start the app locally and test key functionality, including authentication flows, payment processing, custom features you've added, Supabase/Prisma database access, and any routes affected by merge conflicts.

Start dev server
npm run dev

Visit http://localhost:3000 and verify the app manually.

Merge Updates into Main Branch

Once conflicts are resolved and testing is complete, merge the updates into your main branch:

Checkout main branch
git switch main
Merge update branch
git merge update/plainform-latest

Push the updated main branch to your repository:

Push to origin
git push origin main

Clean Up

Delete the update branch if no longer needed:

Delete local branch
git branch -d update/plainform-latest

If you've already pushed the branch to your remote:

Delete remote branch
git push origin --delete update/plainform-latest

Best Practices

Before Pulling Updates

  • Backup Your Work: Commit or stash all uncommitted changes to avoid losing work
  • Check Release Notes: Review Plainform release notes to understand what's changing
  • Check Required Env Vars: Compare your .env / hosting variables with the latest .env.example
  • Check Migrations: Review new files in prisma/migrations before applying them
  • Plan for Downtime: Schedule updates during low-traffic periods if running in production

During the Update Process

  • Read Conflict Carefully: Don't blindly accept all incoming or current changes
  • Test Incrementally: After resolving each major conflict, test the affected functionality
  • Keep Dependencies Updated: Run npm install after merging to update dependencies
  • Review Generated Files: Do not commit .next, .source, lib/generated/prisma, sitemap files, or local .env files

After Merging

  • Run Full Test Suite: Test all critical paths in your application
  • Check Environment Variables: Verify if new environment variables are required
  • Apply Production Migrations: Run npx prisma migrate deploy during deployment if migrations changed
  • Update Documentation: Document any breaking changes that affect your team
  • Monitor Production: Watch for errors after deploying updated code

Troubleshooting

Alternative: Using Git Rebase

For a cleaner commit history, advanced Git users can rebase their update branch instead of merging:

Rebase from upstream
git switch update/plainform-latest
git rebase upstream/main

Only use rebase if you understand the conflict workflow and have not pushed the branch to a shared repository. Rebasing rewrites history and can cause issues for collaborators.

Installation Guide

Set up your Plainform project from scratch

Project Structure

Understand the folder organization

Git Workflow

Learn about branching and commit conventions

Official Git Docs

Git documentation for advanced topics

Next Steps

How is this guide ?

Last updated on

Installation

Set up Plainform locally in under 30 minutes

Architecture

Understand Plainform's architecture, conventions, and design patterns

On this page

Prerequisites
Overview
Step-by-Step Guide
Set Up the Upstream Repository
Create a New Branch for Updates
Fetch and Merge Updates
Resolve Merge Conflicts
Test Your Application
Merge Updates into Main Branch
Clean Up
Best Practices
Before Pulling Updates
During the Update Process
After Merging
Troubleshooting
Alternative: Using Git Rebase
Related Resources
Next Steps