# Upgrading from 1.7 to 1.8

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.7**, follow this guide to get the latest version.

## Upgrade to version 1.8

Here are the main breaking changes between the 1.6 and 1.7 versions.

### Commit the poetry.lock file to the repository

We recommend that teams commit the `poetry.lock` file to the repository.
Doing so ensures that dependencies are locked, leading to consistent documentation builds across different environments.
For more information, see [Committing your poetry.lock file to version control](https://python-poetry.org/docs/basic-usage/#committing-your-poetrylock-file-to-version-control).

Steps to apply this change:

1. Remove the `poetry.lock` file from the `.gitignore` file. This file could be either in the root of the repository or in the `docs` directory.
2. Update the `docs/Makefile` and remove the `rm -f poetry.lock` command from the `clean` command:
   > ```default
   > # Clean commands
   > .PHONY: clean
   > clean:
   >     rm -rf $(BUILDDIR)/*
   >     # rm -f poetry.lock
   > ```
3. In the same file, remove the line `$(POETRY) update` from the `setup` command:
   > ```default
   > .PHONY: setup
   > setup:
   >     $(POETRY) install
   >     # $(POETRY) update
   > ```
4. In the same file, add a new command to update Python dependencies:
   > ```default
   > .PHONY: update
   > update:
   >     $(POETRY) update
   > ```
5. Add the following `dependabot.yml` configuration file in the `.github` directory:
   > ```default
   > version: 2
   > updates:
   >   - package-ecosystem: "uv"
   >     directory: "/docs"
   >     schedule:
   >       interval: "daily"
   >     allow:
   >       - dependency-name: "sphinx-scylladb-theme"
   >       - dependency-name: "sphinx-multiversion-scylla"
   > ```

   This configuration helps keep your project up-to-date with the latest theme versions automatically.
6. In the `docs/pyproject.toml` file, set Poetry to use the non-package mode:
   > ```default
   > [tool.poetry]
   > name = "scylla"
   > description = "Scylla Documentation"
   > version = "4.3.0"
   > authors = ["ScyllaDB Contributors"]
   > package-mode = false
   > ```
7. Ensure all dependencies in the `docs/pyproject.toml` file are configured to install the latest minor versions by using the `^` symbol followed by the major and minor version number:
   > Example:
   > ```default
   > (...)

   > [tool.poetry.dependencies]
   > python = "^3.10"
   > pygments = "^2.18.0"
   > sphinx-scylladb-theme = "^1.8.1"
   > myst-parser = "^3.0.1"
   > sphinx-autobuild = "^2024.4.19"
   > Sphinx = "^7.3.7"
   > sphinx-multiversion-scylla = "^0.3.1"
   > sphinx-sitemap = "^2.6.0"
   > redirects_cli ="^0.1.3"

   > (...)
   > ```
8. In the same `docs/pyproject.toml` file, update the poetry dependency to version 1.8.0:
   > ```python
   > (...)
   > [build-system]
   > requires = ["poetry>=1.8.0"]
   > build-backend = "poetry.masonry.api"
   > ```
9. Run the following command in the `docs``folder to update the ``poetry.lock` file:
   > ```python
   > poetry lock --no-update
   > ```
10. Preview the docs. Ensure sure they render without errors:
    > ```python
    > make preview
    > ```
11. Commit the changes to the repository, including the `poetry.lock` file.

### Update mascots and icons

If your homepage was using mascots or icons, update them to the new ones.

For more information, see:

* [Mascots](https://sphinx-theme.scylladb.com/master/examples/mascots.md)
* [Icons](https://sphinx-theme.scylladb.com/master/examples/icons.md)