Upgrading from 1.7 to 1.8¶

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.

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:

   # Clean commands
   .PHONY: clean
   clean:
       rm -rf $(BUILDDIR)/*
       # rm -f poetry.lock
   

3. Add the following dependabot.yml configuration file in the .github directory:

   version: 2
   updates:
   - package-ecosystem: "pip"
     directory: "/docs"
     schedule:
       interval: "daily"
     ignore:
     - dependency-name: "*"
     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.

4. In the docs/pyproject.toml file, set Poetry to use the non-package mode:

   [tool.poetry]
   name = "scylla"
   description = "Scylla Documentation"
   version = "4.3.0"
   authors = ["ScyllaDB Contributors"]
   package-mode = false
   

5. 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:

   (...)
   
   [tool.poetry.dependencies]
   python = "^3.10"
   pygments = "^2.18.0"
   sphinx-scylladb-theme = "^1.6.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"
   
   (...)
   

6. In the same docs/pyproject.toml file, update the poetry dependency to version 1.8.0:

   (...)
   [build-system]
   requires = ["poetry>=1.8.0"]
   build-backend = "poetry.masonry.api"
   

7. 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

• Icons