Merge pull request #108 from czue/develop

2024.12 release notes + uv updates

configuration.md

@@ -173,14 +173,32 @@ You'll separately need to follow the steps listed on the
 [provider-specific pages here](https://docs.allauth.org/en/latest/socialaccount/providers/index.html)
 to configure things on the other side.
 These steps can sometimes be a bit involved and vary by platform.
+But will generally entail two steps:
+
+1. Creating a new application / client on the service you want to use.
+2. Adding the credentials to your environment (`.env`) file.
+
+See the Google guide below for an example you can follow.
 
 If you want to add a social login that's not supported out of the box (e.g. Facebook/Meta or Apple),
 you can follow the existing patterns and configure things based on the allauth docs.
 
 If you need help setting this up feel free to get in touch!
-Additionally see the resources below.
+Additionally, see the resources below.
+
+#### Google OAuth Specific instructions
+
+1. Register the application with google by following just the "App registration" section
+[here](https://docs.allauth.org/en/latest/socialaccount/providers/google.html). Note that
+the trailing slash for the "Authorized redirect URLs" is required. For example, assuming you are developing locally,
+it should be set to exactly `http://localhost:8000/accounts/google/login/callback/`.
+2. Set the resulting client id and secret key in the `.env` file in the root of your project.
+```
+    GOOGLE_CLIENT_ID="actual client id from the google console"
+    GOOGLE_SECRET_ID="actual secret id from the google console"
+```
 
-#### Social Setup Guides
+#### Other Social Setup Guides
 
 The Pegasus community has recommended the following guides to set things up with specific providers:
 

cookbooks.md

@@ -24,6 +24,100 @@ python ./manage.py promote_user_to_superuser [email protected]
 
 Now you should be able to access the django admin at http://localhost:8000/admin
 
+## Migrating from pip-tools to uv
+
+To migrate your project from pip-tools to uv follow these steps.
+
+### Install uv
+
+If you haven't already, [install uv](https://docs.astral.sh/uv/getting-started/installation/):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Update your project code
+
+It's recommended to do this in two steps:
+
+1. [Upgrade your project](./upgrading.md) to the latest Pegasus version, keeping your pacakge manager as "pip-tools".
+   Merge all conflicts and ensure your project is working properly on this version.
+2. Then, change the package manager from pip-tools to uv in your project settings and do another upgrade/pull request.
+
+At this point you will likely have conflicts in your requirements files, but hopefully nowhere else.
+See the next sections for resolving these.
+
+### Prepare to resolve conflicts
+
+First, follow the github instructions to merge your project on your local machine, by checking out the pegasus upgrade
+branch and merging the main branch into it.
+You will have to update the command below with the exact branch name of the pull request created by Pegasus:
+
+```
+git fetch origin
+git checkout pegasus-<version>-<timestamp>
+git merge main
+```
+
+At this point you'll have a partially merged branch with conflicts.
+
+### Migrate your requirements.in files
+
+The uv build of Pegasus no longer uses requirements files, so any changes you've made to these will need
+to be migrated to `pyproject.toml` and `uv.lock`.
+
+You can use the [reqs-sync](https://github.com/saaspegasus/reqs-sync/) package to help with this.
+Follow the steps below for any file with conflicts.
+
+To migrate your main *requirements.in* file:
+
+```bash
+uv tool run reqs-sync reqs-to-toml requirements/requirements.in
+```
+
+To migrate your development *dev-requirements.in* file:
+
+```bash
+uv tool run reqs-sync reqs-to-toml requirements/dev-requirements.in --group=dev
+```
+
+To migrate your production *prod-requirements.in* file:
+
+```bash
+uv tool run reqs-sync reqs-to-toml requirements/prod-requirements.in --group=prod
+```
+
+These commands should copy all project requirements from your `requirements.in` file(s) to your `pyproject.toml` file
+(into the appropriate group, if necessary).
+
+### Update your uv.lock file
+
+Next you should rebuild your `uv.lock` file from the updated `pyproject.toml` file:
+
+```bash
+uv lock
+```
+
+You should then check the versions that were added to the `uv.lock` file and update any as
+needed based on the versions your requirements.txt files.
+
+### Test the migration
+
+Run your project (`uv run python manage.py runserver`) and verify everything works as expected.
+
+### Remove your requirements files
+
+Finally, run:
+
+```bash
+git rm requirements/*`
+```
+
+To remove all your requirements files.
+
+Congratulations, you've migrated to uv!
+Resolve any other conflicts, push and merge your code, and you're done!
+
 ## Migrating to auto-formatted code
 
 As of February, 2023 all Pegasus projects have the option to auto-format your Python code.

getting-started.md

@@ -67,28 +67,13 @@ Then skip ahead to the [post-install steps](getting-started.md#post-installation
 
 ## Get up and running with native Python
 
-Follow these instructions to run your application in your system's Python.
 If you're using Docker you can skip this section.
 
-*A video walkthrough of most of these steps is [available here](https://www.youtube.com/watch?v=kUoKm81OFqk).*
+### Set up your Python environment
 
-### Install Prerequisites
+There are several ways of setting up your Python environment.
 
-If you haven't already, first install Python version 3.11.
-
-On Mac and windows you can [download Python 3.11 installers from here](https://www.python.org/downloads/).
-On Ubuntu it's recommended to [use the deadsnakes repo](https://www.debugpoint.com/install-python-3-11-ubuntu/).
-
-*Note: running on older Python versions may work, but 3.11 is what's tested and supported.*
-
-If you're using Postgres, you'll also want to make sure [you have it installed](https://www.postgresql.org/download/).
-Depending on how you install it, you may also need to create a user account that can create and manage databases.
-
-To use [celery](./celery.md) you will also need to [install Redis](https://redis.io/docs/getting-started/installation/).
-
-### Setup a Python 3.11 virtual environment
-
-See [the docs on Virtual Environments](/python/#using-native-system-python-with-virtual-environments) for details on this process.
+See [this page](./python/setup.md) for information on choosing an option and setting up your environment.
 
 ### Enter the project directory
 
@@ -100,6 +85,9 @@ You should see a lot of newly created files for your project including a `manage
 
 ### Install package requirements
 
+If you used `uv` your packages should already be installed.
+If you chose a different option, install them now by running:
+
 ```shell
 pip install -r dev-requirements.txt
 # for production installs use
@@ -149,18 +137,27 @@ Followed by the password for the postgres user.
 ### Create database migrations
 
 ```bash
+# with uv
+uv run manage.py makemigrations
+# or with normal venv
 python ./manage.py makemigrations
 ```
 
 ### Run database migrations
 
 ```bash
+# with uv
+uv run manage.py migrate
+# or with normal venv
 python ./manage.py migrate
 ```
 
 ### Run server
 
 ```bash
+# with uv
+uv run manage.py runserver
+# or with normal venv
 python ./manage.py runserver
 ```