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. In the same file, remove the line $(POETRY) update from the setup command:

   .PHONY: setup
   setup:
       $(POETRY) install
       # $(POETRY) update
   

4. In the same file, add a new command to update Python dependencies:

   .PHONY: update
   update:
       $(POETRY) update
   

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

   version: 2
   updates:
     - package-ecosystem: "pip"
       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:

   [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:

   (...)
   
   [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:

   (...)
   [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:

   poetry lock --no-update
   

10. Preview the docs. Ensure sure they render without errors:

    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

• Icons