> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipnative.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrading

> How to update your app with the latest Shipnative changes

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.

<Info>
  **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.
</Info>

## Choose Your Workflow

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

<CardGroup cols={2}>
  <Card title="Upstream Remote (Recommended)" icon="code-branch" href="#workflow-1-upstream-remote-recommended">
    **Best for most users.** Keep your own repo structure, pull updates when needed. Simpler setup, works immediately.
  </Card>

  <Card title="Fork-Based" icon="code-fork" href="#workflow-2-fork-based">
    **Best if you want to contribute back.** Fork the repo, sync periodically. Requires accepting org invitation first.
  </Card>
</CardGroup>

| 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

1. **Commit all your current work** - Ensure your working directory is clean
2. **Check the [CHANGELOG](https://github.com/shipnativeapp/shipnative/blob/main/CHANGELOG.md)** - Review what changed and whether you need/want the updates
3. **Back up your branch** - Create a backup branch before merging

```bash theme={null}
# 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:

```bash theme={null}
# 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
```

<Tip>
  **Already disconnected the remote?** No problem - just add it back:

  ```bash theme={null}
  git remote add upstream https://github.com/shipnativeapp/shipnative.git
  ```
</Tip>

### Pulling Updates

When you want to incorporate Shipnative updates:

```bash theme={null}
# 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:

```bash theme={null}
git status  # Shows conflicted files
```

For each conflicted file:

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

### Complete the Upgrade

```bash theme={null}
# 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.

<Warning>
  **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.
</Warning>

### Initial Setup (One-Time)

1. **Accept org invitation** - Check GitHub notifications
2. **Fork the repo** - Go to [https://github.com/shipnativeapp/shipnative](https://github.com/shipnativeapp/shipnative) and click "Fork"
3. **Clone your fork:**

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# 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):

```bash theme={null}
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:

```bash theme={null}
# Resolve conflicts, then:
git cherry-pick --continue
```

### Manual Copy

For small updates or when git conflicts are overwhelming:

1. Check the [CHANGELOG](https://github.com/shipnativeapp/shipnative/blob/main/CHANGELOG.md) for what changed
2. Browse the [commit history](https://github.com/shipnativeapp/shipnative/commits/main) to see file changes
3. Manually copy the relevant code changes into your project
4. Test thoroughly

<Warning>
  This method is error-prone for large updates. Prefer git merge when possible.
</Warning>

***

## Post-Upgrade Checklist

After any upgrade:

<Steps>
  <Step title="Install Dependencies">
    ```bash theme={null}
    yarn install
    ```

    New packages may have been added.
  </Step>

  <Step title="Check for New Environment Variables">
    Compare your `.env` with `.env.example`:

    ```bash theme={null}
    diff apps/app/.env apps/app/.env.example
    ```

    Add any new variables.
  </Step>

  <Step title="Run Database Migrations (if applicable)">
    For Supabase:

    ```bash theme={null}
    supabase db push
    ```

    For Convex:

    ```bash theme={null}
    npx convex dev
    ```
  </Step>

  <Step title="Rebuild Dev Client (if native changes)">
    If native code changed (new packages, config changes):

    ```bash theme={null}
    cd apps/app
    yarn prebuild:clean
    yarn ios  # or yarn android
    ```
  </Step>

  <Step title="Test Core Flows">
    * Sign up / Sign in
    * Profile updates
    * Payments (in sandbox)
    * Push notifications
  </Step>
</Steps>

***

## Handling Common Conflicts

### app.json Conflicts

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

```json theme={null}
{
  "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:

```bash theme={null}
# After resolving package.json
yarn install
```

### Screen/Component Conflicts

If you've heavily modified a screen:

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

***

## Staying Informed

<CardGroup cols={2}>
  <Card title="CHANGELOG" icon="scroll" href="https://github.com/shipnativeapp/shipnative/blob/main/CHANGELOG.md">
    All releases documented with migration notes
  </Card>

  <Card title="Discord" icon="discord" href="https://discord.gg/shipnative">
    Announcements and upgrade help from the community
  </Card>
</CardGroup>

***

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="I disconnected the remote - can I still upgrade?">
    Yes! Just add the upstream remote again:

    ```bash theme={null}
    git remote add upstream https://github.com/shipnativeapp/shipnative.git
    git fetch upstream
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>