MyApp

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:

Open the affected files in your code editor (VS Code will highlight conflicts)
Look for conflict markers: <<<<<<<, =======, and >>>>>>>
Review each conflict and decide which changes to keep
Remove the conflict markers after resolving
Mark files as resolved:

Mark file as resolved

git add <file-name>

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

Configure your IDE for optimal development
Set up environment variables for your project
Learn about the architecture to understand the codebase

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

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:

Open the affected files in your code editor (VS Code will highlight conflicts)
Look for conflict markers: <<<<<<<, =======, and >>>>>>>
Review each conflict and decide which changes to keep
Remove the conflict markers after resolving
Mark files as resolved:

Mark file as resolved

git add <file-name>

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.

Configure your IDE for optimal development
Set up environment variables for your project
Learn about the architecture to understand the codebase

Pull Updates

Error: remote upstream already exists

Too many merge conflicts to resolve

Tests fail after merging updates

Lost my customizations during merge

Want to undo the merge

Installation Guide

Project Structure

Git Workflow

Official Git Docs

On this page

Pull Updates

Error: remote upstream already exists

Too many merge conflicts to resolve

Tests fail after merging updates

Lost my customizations during merge

Want to undo the merge

Installation Guide

Project Structure

Git Workflow

Official Git Docs

On this page