From 06c54c522001d0adf27c6dfbe69a4b6953ae2f72 Mon Sep 17 00:00:00 2001 From: Chris Diaz <24395592+chrisdaaz@users.noreply.github.com> Date: Fri, 5 Sep 2025 09:55:02 -0500 Subject: [PATCH 1/2] adds howto upgrade coldfront --- docs/pages/howto/upgrade.md | 72 +++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/pages/howto/upgrade.md diff --git a/docs/pages/howto/upgrade.md b/docs/pages/howto/upgrade.md new file mode 100644 index 0000000000..c67c8aac99 --- /dev/null +++ b/docs/pages/howto/upgrade.md @@ -0,0 +1,72 @@ +# Upgrade ColdFront + +This howto guide demonstrates one way to upgrade your ColdFront codebase to the latest release or the `main` branch using `git`. + +## Git setup + +You will need to set up two git remotes: + +- `origin` -> Your organization's Git repo for ColdFront +- `upstream` -> `$ git remote add upstream https://github.com/ubccr/coldfront.git` + +Next, you will want to have at least three git branches to work with: + +- `` -> This is your default branch, containing your organization's ColdFront codebase +- `main` -> This branch tracks the `main` branch of the ColdFront project +- `staged_upgrade` -> This is based on your `custom` branch, used for resolving merge conflicts + +```sh +# let's assume you only have a `main` branch and a `custom` branch +$ git checkout main + +# pull in the latest changes +$ git pull upstream main +# or checkout a new tagged release +$ git tag -l +$ git checkout v1.x.x + +$ git checkout custom + +# make a new branch off of your `custom` branch +$ git checkout -b staged_upgrade +$ git merge main + +# resolve any conflicts in your text editor +$ git commit -m "merge bring in latest changes" +``` + +The trickiest part of the process will be to resolve any conflicts from merging `main` into your `staged_upgrade` branch. This is where you want to make sure your local customizations are kept in tact from the upgrade. + +## Database Migrations + +After your code is merged, migrate your database to accomodate changes to models: + +```sh +# make sure you have activated your virtual environment +$ source .venv/bin/activate +$ coldfront makemigrations --merge +$ coldfront migrate +``` + +## Testing + +Restart your server in your testing environment to confirm everything is working as expected. + +``` +# either in a local dev environment +$ DEBUG=True uv run coldfront runserver +# or on a test server environment +$ sudo systemctl restart gunicorn +``` + +If everything looks good, merge your `staged_upgrade` branch into your default branch: + +```sh +$ git checkout custom +$ git merge staged_upgrade +# update your remote +$ git push origin custom +$ git branch -d staged_upgrade +``` + +Your organization's ColdFront codebase should now have the latest updates from the upstream ColdFront project. If you want to enable some of the newest ColdFront features, you may need to [install](/install#installation-methods) newer packages. \ No newline at end of file From 57bf069c26e7eb5dedfaa664d841db5189bda78a Mon Sep 17 00:00:00 2001 From: Chris Diaz <24395592+chrisdaaz@users.noreply.github.com> Date: Mon, 29 Sep 2025 09:30:44 -0500 Subject: [PATCH 2/2] consolidate upgrade guide with upgrading docs page --- docs/pages/howto/upgrade.md | 72 ------------------------------------ docs/pages/upgrading.md | 73 +++++++++++++++++++++++++++++++++++++ 2 files changed, 73 insertions(+), 72 deletions(-) delete mode 100644 docs/pages/howto/upgrade.md diff --git a/docs/pages/howto/upgrade.md b/docs/pages/howto/upgrade.md deleted file mode 100644 index c67c8aac99..0000000000 --- a/docs/pages/howto/upgrade.md +++ /dev/null @@ -1,72 +0,0 @@ -# Upgrade ColdFront - -This howto guide demonstrates one way to upgrade your ColdFront codebase to the latest release or the `main` branch using `git`. - -## Git setup - -You will need to set up two git remotes: - -- `origin` -> Your organization's Git repo for ColdFront -- `upstream` -> `$ git remote add upstream https://github.com/ubccr/coldfront.git` - -Next, you will want to have at least three git branches to work with: - -- `` -> This is your default branch, containing your organization's ColdFront codebase -- `main` -> This branch tracks the `main` branch of the ColdFront project -- `staged_upgrade` -> This is based on your `custom` branch, used for resolving merge conflicts - -```sh -# let's assume you only have a `main` branch and a `custom` branch -$ git checkout main - -# pull in the latest changes -$ git pull upstream main -# or checkout a new tagged release -$ git tag -l -$ git checkout v1.x.x - -$ git checkout custom - -# make a new branch off of your `custom` branch -$ git checkout -b staged_upgrade -$ git merge main - -# resolve any conflicts in your text editor -$ git commit -m "merge bring in latest changes" -``` - -The trickiest part of the process will be to resolve any conflicts from merging `main` into your `staged_upgrade` branch. This is where you want to make sure your local customizations are kept in tact from the upgrade. - -## Database Migrations - -After your code is merged, migrate your database to accomodate changes to models: - -```sh -# make sure you have activated your virtual environment -$ source .venv/bin/activate -$ coldfront makemigrations --merge -$ coldfront migrate -``` - -## Testing - -Restart your server in your testing environment to confirm everything is working as expected. - -``` -# either in a local dev environment -$ DEBUG=True uv run coldfront runserver -# or on a test server environment -$ sudo systemctl restart gunicorn -``` - -If everything looks good, merge your `staged_upgrade` branch into your default branch: - -```sh -$ git checkout custom -$ git merge staged_upgrade -# update your remote -$ git push origin custom -$ git branch -d staged_upgrade -``` - -Your organization's ColdFront codebase should now have the latest updates from the upstream ColdFront project. If you want to enable some of the newest ColdFront features, you may need to [install](/install#installation-methods) newer packages. \ No newline at end of file diff --git a/docs/pages/upgrading.md b/docs/pages/upgrading.md index a801606c5a..304f9deb34 100644 --- a/docs/pages/upgrading.md +++ b/docs/pages/upgrading.md @@ -125,3 +125,76 @@ PLUGIN_SLURM=True SLURM_IGNORE_USERS=root,admin,testuser SLURM_SACCTMGR_PATH=/usr/bin/sacctmgr ``` + +## Upgrading with Git + +This guide demonstrates one way to use `git` to upgrade your ColdFront codebase to the latest release or the `main` branch. + +### Git setup + +You will need to set up two git remotes: + +- `origin` -> Your organization's Git repo for ColdFront +- `upstream` -> `$ git remote add upstream https://github.com/ubccr/coldfront.git` + +Next, you will want to have at least three git branches to work with: + +- `` -> This is your default branch, containing your organization's ColdFront codebase +- `main` -> This branch tracks the `main` branch of the ColdFront project +- `staged_upgrade` -> This is based on your `custom` branch, used for resolving merge conflicts + +```sh +# let's assume you only have a `main` branch and a `custom` branch +$ git checkout main + +# pull in the latest changes +$ git pull upstream main +# or checkout a new tagged release +$ git tag -l +$ git checkout v1.x.x + +$ git checkout custom + +# make a new branch off of your `custom` branch +$ git checkout -b staged_upgrade +$ git merge main + +# resolve any conflicts in your text editor +$ git commit -m "merge bring in latest changes" +``` + +The trickiest part of the process will be to resolve any conflicts from merging `main` into your `staged_upgrade` branch. This is where you want to make sure your local customizations are kept in tact from the upgrade. + +### Database Migrations + +After your code is merged, migrate your database to accomodate changes to models: + +```sh +# make sure you have activated your virtual environment +$ source .venv/bin/activate +$ coldfront makemigrations --merge +$ coldfront migrate +``` + +### Testing + +Restart your server in your testing environment to confirm everything is working as expected. + +``` +# either in a local dev environment +$ DEBUG=True uv run coldfront runserver +# or on a test server environment +$ sudo systemctl restart gunicorn +``` + +If everything looks good, merge your `staged_upgrade` branch into your default branch: + +```sh +$ git checkout custom +$ git merge staged_upgrade +# update your remote +$ git push origin custom +$ git branch -d staged_upgrade +``` + +Your organization's ColdFront codebase should now have the latest updates from the upstream ColdFront project. If you want to enable some of the newest ColdFront features, you may need to [install](/install#installation-methods) newer packages. \ No newline at end of file