upgrade-project.md

Upgrade Project

Table of Contents

• from v4.N to v4.7+
• from v3 to v4
• from v3.N to v3.12+
• from v2 to v3

from v4.N to v4.7

• Update Custom Favicon Setting
• Upgrade Custom Logo Setting

Update Custom Favicon Setting

1. Rename the FAVICON dict to PORTAL_FAVICON.
2. Add a key/value pair to the PORTAL_FAVICON.

- FAVICON = {
-     "img_file_src": "site_cms/img/favicons/favicon.ico"
+ PORTAL_FAVICON = {
+     "img_file_src": "site_cms/img/favicons/favicon.ico",
+     "is_remote": False,
}

Upgrade Custom Logo Setting

Refactor the LOGO array to a PORTAL_LOGO dict:

- LOGO = [
-     "portal",
-     "site_cms/img/org_logos/portal.png",
-     "",
-     "/",
-     "_self",
-     "Portal Logo",
-     "anonymous",
-     "True"
- ]
+ PORTAL_LOGO = {
+     "is_remote": False,
+     "img_file_src": "site_cms/img/org_logos/portal.png",
+     "img_class": "", # additional class names
+     "link_href": "/",
+     "link_target": "_self",
+     "img_alt_text": "Portal Logo",
+     "img_crossorigin": "anonymous",
+ } # To hide logo, set `PORTAL_LOGO = False`

Map of Array Values to Dict Properties

	from Array Value	to Dict Property
0	"portal"	(unused value)
1	"site_cms/.../portal.png"	"img_file_src"
2	""	"img_class"
3	"/"	"link_href"
4	"_self"	"link_target"
5	"Portal Logo"	"img_alt_text"
6	"anonymous"	"img_crossorigin"
7	"True"	(whether to show logo)

from v3 to v4

1. Use Postgres is v14.9 or greater. You may assume all TACC sites do.
2. Update code that uses features removed in Django 4 e.g.
   • django.conf.urls.url()
   • django.utils.encoding.force_text()
   • django.utils.translation.ugettext...
3. Bookmark backwards incompatible changes in Django 4.
4. Deploy and test.

   Given a …	Then …
   Deployed Website	Follow How To Build & Deploy a CMS Website.
   Local Instance	Follow Update Project instructions. (Assume everything changed.)

from v3.N to v3.12+

1. Rename Custom Project Directory
2. Redirect Deprecated Templates
3. Deploy And Test
4. Clean Up After Deploy

Rename Custom Project Directory

If your custom project directory name has dashes, e.g.

taccsite_custom/custom-project-dir

Then:

1. Rename all custom-project-dir directories to custom_project_dir.
2. Update all custom-project-dir references to custom_project_dir.

Important A custom project directory name is a Django application. A Django application name must be "a valid Python identifier".

Redirect Deprecated Templates

If your custom project directory has any templates/*.html e.g.

• taccsite_custom/custom_project_dir/templates/standard.html
• taccsite_custom/custom_project_dir/templates/fullwidth.html
• taccsite_custom/custom_project_dir/templates/home.html

Then:

1. Copy the templates to become deprecated templates:

   • from custom_project_dir/templates
   • to custom-project-dir/templates

   Warning The name custom-project-dir must match the old name as it was, including dashes.

2. Edit the deprecated templates to extend the new templates e.g.

   {% extends "custom_project_dir/templates/standard.html" %}

3. Update settings_custom.py to support deprecated templates:

       ('custom_project_dir/templates/standard.html', 'Standard'),
       ('custom_project_dir/templates/fullwidth.html', 'Full Width'),
   +   ('custom-project-dir/templates/standard.html', 'DEPRECATED Standard'),
   +   ('custom-project-dir/templates/fullwidth.html', 'DEPRECATED Full Width'),

Deploy And Test

For a Deployed Website

Follow How To Build & Deploy a CMS Website.

For a Local Instance

Follow Update Project instructions. (Assume everything changed.)

Clean Up After Deploy

1. Change template of every page on the CMS to not use deprecated template.
2. Remove its deprecated templates from repository.

from v2 to v3

Undocumented. Contact a primary contributor for assistance.