Merge pull request #9167 from nextcloud/migration-description

Add human readable description to migration steps

core/Command/Db/Migrations/StatusCommand.php

@@ -58,7 +58,14 @@ class StatusCommand extends Command implements CompletionAwareInterface {
 
 		$infos = $this->getMigrationsInfos($ms);
 		foreach ($infos as $key => $value) {
-			$output->writeln("    <comment>>></comment> $key: " . str_repeat(' ', 50 - strlen($key)) . $value);
+			if (is_array($value)) {
+				$output->writeln("    <comment>>></comment> $key:");
+				foreach ($value as $subKey => $subValue) {
+					$output->writeln("        <comment>>></comment> $subKey: " . str_repeat(' ', 46 - strlen($subKey)) . $subValue);
+				}
+			} else {
+				$output->writeln("    <comment>>></comment> $key: " . str_repeat(' ', 50 - strlen($key)) . $value);
+			}
 		}
 	}
 
@@ -96,6 +103,7 @@ class StatusCommand extends Command implements CompletionAwareInterface {
 
 		$numExecutedUnavailableMigrations = count($executedUnavailableMigrations);
 		$numNewMigrations = count(array_diff(array_keys($availableMigrations), $executedMigrations));
+		$pending = $ms->describeMigrationStep('lastest');
 
 		$infos = [
 			'App'								=> $ms->getApp(),
@@ -110,6 +118,7 @@ class StatusCommand extends Command implements CompletionAwareInterface {
 			'Executed Unavailable Migrations'	=> $numExecutedUnavailableMigrations,
 			'Available Migrations'				=> count($availableMigrations),
 			'New Migrations'					=> $numNewMigrations,
+			'Pending Migrations'				=> count($pending) ? $pending : 'None'
 		];
 
 		return $infos;

core/Migrations/Version14000Date20180129121024.php

@@ -30,6 +30,13 @@ use OCP\Migration\IOutput;
  * Delete the admin|personal sections and settings tables
  */
 class Version14000Date20180129121024 extends SimpleMigrationStep {
+	public function name(): string {
+		return 'Drop obsolete settings tables';
+	}
+
+	public function description(): string {
+		return 'Drops the following obsolete tables: "admin_sections", "admin_settings", "personal_sections" and "personal_settings"';
+	}
 
 	/**
 	 * @param IOutput $output

core/Migrations/Version14000Date20180404140050.php

@@ -41,6 +41,14 @@ class Version14000Date20180404140050 extends SimpleMigrationStep {
 		$this->connection = $connection;
 	}
 
+	public function name(): string {
+		return 'Add lowercase user id column to users table';
+	}
+
+	public function description(): string {
+		return 'Adds "uid_lower" column to the users table and fills the column to allow indexed case-insensitive searches';
+	}
+
 	/**
 	 * @param IOutput $output
 	 * @param \Closure $schemaClosure The `\Closure` returns a `ISchemaWrapper`

lib/private/DB/MigrationService.php

@@ -386,15 +386,37 @@ class MigrationService {
 		}
 	}
 
+	/**
+	 * Get the human readable descriptions for the migration steps to run
+	 *
+	 * @param string $to
+	 * @return string[] [$name => $description]
+	 */
+	public function describeMigrationStep($to = 'latest') {
+		$toBeExecuted = $this->getMigrationsToExecute($to);
+		$description = [];
+		foreach ($toBeExecuted as $version) {
+			$migration = $this->createInstance($version);
+			if ($migration->name()) {
+				$description[$migration->name()] = $migration->description();
+			}
+		}
+		return $description;
+	}
+
 	/**
 	 * @param string $version
-	 * @return mixed
+	 * @return IMigrationStep
 	 * @throws \InvalidArgumentException
 	 */
 	protected function createInstance($version) {
 		$class = $this->getClass($version);
 		try {
 			$s = \OC::$server->query($class);
+
+			if (!$s instanceof IMigrationStep) {
+				throw new \InvalidArgumentException('Not a valid migration');
+			}
 		} catch (QueryException $e) {
 			if (class_exists($class)) {
 				$s = new $class();
@@ -414,9 +436,6 @@ class MigrationService {
 	 */
 	public function executeStep($version) {
 		$instance = $this->createInstance($version);
-		if (!$instance instanceof IMigrationStep) {
-			throw new \InvalidArgumentException('Not a valid migration');
-		}
 
 		$instance->preSchemaChange($this->output, function() {
 			return new SchemaWrapper($this->connection);

lib/public/Migration/IMigrationStep.php

@@ -29,6 +29,21 @@ use OCP\DB\ISchemaWrapper;
  * @since 13.0.0
  */
 interface IMigrationStep {
+	/**
+	 * Human readable name of the migration step
+	 *
+	 * @return string
+	 * @since 14.0.0
+	 */
+	public function name(): string;
+
+	/**
+	 * Human readable description of the migration steps
+	 *
+	 * @return string
+	 * @since 14.0.0
+	 */
+	public function description(): string;
 
 	/**
 	 * @param IOutput $output

lib/public/Migration/SimpleMigrationStep.php

@@ -29,6 +29,25 @@ use OCP\DB\ISchemaWrapper;
  * @since 13.0.0
  */
 abstract class SimpleMigrationStep implements IMigrationStep {
+	/**
+	 * Human readable name of the migration step
+	 *
+	 * @return string
+	 * @since 14.0.0
+	 */
+	public function name(): string {
+		return '';
+	}
+
+	/**
+	 * Human readable description of the migration step
+	 *
+	 * @return string
+	 * @since 14.0.0
+	 */
+	public function description(): string {
+		return '';
+	}
 
 	/**
 	 * @param IOutput $output