We use tracking cookies to understand how you use the product and help us improve it. For more information on how we store cookies, read our  privacy policy.

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
  • Uncommitted changes committed or stashed
  • 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

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

Create update branch
git checkout -b update-branch

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

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, test your application locally to ensure everything works correctly:

Install dependencies
npm install
Start dev server
npm run dev

Visit http://localhost:3000 and test key functionality, including authentication flows, payment processing (if applicable), custom features you've added, and database connections.

Merge Updates into Main Branch

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

Checkout main branch
git checkout main
Merge update branch
git merge update-branch

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-branch

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

Delete remote branch
git push origin --delete update-branch

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
  • 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

After Merging

  • Run Full Test Suite: Test all critical paths in your application
  • Check Environment Variables: Verify if new environment variables are required
  • 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, you can use rebase instead of merge:

Rebase from upstream
git checkout update-branch
git rebase upstream/main

Only use rebase if you haven't pushed your 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