Upgrading Pegasus is currently a manual process though there are plans to improve it in the future.

New projects are recommended to use the branch-based approach. Older projects can use the patch-based approach.

The upgrade process can also be used when changing any Pegasus configuration variables.

Using patches (if you can’t use 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#

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. 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#

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

First, use git-apply to apply the patch. The recommended command to run is:

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. 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:

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

Other notes#

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:

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#

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), and jump to step 2 above.