# Upgrading from 1.2 to 1.3

This guide explains how to upgrade the version of the ScyllaDB Sphinx Theme.

## How to check your current theme version

The theme version is displayed in the footer of the project’s documentation site.

![image](upgrade/version.png)

If your project theme’s version is **>=1.2**, follow this guide to get the latest version.

## Upgrade to version 1.3

Here are the main breaking changes between the 1.2 and 1.3 versions.

1. Update the following Python dependencies in `docs/pyproject.toml`:
   > ```default
   > sphinx-scylladb-theme = "~1.3.1"
   > redirects_cli ="~0.1.3"
   > ```
2. Add the new redirects command in `docs/Makefile`:
   > ```default
   > .PHONY: redirects
   > redirects: setup
   >     $(POETRY) run redirects-cli fromfile --yaml-file ./_utils/redirects.yaml --output-dir $(BUILDDIR)/dirhtml
   >     @echo
   >     @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
   > ```
3. Create a new file `docs/_utils/redirects.yml`. If the project has a file `docs/_utils/redirections.yml`, rename it to `docs/_utils/redirects.yml` and update it to the new format:
   > Before, redirects were created for all versions:
   > ```default
   > test-redirect: /stable/index
   > ```

   > If the project were building docs for the branches `stable` and `branch-1.0`, it would generate the following redirections:
   > > * `/stable/test-redirect` -> `/stable/index`
   > > * `/branch-1.0/test-redirect` -> `/stable/index`

   > Now, you have more control to define redirects per version. To create the same redirects as in the previous example, the new format is:
   > ```default
   > /stable/test-redirect.html: /stable/index.html
   > /branch-1.0/test-redirect.html: /stable/index.html
   > ```

   > #### NOTE
   > Notice that now you must append the `.html` extension to the redirects.
4. Remove the file `.github/workflows/docs-pages.yml`. Then, copy the new workflow in the `.github/workflows` folder. You can download the latest docs-pages.yml workflow [here](https://github.com/scylladb/sphinx-scylladb-theme/tree/master/.github/workflows).
   > If the default branch is not `master` or the docs are not under the `docs` folder, the workflows to match the project configuration. For example:
   > ```default
   > on:
   > push:
   >     branches:
   >     - master # edit this line
   >     paths:
   >     - "docs/**" # edit this line
   > ```
5. Commit and push the changes to GitHub (default branch).

To check if the upgrade completed successfully, run the command [make preview](https://sphinx-theme.scylladb.com/master/commands.md).
Then, check if the site footer displays version 1.3 or greater.