From 0b462e7aac44fe445f7da802f617389610351db3 Mon Sep 17 00:00:00 2001
From: Li Chaoran <pkwarcraft@gmail.com>
Date: Wed, 28 Jun 2023 10:19:30 +0800
Subject: [PATCH] add how to rename chroot doc

Signed-off-by: Li Chaoran <pkwarcraft@gmail.com>
---
 doc/how_to_rename_chroot.rst      | 50 +++++++++++++++++++++++++++++++
 doc/maintenance_documentation.rst |  1 +
 doc/seeddb.rst                    |  2 +-
 3 files changed, 52 insertions(+), 1 deletion(-)
 create mode 100644 doc/how_to_rename_chroot.rst

diff --git a/doc/how_to_rename_chroot.rst b/doc/how_to_rename_chroot.rst
new file mode 100644
index 000000000..e5f570eec
--- /dev/null
+++ b/doc/how_to_rename_chroot.rst
@@ -0,0 +1,50 @@
+.. _how_to_rename_chroot:
+
+How to rename a chroot
+================================
+
+In the openEuler copr instance, we unfortunately need to rename a chroot.
+
+The operations need to be done can be described as:
+
+* [backend]: symlinks all the old chroot dir in resultdir to the new one
+* [frontend]: change the os_release/os_version in frontend table mock_chroot
+* [builder]: add new mock chroot configs to all builder
+
+.. note::
+
+    After these operations are complete, a new chroot will be displayed at all frontend pages, and all the old repo config files should be still usable.
+
+To be more precisely, here are some operation details:
+
+*Suppose you have a chroot named* ``foo-bar-x86_64`` *and want to rename it to* ``new-foo_bar-x86_64``
+
+For backend
+--------------
+Login as copr user to backend node, and run:
+
+.. code-block:: console
+
+    $ /usr/bin/copr-rename-chroot --real-run  --pair foo-bar-x86_64:new-foo_bar-x86_64
+
+Explain: the ``/usr/bin/copr-rename-chroot`` script will rename the dir in ``destdir`` from ``foo-bar-x86_64`` to ``new-foo_bar-x86_64``
+
+.. warning::
+
+    You may note the ``--real-run`` arguement, without it the script will perform a dry-run and just print the operations out.
+
+    Run the command without ``real-run`` until you make sure all the operations are expected!
+
+For frontend
+--------------
+Login to the frontend database and run:
+
+.. code-block:: sql
+
+    coprdb# UPDATE mock_chroot SET os_version='foo_bar', os_release='new' WHERE os_version='foo' AND os_release='bar' AND arch='x86_64'
+
+Explain: the SQL will rename the old chroot which name is ``foo-bar-x86_64`` to ``new-foo_bar-x86_64`` in database, this operation will make webUI&copr-cli see the new chroot.
+
+For builder
+--------------
+Update your mock package to ensure the ``new-foo_bar-x86_64.cfg`` existed!
diff --git a/doc/maintenance_documentation.rst b/doc/maintenance_documentation.rst
index d0e3eee91..f375a16df 100644
--- a/doc/maintenance_documentation.rst
+++ b/doc/maintenance_documentation.rst
@@ -13,6 +13,7 @@ This section contains information about maintenance topics. You may also be inte
    how_to_upgrade_builders
    how_to_upgrade_persistent_instances
    How to manage active chroots <how_to_manage_chroots>
+   How to rename chroots <how_to_rename_chroot>
 
 
 .. toctree::
diff --git a/doc/seeddb.rst b/doc/seeddb.rst
index 29cbc6c0e..473c446d5 100644
--- a/doc/seeddb.rst
+++ b/doc/seeddb.rst
@@ -1,6 +1,6 @@
 .. _seeddb:
 
-Populate DB with pruduction data
+Populate DB with production data
 ================================
 
 While setting your local development environment, you might want to