From 3d8e410fc3874f6ef8e33513d331bce8a8c8e865 Mon Sep 17 00:00:00 2001 From: Tobia De Koninck Date: Sun, 23 Jul 2017 11:40:43 +0200 Subject: [PATCH 1/3] Add documentation about repair stesp Signed-off-by: Tobia De Koninck --- developer_manual/app/index.rst | 7 ++ developer_manual/app/repair.rst | 111 ++++++++++++++++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 developer_manual/app/repair.rst diff --git a/developer_manual/app/index.rst b/developer_manual/app/index.rst index 4469e8789..f7301d3ca 100644 --- a/developer_manual/app/index.rst +++ b/developer_manual/app/index.rst @@ -35,6 +35,7 @@ backgroundjobs settings logging + repair testing publishing code_signing @@ -149,6 +150,12 @@ Log to the :file:`data/nextcloud.log`: * :doc:`logging` +Repair steps +------------ +Repair steps can be used to run code at various stages in app installation, uninstallation, migration ... + +* :doc:`repair` + Testing ------- Write automated tests to ensure stability and ease maintenance: diff --git a/developer_manual/app/repair.rst b/developer_manual/app/repair.rst new file mode 100644 index 000000000..8afd34155 --- /dev/null +++ b/developer_manual/app/repair.rst @@ -0,0 +1,111 @@ +======= +Repair Steps +======= + +Repair steps are methods which are executed by Nextcloud on certain +events which directly affect the app. You can use these repair steps to run +code when your app is installed, uninstalled, upgraded etc. It's called repair +steps because they are frequently used to fix things automatically. + +.. note:: Don't use the ``install.php``, ``update.php`` and ``preupdate.php`` files anymore! This method is deprecated and is known to cause issues. + + +Creating a repair step +====================== +A repair step is an implementation of the ``OCP\Migration\IRepairStep`` interface. +By convention these classes are placed in the **lib/Migration** directory. +The following repairstep will log a message when executed. + +.. code-block:: php + + logger = $logger; + } + + /** + * Returns the step's name + */ + public function getName() { + return 'A demonstration repair step!'; + } + + /** + * @param IOutput $output + */ + public function run(IOutput $output) { + $this->logger->warning("Hello world from MyRepairStep!", ["app" => "MyApp"]); + } + } + +Outputting information +~~~~~~~~~~~~~~~~~~~~~ +A repair step can generate information while running, using the +``OCP\Migration\IOutput`` parameter to the ``run`` method. +Using the ``info`` and ``warning`` methods a message can be shown in the console. +In orderto show a progressbar, firstly call the ``startProgress`` method. +The maximum number of steps can be adjusted by passing it as argument to the +``startProgress`` method. After every step run the ``advance`` method. When all steps are finished run the ``finishProgress`` +method. + +The following function will sleep for 10 seconds and show the progress: + +.. code-block:: php + + info("This step will take 10 seconds."); + $output->startProgress(10); + for ($i = 0; $i < 10; $i++) { + sleep(1); + $output->advance(1); + } + $output->finishProgress(); + } + +Register a repair-step +====================== +To register a repair-step in Nextcloud you have to define the repair-setp in the ``info.xml`` +file. The following example registers a repair-step which will be executed after installation +of the app: + +.. code-block:: xml + + + + myapp + My App + A test app + ... + + + OCA\MyApp\Migration\MyRepairStep + + + + + +Repair-step types +========================== +The following repair steps are available: + +* ``install`` This repair step will be executed when installing the app. This means it is executed every time the app is enabled (using the Web interface or the CLI). +* ``uninstall`` This repair step will be executed when uninstalling the app, and when disabling the app. +* ``pre-migration`` This repair step will be executed just before the database is migrated during an update of the app. +* ``post-migration`` This repair step will be executed just after the database is migrated during an update of the app. This repair step will also be executed when running the ``occ maintenance:repair`` command +* ``live-migration`` This repair step will be scheduled to be run in the background (e.g. using cron), therefore it is unpredictable when it will run. If the job isn't required right after the update of the app and the job would take a long time this is the best choice. From 42654591ba17f61b111a784c10f6dd9e19a4295d Mon Sep 17 00:00:00 2001 From: Tobia De Koninck Date: Sun, 13 Aug 2017 10:36:30 +0200 Subject: [PATCH 2/3] Fix style issues --- developer_manual/app/repair.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/developer_manual/app/repair.rst b/developer_manual/app/repair.rst index 8afd34155..d514558dd 100644 --- a/developer_manual/app/repair.rst +++ b/developer_manual/app/repair.rst @@ -1,6 +1,6 @@ -======= +============ Repair Steps -======= +============ Repair steps are methods which are executed by Nextcloud on certain events which directly affect the app. You can use these repair steps to run @@ -101,7 +101,7 @@ of the app: Repair-step types -========================== +================= The following repair steps are available: * ``install`` This repair step will be executed when installing the app. This means it is executed every time the app is enabled (using the Web interface or the CLI). From 23c11d16ec37fd5cb9d55ab77292c4537b257342 Mon Sep 17 00:00:00 2001 From: Tobia De Koninck Date: Mon, 14 Aug 2017 11:35:38 +0200 Subject: [PATCH 3/3] Fix some more style issues --- developer_manual/app/repair.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developer_manual/app/repair.rst b/developer_manual/app/repair.rst index d514558dd..3a71965df 100644 --- a/developer_manual/app/repair.rst +++ b/developer_manual/app/repair.rst @@ -54,9 +54,9 @@ Outputting information A repair step can generate information while running, using the ``OCP\Migration\IOutput`` parameter to the ``run`` method. Using the ``info`` and ``warning`` methods a message can be shown in the console. -In orderto show a progressbar, firstly call the ``startProgress`` method. +In order to show a progressbar, firstly call the ``startProgress`` method. The maximum number of steps can be adjusted by passing it as argument to the -``startProgress`` method. After every step run the ``advance`` method. When all steps are finished run the ``finishProgress`` +``startProgress`` method. After every step run the ``advance`` method. Once all steps are finished run the ``finishProgress`` method. The following function will sleep for 10 seconds and show the progress: