Plugin Migration

Rock RMS Plugin Migration Creator & Reviewer

You are creating or reviewing a plugin migration (hotfix) in the Rock RMS codebase. Plugin migrations are single .cs files in Rock/Plugin/HotFixes/ with sequential numbering and a [MigrationNumber] attribute. They inherit from Rock.Plugin.Migration and provide Up() and Down() methods.

The user's request: $ARGUMENTS

Reference Routing Table

Load reference files progressively — only when needed.

Do NOT read all files upfront. Read hotfix-patterns.md always for write mode; read others only when their trigger condition is met.

Step 1 — Understand the Request and Determine Mode

Parse what the migration needs to do and determine which mode to use:

Write mode — The user describes what the migration should accomplish, or says "create", "write", "new". Proceed to Step 2 (Write Mode).

Review mode — The user says "review", "check", "audit", or names an existing migration file. Proceed to Step 2 (Review Mode).

Migration categories (for write mode):

• Data fix — UPDATE/INSERT/DELETE records to correct bad data
• Configuration change — update page layouts, block settings, HTML content
• Attribute update — add/modify block type attributes, person attributes, defined values
• Stored procedure update — create or alter a stored procedure
• Post-update job — add a run-once service job
• Block type change — add/update/remove block types and entity types

If ambiguous, ask clarifying questions before proceeding.

Write Mode

Step 2 — Determine Migration Number and Version

1. Scan Rock/Plugin/HotFixes/ for the highest existing migration number:

   Glob: Rock/Plugin/HotFixes/*.cs
   

   Parse the leading number from each filename (e.g., 279_MigrationRollupsForV18_3_0_1.cs → 279).

2. Next number = highest + 1

3. Determine minimum Rock version:

   • If the user specifies a version, use it
   • If working on a specific release branch, use that version
   • If unclear, ask the user

4. Generate filename: {number}_{PascalCaseDescription}.cs

   • Class name = the PascalCase description (without the number prefix)

Step 3 — Research the Schema

Before writing the migration, you must understand the actual database schema. Do not guess column names, types, or relationships.

Read the model files for every entity you're touching:

• Entity models: Rock/Model/[Domain]/[Entity]/[Entity].cs
• If not found, search: Rock/Model/**/{EntityName}.cs
• Look for: [Required] (NOT NULL), [MaxLength(N)] (string limits), FK navigation properties, enum-typed properties

Understand Rock's standard column patterns:

• Every entity inheriting Model<T> has: Id (identity), Guid (uniqueidentifier), IsSystem (bit), CreatedDateTime, ModifiedDateTime, CreatedByPersonAliasId, ModifiedByPersonAliasId
• Audit FK columns (CreatedByPersonAliasId, ModifiedByPersonAliasId) reference [PersonAlias], NOT [Person]
• Campus FK columns typically use ON DELETE SET NULL
• [Order] columns should be calculated from existing max, not hardcoded

Check SystemGuid files: Rock/SystemGuid/{EntityType}.cs for well-known GUIDs

Check enum definitions: Rock.Enums/[Domain]/ for integer values of enum-typed columns

Load references:

• Read references/hotfix-patterns.md for common patterns and complete examples
• Read references/methods-and-sql.md if using RockMigrationHelper, stored procedures, or complex SQL

Step 4 — Write the Migration File

Use the following template. The copyright block, namespace, class structure, and XML doc comments must match exactly:

// <copyright>
// Copyright by the Spark Development Network
//
// Licensed under the Rock Community License (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.rockrms.com/license
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// </copyright>

using System;

namespace Rock.Plugin.HotFixes
{
    /// <summary>
    /// [Description of what this migration does]
    /// </summary>
    /// <seealso cref="Rock.Plugin.Migration" />
    [MigrationNumber( {number}, "{minRockVersion}" )]
    public class {ClassName} : Migration
    {
        /// <summary>
        /// Operations to be performed during the upgrade process.
        /// </summary>
        public override void Up()
        {
            // Migration logic here
        }

        /// <summary>
        /// Operations to be performed during the downgrade process.
        /// </summary>
        public override void Down()
        {
            // Down migrations are not yet supported in plug-in migrations.
        }
    }
}

For available methods (Sql(), SqlScalar(), RockMigrationHelper.*, EF wrappers), SQL formatting rules, string escaping, stored procedure patterns, and code organization conventions, consult references/methods-and-sql.md.

Step 5 — Validate

Read references/common-pitfalls.md and run through the pre-finalization checklist before presenting.

Output: Write the .cs file to Rock/Plugin/HotFixes/ and show the contents in conversation for review.

Review Mode

Step 2 (Review Mode) — Find the Migration

1. If $ARGUMENTS names a specific file or migration number, find it in Rock/Plugin/HotFixes/
2. Otherwise, find the most recently created .cs file (highest number prefix):

   Glob: Rock/Plugin/HotFixes/*.cs
   

3. Read the full .cs file

Step 3 (Review Mode) — Research for Comparison

Before reviewing, gather the context needed to judge correctness:

• Read the actual model files (Rock/Model/[Domain]/[Entity]/[Entity].cs) for every entity the migration touches — verify column types, [Required], [MaxLength], nullable, FK navigation properties
• Check Rock/SystemGuid/ files if the migration references GUIDs
• Check Rock.Enums/[Domain]/ if the migration uses enum integer values
• Read references/hotfix-patterns.md for expected patterns
• Read references/common-pitfalls.md for known failure modes

Step 4 (Review Mode) — Audit the Migration

Run through the pre-finalization checklist from references/common-pitfalls.md, plus these additional review-specific checks:

Structural checks

• Class inherits Rock.Plugin.Migration
• Copyright header and XML doc comments present
• [MigrationNumber] attribute present with valid number and version

Cross-reference checks

• If migration references SystemGuid constants, verify they exist
• If migration uses RockMigrationHelper methods, verify parameter order matches method signatures
• Check for potential conflicts with other recent migrations

Step 5 (Review Mode) — Report Findings

Present findings using severity levels:

Format each finding as:

[SEVERITY-N] Short title
Description of the issue and what to change.
Line/area: [where in the file]

End with a summary: total findings by severity and a go/no-go recommendation.

If the migration is clean: Say so. Don't invent issues to fill a report.

Examples

Example 1: Fix HTML content

User says: "Fix the SQL runner warning block HTML to use proper Bootstrap classes"

Actions:

1. Determine next migration number
2. Research the HtmlContent entity model
3. Write Sql() with UPDATE on [HtmlContent] by known Guid

Result: File written to Rock/Plugin/HotFixes/280_FixSqlRunnerWarningHtml.cs with a Sql() UPDATE on [HtmlContent] targeting the known Guid.

Example 2: Add a block type attribute

User says: "Add a 'ShowHeader' boolean attribute to the PersonBio block type"

Actions:

1. Look up PersonBio block type Guid in SystemGuid
2. Use RockMigrationHelper.AddOrUpdateBlockTypeAttribute()

Result: File written with RockMigrationHelper.AddOrUpdateBlockTypeAttribute() call using the PersonBio block type Guid from Rock/SystemGuid/BlockType.cs.

Example 3: Add a post-update service job

User says: "Add a run-once job to fix broken achievement types from the v18.0 bug"

Actions:

1. Add using Rock.Model; for typeof() reference
2. Use RockMigrationHelper.AddPostUpdateServiceJob() with job type, cron expression, and SystemGuid

Result: File written with AddPostUpdateServiceJob() using typeof(Rock.Jobs.PostUpdateJobs.PostV183UpdateAchievementTypes).FullName and the correct SystemGuid.

Example 4: Update a stored procedure

User says: "Update the SynchronizeListRecipients proc to exclude archived members"

Actions:

1. Read references/methods-and-sql.md for stored procedure pattern
2. Save/restore ANSI_NULLS and QUOTED_IDENTIFIER
3. Drop existing procedure if exists
4. Create updated procedure (inline or via HotFixMigrationResource)

Result: File written with the full stored procedure pattern including session setting save/restore and IF EXISTS guard.

Example 5: Review an existing plugin migration

User says: "review my plugin migration" or /plugin-migration review

Actions:

1. Find the most recent migration in Rock/Plugin/HotFixes/
2. Read the .cs file
3. Enter Review Mode: research models, audit against checklist + common pitfalls
4. Report findings by severity (CRITICAL/WARNING/NOTE) with go/no-go recommendation

Result: Severity-based findings report with actionable fix suggestions and a go/no-go recommendation.

Troubleshooting

Migration number conflict: Another developer may have used that number. Re-scan the directory for the latest number after pulling latest.

"Down migrations are not yet supported": This is the standard convention for plugin migrations. Keep the comment in Down() as-is unless the migration has a natural reverse (like stored procedure changes).

Large SQL won't fit inline: For stored procedures or large scripts, use HotFixMigrationResource embedded resources. Add the SQL to the .resx file and reference it as HotFixMigrationResource._NNN_Description_ProcedureName.

RockMigrationHelper method not found: Check Rock/Data/MigrationHelper.cs for the exact method signature and overloads.

String escaping errors at runtime: Single quotes must be doubled in SQL within C# strings ('O''Brien'). Curly braces must be doubled in $@"..." strings ({{, }}). See references/common-pitfalls.md for full examples.

Wrong block type method (data loss risk): Never use UpdateBlockTypeByGuid() for Obsidian or Mobile blocks — it can delete entity-based block types. Use AddOrUpdateEntityBlockType() instead. See references/common-pitfalls.md for details.

Missing using Rock.Model;: Required when using typeof() for job types or entity types. Without it, the type reference may not resolve correctly.