Address the review comments

Signed-off-by: Chenxiong Qi <[email protected]>

hack/validate-migration.sh

@@ -97,9 +97,11 @@ list_preprocessed_pipelines() {
     find "${WORK_DIR}/pipelines" -type f -name "*.yaml"
 }
 
-# Migration script should run without errors (0 exit code) on the pre-latest default pipeline.
-# after performing migration, the pipeline yaml should be valid (yaml and pipeline definition)
-# Test should run on all pipelines (docker, FBC and their trusted artifacts and remote versions)
+# Check the migration does not break build pipelines.
+# Only the pipelines included in the build pipeline config are checked.
+# This function checks two aspects:
+# - whether the migration file exits successfully or not.
+# - whether the migration file modifies a pipeline. If nothing changed, it is treated a failure.
 check_apply_on_pipelines() {
     local -r migration_file=$1
     local -r run_log_file=$(mktemp --suffix=-migration-run-test)
@@ -179,6 +181,10 @@ resolve_migrations_parent_dir() {
     echo "${dir_path%/*}"  # remove path component migrations/
 }
 
+# Check a migration file is included in a task version-specific directory.
+# Each task version has its own migrations. Developers have to create
+# migrations/ directory under a specific task version directory, for example
+# task/buildah/0.2/migrations/.
 check_migrations_is_in_task_version_specific_dir() {
     local -r migration_file=$1
     local -r parent_dir=$(resolve_migrations_parent_dir "$migration_file")
@@ -191,6 +197,8 @@ check_migrations_is_in_task_version_specific_dir() {
 
 # Check that version within the migration file name must match the task version
 # in task label .metadata.labels."app.kubernetes.io/version".
+# When a migration file is committed, the task version must be bumped properly
+# accordingly which must match the version used in migration file name.
 check_version_match() {
     local -r migration_file=$1
     local -r task_dir=$(resolve_migrations_parent_dir "$migration_file")
@@ -251,7 +259,8 @@ list_migration_files() {
                     echo "$origin_path"
                     ;;
                 D | M)
-                    echo "It is not allowed to delete or modify existing migration file: $origin_path" >&2
+                    echo "error: It is not allowed to delete or modify existing migration file: $origin_path" >&2
+                    echo "error: Please bump task version in the label '${LABEL_TASK_VERSION}' and create a new migration file." >&2
                     exit 1
                     ;;
                 *)