Document the db:check-migrations timestamp check and skip label scope

Andrew Dunnrequested to merge
docs/dbcheck-migrations-skip-label-scope-v2 into master

What does this MR do?

This page is where a contributor looks up what db:check-migrations checks and how to get past a failure. It lists three of the job's five checks, not the timestamp check, and says the pipeline:skip-check-migrations label skips the job. A contributor whose job fails on a migration more than three weeks old finds nothing on the page to explain it. The label looks like the way through, but it turns off the schema validation only, so the job fails again.

A backport to a stable branch meets the same check. Every migration it adds to the target branch is held to the limit, and the label cannot lift it.

After this change:

  • The page lists all five checks in the order the job runs them, adding the timestamp check (with the 21-day limit and a note that the job measures the age when it runs) and the ignored-columns check.
  • The page says the label skips the schema dump comparisons and the db/schema_migrations diff, and that the timestamp and ignored-columns checks still run.
  • The migration style guide says that the db:check-migrations job enforces the three-week limit on migration timestamps, measured when the job runs.
flowchart TD
  job["db:check-migrations"] --> ts["scripts/validate_migration_timestamps"]
  ts -->|"future timestamp, or an added migration older than 21 days"| fail["job fails"]
  ts -->|passes| schema["scripts/validate_migration_schema"]
  schema --> ign["validate_ignore_columns!"]
  ign -->|"column not ignored in its model"| fail
  ign --> label{"label present?"}
  label -->|yes| skip["return: schema validation skipped"]
  label -->|no| checks["rollback, migrate and schema_migrations checks"]

How to verify

Each line below is at commit 9d4cbde6.

  • The job runs the timestamp check, then the schema validation: .gitlab/ci/database.gitlab-ci.yml lines 167-168.
  • The schema validator is the only code that reads the label (line 22 and lines 62-66, and an exact-phrase git grep for the label finds only specs and documentation besides). It returns after validate_ignore_columns! has run (lines 47-53).
  • The timestamp checker reads no label. Its limit is three weeks, compared with the time the job runs, and it applies to migrations the MR adds to the target branch.
  • The style guide edit is in its Migration timestamp age section, which the page now links to.
  • On a new branch from master in a checkout of this repository at that commit, commit a migration dated more than three weeks ago and run CI_MERGE_REQUEST_TARGET_BRANCH_NAME=master CI_MERGE_REQUEST_LABELS=pipeline:skip-check-migrations scripts/validate_migration_timestamps. It exits 1 with "has a timestamp older than three weeks", the same as without the label. With a current timestamp it exits 0.
  • On a new branch from master in a full checkout of this repository at that commit, commit a migration whose change method calls remove_column :projects, :dbcheck_example and run CI_MERGE_REQUEST_TARGET_BRANCH_NAME=master CI_MERGE_REQUEST_LABELS=pipeline:skip-check-migrations scripts/validate_migration_schema. It exits 1 with "Project: dbcheck_example". After you add ignore_column :dbcheck_example to app/models/project.rb, it exits 0 after "Label pipeline:skip-check-migrations is present, skipping schema validation", without running any database command.

Related issues

Merge request 241032 added the three-week limit to the timestamp checker. It changed no documentation.

Author's checklist

If you are a GitLab team member and only adding documentation, do not add any of the following labels:

  • ~"frontend"
  • ~"backend"
  • ~"type::bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.

An AI coding assistant wrote this change and this description. It checked each code claim against the source at commit 9d4cbde6, ran the project's Vale and markdownlint-cli2 configurations on the changed pages with no findings on the changed lines, and ran scripts/validate_migration_timestamps and scripts/validate_migration_schema from that commit under Ruby 3.4.10, as the last two steps above describe.

Edited by Bojan Marjanovic

Merge request reports