# Upgrading and Changing your Project Settings

> Upgrade Pegasus projects to new versions using GitHub integration, git branches, or patch files with conflict resolution strategies.

There are several ways to update your Pegasus project. These methods can be used to upgrade your project to a new Pegasus version, or when changing anything in your project configuration.

## Using the Github integration (recommended)

[Section titled “Using the Github integration (recommended)”](#using-the-github-integration-recommended)

The easiest way to upgrade your project is to use the built-in Github integration. If you created your project with Github, you should be able to make any changes you want to your project configuration and then create a pull request with the updated code from the “Download” page.

If you did not create your project with the Github you can still use this method. First follow the instructions for [connecting an existing project to Github](/github/#connecting-an-existing-project-to-github). After completing that step, you should be able to submit updates to your project via pull request, just like above.

You can watch a demo of this set up here:

Note: Whenever you merge Pegasus pull requests you should **use the Github option to “Create a merge commit”**. Do NOT use “Squash and merge” or “Rebase and merge”, as they could prevent future updates from merging cleanly into your project.

## Manually, using branches

[Section titled “Manually, using branches”](#manually-using-branches)

If you don’t want to, or can’t, use the Github integration, you can manually upgrade your project with git branches. Note that this is a longer and more complicated process than using the Github integration, which handles most of these steps for you.

With this option you maintain a “pure” Pegasus branch in your repository with no other modifications. Then, you merge this branch into your main app when you upgrade.

This process is outlined below, and also in the below screencast which shows a live example on a real Pegasus project.

Here are the steps to take:

### 1. Create a branch for the upgrade

[Section titled “1. Create a branch for the upgrade”](#1-create-a-branch-for-the-upgrade)

First [checkout the first commit](https://stackoverflow.com/questions/43197105/how-do-you-jump-to-the-first-commit-in-git) in your repository and create a new branch from there.

After finding and checking out the initial commit, run:

```bash
git branch pegasus
git checkout pegasus
```

*Note: if you created the `pegasus` branch when you set up your codebase you can skip this step. Alternatively, if you don’t have any commit with pure pegasus code, see the instructions at the bottom of this page to create one.*

Next, make sure the branch is up-to-date with your current Pegasus version:

1. Download your Pegasus project on your *current* version and unzip the code.
2. Copy the `.git` folder from your main project into the downloaded codebase.
3. Make sure you are on the `pegasus` branch (`git checkout pegasus`)
4. Commit all changes (`git add .` then `git commit -am "ready to upgrade"`)

### 2. Upgrade the code in the branch

[Section titled “2. Upgrade the code in the branch”](#2-upgrade-the-code-in-the-branch)

1. Upgrade your project on saaspegasus.com
2. Download the latest codebase and unzip the code.
3. Copy the `.git` folder from step 1 into this new folder.
4. Commit all changes (`git add .` then `git commit -am "upgrade to latest Pegasus"`)

### 3. Merge into your main branch

[Section titled “3. Merge into your main branch”](#3-merge-into-your-main-branch)

1. Checkout the (latest/current) main branch (`git checkout main`)
2. Merge the code (`git merge pegasus`)

Alternatively you may wish to do this in a new branch and then submit a pull request to the main branch from there:

1. Create a new branch off of the main branch (`git checkout main; git checkout -b upgrade-pegasus`)
2. Merge the code (`git merge pegasus`)

In the merging step you should look at the modifications being made, and you may have to manually resolve conflicts that come up. You may also need to run `./manage.py makemigrations` to create any database migrations that were not included with Pegasus.

## Manually, using patches (if you can’t use Github or branches)

[Section titled “Manually, using patches (if you can’t use Github or branches)”](#manually-using-patches-if-you-cant-use-github-or-branches)

You can also follow a similar process to the above using Git patches. Patches do not require working in the same repository or having a previously created branch.

At a high level you will:

1. Create a patch file containing the changes in the upgrade.
2. Apply the patch to your app.

Here we’ll walk through the steps in more detail.

### 1. Creating the patch file

[Section titled “1. Creating the patch file”](#1-creating-the-patch-file)

Follow these steps to create your patch file:

1. Download a “clean” version of your Pegasus project on your *current* version, and commit it to a git branch or repository.
2. Upgrade your Pegasus version (or change your configuration), and download the new codebase.
3. Copy your `.git` directory from your “clean” project in step 1 into your new project in step 2. E.g. `cp -r path/to/yourapp/.git path/to/newapp/`.
4. In your new project directory, *commit all of the changes* in a single commit.
5. Create a patchfile for the commit using [git-format-patch](https://git-scm.com/docs/git-format-patch). The recommended command to run is `git format-patch -1 HEAD`.

You should now see a file in your repository root with a name like `0001-branch-details.patch`. This is your patch file.

### 2. Applying the patch file

[Section titled “2. Applying the patch file”](#2-applying-the-patch-file)

Now return to your main branch in your application’s repository.

First, use [git-apply](https://git-scm.com/docs/git-apply) to apply the patch. The recommended command to run is:

```bash
git apply --ignore-space-change --ignore-whitespace --reject /path/to/<patchname>.patch
```

substituting the path/name of the patchfile created above.

This command will do a best-effort application of the patch.

For each affected file:

1. If updates could be applied cleanly, the file will be updated with the contents of the applied patch.
2. If updates could not be applied cleanly, a new diff file called `<filename>.rej` will be created, showing the diff that could not be applied.

If the file was partially updated then the file will be modified *and* the remaining changes will be visible in the `<filename>.rej` file.

The last step of the upgrade process is to go through each file and:

1. If the file has been modified, look at the modifications, see if you want them, and commit/reject them as necessary.
2. If the file has a `<filename>.rej` file, look at the proposed diff and see if you want to manually apply it, or ignore it.

After you have merged all changes to a file, you should delete the `<filename>.rej` file.

To understand the format of the `<filename>.rej` files, take a look at the [unified diff format](https://en.wikipedia.org/wiki/Diff#Unified_format). Basically changes will look like the below, with a line starting with a minus sign, indicating a removal, and a plus sign indicating an addition.

In this example, the type annotations were added to the function signature:

```bash
-def is_member(user, team):
+def is_member(user: CustomUser, team: apps.teams.models.Team) -> bool:
```

## Conflict Resolution Tips and Tricks

[Section titled “Conflict Resolution Tips and Tricks”](#conflict-resolution-tips-and-tricks)

The most time-consuming part of an upgrade is typically resolving conflicts between changes you’ve made and changes in the updated Pegasus release. Here are some tips and tricks for managing this process.

### Make sure resolutions are recorded

[Section titled “Make sure resolutions are recorded”](#make-sure-resolutions-are-recorded)

Git has a feature called [rerere](https://git-scm.com/book/en/v2/Git-Tools-Rerere), which stands for “reuse recorded resolution”. This feature allows you to ask Git to remember how you’ve resolved a conflict so that the next time it sees the same conflict, Git can resolve it for you automatically. Enabling this feature will make future merges much smoother as each conflict will only have to be resolved once.

The easiest way to ensure rerere is enabled is to use the Github integration. If that’s not possible, you can enable it locally by running:

```bash
$ git config --global rerere.enabled true
```

### Resolving Database Migrations

[Section titled “Resolving Database Migrations”](#resolving-database-migrations)

It can be quite common for there to be conflicting database migrations during an upgrade. This can happen when Pegasus modifies data models, you change your project settings in a way that updates models, or you customize Pegasus models in your own code.

To resolve any issues with database migrations, follow the following steps:

1. Always commit your migration files to source control. This makes it easier to have a consistent state across environments and builds.
2. Before doing an upgrade, make sure your project migrations are up to date (`manage.py makemigrations` should do nothing).
3. After doing an upgrade, if Pegasus adds or changes any migration files, *discard those changes*.
4. After merging the code and discarding any changes to migrations introduced by Pegasus, re-run `manage.py makemigrations` on the upgraded code, and commit the result to source control.
5. Run `manage.py migrate` to update the database.

Basically, **you should always keep your migration history and throw away any changes Pegasus proposes to existing migration files.** Then re-run `makemigrations` on the merged code.

### Resolving Python Package “generated” files (e.g. `uv.lock`)

[Section titled “Resolving Python Package “generated” files (e.g. uv.lock)”](#resolving-python-package-generated-files-eg-uvlock)

Python packages in Pegasus have lock files that are dynamically generated from other files:

* If you’re using uv, your `uv.lock` is generated from `pyproject.toml`.
* If you’re using pip-tools, your `requirements.txt` is generated from `requirements.in`.

In either case, the easiest way to resolve the conflicts in these files is:

1. *Merge* the source file (`pyproject.toml` or `requirements.in`).
2. Accept all of SaaS Pegasus’s proposed changes to the generated file. While merging your main branch to the pegasus update branch you can run `git checkout --ours uv.lock` to achieve this.
3. Regenerate the generated file, using `uv sync` or `pip-compile`.
4. Manually inspect the new library versions and update them as needed.

The end result of this should be that you get all of Pegasus’s pinned versions, and then manually choose which of your own dependencies (if any) to update.

### Resolving bundled static files

[Section titled “Resolving bundled static files”](#resolving-bundled-static-files)

Conflicts in any built static files should be resolved by:

1. Deleting the files entirely.
2. Re-running `npm run build` / `npm run dev` and committing the result.

## Post-merge steps

[Section titled “Post-merge steps”](#post-merge-steps)

After upgrading you may also need to reinstall requirements (`pip install -r requirements.txt`), npm packages (`npm install`), etc. depending on what has changed.

You will also need to rebuild your front end if you’ve made any changes there (`npm run dev` or `npm run build`)

If you are using docker you can use the ‘upgrade’ make target to do this:

```bash
make upgrade
```

This will rebuild the Docker images and create and run any database migrations that are needed. **Note: your web container needs to be running when you run this or it will fail.**

## If you don’t have a “pure” Pegasus branch

[Section titled “If you don’t have a “pure” Pegasus branch”](#if-you-dont-have-a-pure-pegasus-branch)

In some cases you may not have a “clean” Pegasus branch. This could happen if you did substantial development before your first commit, merged Pegasus into another project, or did several upgrades.

In this case you can fake a pure Pegasus branch by taking the following steps. *Note: this process destroys `git blame` for most of your project.*

1. Save your current code (from the “main” branch).
2. Make a new branch (e.g. called “pure-pegasus”)
3. Download your codebase from saaspegasus.com on the *last release your project used/upgraded to*.
4. Put the unmodified download of Pegasus 2022.3 onto that branch, without any of your own code. The easiest way to do that is to copy the `.git` folder into your downloaded project and immediately commit the result. This will “brutally” overwrite all your customizations in your git history. *Note this commit id.*
5. Then repeat this process, but instead, do the reverse. Copy the `.git` folder from the Pegasus download back into your (unmodified) copy of the `main` code and again commit the result. This will create a single commit containing all customizations you’ve made to your project.
6. Review this code and merge it back into `main`. If you did everything correctly you should have two huge commits but the pull request will contain no changes.

After this process git will believe that the pure pegasus code is fully merged to `main`. You can then use the commit id you noted in step 4 as the starting point for your upgrade ([step 1](#1-create-a-branch-for-the-upgrade)), and jump to [step 2 above](#2-upgrade-the-code-in-the-branch).