Upgrading

When we release updates to Shipnative, you may want to incorporate them into your project. Since you own your codebase and likely have custom modifications, updates require a manual merge process.

Your app is yours. Unlike a dependency you update via npm, Shipnative is a starting point you’ve customized. Updates are applied by merging our changes with yours, not by replacing your code.

Choose Your Workflow

There are two main workflows for staying updated. We recommend the Upstream Remote workflow for most users.

Upstream Remote (Recommended)

Best for most users. Keep your own repo structure, pull updates when needed. Simpler setup, works immediately.

Fork-Based

Best if you want to contribute back. Fork the repo, sync periodically. Requires accepting org invitation first.

Aspect	Upstream Remote	Fork-Based
Setup complexity	Simple - just add a remote	Requires org invitation + fork
Can contribute PRs	No	Yes
Repo ownership	Your own repo from scratch	Fork of Shipnative
Recommended for	Most users	Contributors

Before Any Upgrade

Commit all your current work - Ensure your working directory is clean
Check the CHANGELOG - Review what changed and whether you need/want the updates
Back up your branch - Create a backup branch before merging

# Ensure everything is committed
git status

# Create a backup branch
git checkout -b backup/pre-upgrade-$(date +%Y%m%d)
git checkout main  # or your primary branch

Workflow 1: Upstream Remote (Recommended)

This is the simplest approach. You keep your own repo and pull updates from Shipnative when needed.

Initial Setup (One-Time)

After cloning Shipnative, set up your remotes:

# Rename the original remote to 'upstream'
git remote rename origin upstream

# Add your own repo as 'origin'
git remote add origin https://github.com/YOUR_USERNAME/your-app.git

# Verify setup
git remote -v
# origin    https://github.com/YOUR_USERNAME/your-app.git (fetch)
# origin    https://github.com/YOUR_USERNAME/your-app.git (push)
# upstream  https://github.com/shipnativeapp/shipnative.git (fetch)
# upstream  https://github.com/shipnativeapp/shipnative.git (push)

# Push to your repo
git push -u origin main

Already disconnected the remote? No problem - just add it back:

git remote add upstream https://github.com/shipnativeapp/shipnative.git

Pulling Updates

When you want to incorporate Shipnative updates:

# Fetch latest from Shipnative
git fetch upstream

# Create an upgrade branch (don't merge directly to main)
git checkout -b upgrade/shipnative-$(date +%Y%m%d)

# Merge upstream changes
git merge upstream/main --no-commit

The --no-commit flag lets you review changes before committing.

Resolve Conflicts

If there are conflicts:

git status  # Shows conflicted files

For each conflicted file:

Open the file and look for conflict markers (<<<<<<<, =======, >>>>>>>)
Decide which changes to keep (yours, theirs, or a combination)
Remove the conflict markers
Stage the resolved file: git add <filename>

Complete the Upgrade

# After resolving conflicts and testing
git commit -m "Upgrade to Shipnative $(date +%Y%m%d)"

# Merge to main
git checkout main
git merge upgrade/shipnative-$(date +%Y%m%d)

# Push to your repo
git push origin main

Workflow 2: Fork-Based

Use this if you want to contribute changes back to Shipnative via pull requests.

Prerequisite: You must accept the organization invitation first. Check your GitHub notifications or email for an invite to join shipnativeapp. Once accepted, you can fork the private repo.

Initial Setup (One-Time)

Accept org invitation - Check GitHub notifications
Fork the repo - Go to https://github.com/shipnativeapp/shipnative and click “Fork”
Clone your fork:

git clone https://github.com/YOUR_USERNAME/shipnative.git my-app
cd my-app

# Add upstream remote pointing to original
git remote add upstream https://github.com/shipnativeapp/shipnative.git

# Verify setup
git remote -v
# origin    https://github.com/YOUR_USERNAME/shipnative.git (fetch)
# origin    https://github.com/YOUR_USERNAME/shipnative.git (push)
# upstream  https://github.com/shipnativeapp/shipnative.git (fetch)
# upstream  https://github.com/shipnativeapp/shipnative.git (push)

Syncing Your Fork

When you want to incorporate Shipnative updates:

# Fetch latest from original repo
git fetch upstream

# Create upgrade branch
git checkout -b upgrade/sync-$(date +%Y%m%d)

# Merge upstream changes
git merge upstream/main --no-commit

# Resolve conflicts, test, then commit
git commit -m "Sync with upstream $(date +%Y%m%d)"

# Merge to main and push to your fork
git checkout main
git merge upgrade/sync-$(date +%Y%m%d)
git push origin main

Contributing Back

If you fix a bug or add a feature others might benefit from:

# Create a feature branch from latest upstream
git fetch upstream
git checkout -b fix/your-bugfix upstream/main

# Make your changes, commit
git add .
git commit -m "Fix: description of fix"

# Push to your fork
git push origin fix/your-bugfix

# Create PR on GitHub from your fork to shipnativeapp/shipnative

Additional Methods

Cherry-Pick Specific Changes

When you only want specific commits (e.g., a bug fix or new feature):

git fetch upstream
git log upstream/main --oneline  # Find commit hashes

git checkout -b feature/specific-update
git cherry-pick abc1234  # Cherry-pick by commit hash
git cherry-pick def5678

If conflicts occur:

# Resolve conflicts, then:
git cherry-pick --continue

Manual Copy

For small updates or when git conflicts are overwhelming:

Check the CHANGELOG for what changed
Browse the commit history to see file changes
Manually copy the relevant code changes into your project
Test thoroughly

This method is error-prone for large updates. Prefer git merge when possible.

Post-Upgrade Checklist

After any upgrade:

Install Dependencies

yarn install

New packages may have been added.

Check for New Environment Variables

Compare your .env with .env.example:

diff apps/app/.env apps/app/.env.example

Add any new variables.

Run Database Migrations (if applicable)

For Supabase:

supabase db push

For Convex:

npx convex dev

Rebuild Dev Client (if native changes)

If native code changed (new packages, config changes):

cd apps/app
yarn prebuild:clean
yarn ios  # or yarn android

Test Core Flows

Sign up / Sign in
Profile updates
Payments (in sandbox)
Push notifications

Handling Common Conflicts

app.json Conflicts

Keep your app name, bundle ID, and scheme. Accept new Expo SDK versions or plugin configurations:

{
  "expo": {
    "name": "YOUR APP NAME",        // Keep yours
    "slug": "your-app-slug",        // Keep yours
    "version": "1.0.0",             // Keep yours
    "sdkVersion": "52.0.0",         // Accept theirs (usually)
    "ios": {
      "bundleIdentifier": "com.you.yourapp"  // Keep yours
    }
  }
}

package.json Conflicts

Generally accept the upstream dependency versions unless you have a specific reason to stay on an older version:

# After resolving package.json
yarn install

Screen/Component Conflicts

If you’ve heavily modified a screen:

Review what the upstream change does
Decide if you need it
If yes, manually integrate the logic into your version
If no, keep your version

Staying Informed

CHANGELOG

All releases documented with migration notes

Discord

Announcements and upgrade help from the community

FAQ

Which workflow should I use?

Use Upstream Remote (recommended) unless you specifically want to contribute PRs back to Shipnative. It’s simpler to set up and works the same way for pulling updates.

How often should I upgrade?

There’s no fixed schedule. Check the CHANGELOG periodically (monthly is reasonable) and upgrade when you see changes relevant to your app - security fixes, features you want, or bug fixes you’ve encountered.

Can I skip versions?

Yes. Each upgrade merges the latest changes regardless of how many versions you’ve skipped. However, larger gaps mean more potential conflicts.

What if I can't resolve a conflict?

Ask in Discord! Share the conflicted file and your use case, and we’ll help you work through it.

I disconnected the remote - can I still upgrade?

Yes! Just add the upstream remote again:

git remote add upstream https://github.com/shipnativeapp/shipnative.git
git fetch upstream

Why can't I fork the repo?

You need to accept your organization invitation first. Check your GitHub notifications or email for an invite to join shipnativeapp. Once you’re an org member, you can fork private repos.

Introduction

Getting Started

Core Features

Development

Deployment

Support

Choose Your Workflow

Upstream Remote (Recommended)

Fork-Based

Before Any Upgrade

Workflow 1: Upstream Remote (Recommended)

Initial Setup (One-Time)

Pulling Updates

Resolve Conflicts

Complete the Upgrade

Workflow 2: Fork-Based

Initial Setup (One-Time)

Syncing Your Fork

Contributing Back

Additional Methods

Cherry-Pick Specific Changes

Manual Copy

Post-Upgrade Checklist

Handling Common Conflicts

app.json Conflicts

package.json Conflicts

Screen/Component Conflicts

Staying Informed

CHANGELOG

Discord

FAQ

​Choose Your Workflow

Upstream Remote (Recommended)

Fork-Based

​Before Any Upgrade

​Workflow 1: Upstream Remote (Recommended)

​Initial Setup (One-Time)

​Pulling Updates

​Resolve Conflicts

​Complete the Upgrade

​Workflow 2: Fork-Based

​Initial Setup (One-Time)

​Syncing Your Fork

​Contributing Back

​Additional Methods

​Cherry-Pick Specific Changes

​Manual Copy

​Post-Upgrade Checklist

​Handling Common Conflicts

​app.json Conflicts

​package.json Conflicts

​Screen/Component Conflicts

​Staying Informed

CHANGELOG

Discord

​FAQ

Choose Your Workflow

Before Any Upgrade

Workflow 1: Upstream Remote (Recommended)

Initial Setup (One-Time)

Pulling Updates

Resolve Conflicts

Complete the Upgrade

Workflow 2: Fork-Based

Initial Setup (One-Time)

Syncing Your Fork

Contributing Back

Additional Methods

Cherry-Pick Specific Changes

Manual Copy

Post-Upgrade Checklist

Handling Common Conflicts

app.json Conflicts

package.json Conflicts

Screen/Component Conflicts

Staying Informed

FAQ