Add comments

Author: yzhoubk

db/migrate/20250930215317_add_two_terms.rb

@@ -1,3 +1,4 @@
+# Migration to add "Digital" and "Drawing" terms to the "Medium" facet.
 class AddTwoTerms < ActiveRecord::Migration[7.0]
   def up
     facet = Facet.find_by!(name: "Medium")

db/migrate/20250930220140_add_three_ordered_terms.rb

@@ -1,11 +1,20 @@
+# Migration summary:
+# After running `up`, the "Decade" facet will have terms:
+#   - "2000-2009" (ord: 11)
+#   - "2010-2019" (ord: 12)
+#   - "After 2020" (ord: 13)
+#   - "No Date" (ord: 14)
+#   - "After 1999" (ord: 15, to be removed after updating items_terms)
+# After running `down`, the "Decade" facet will have:
+#   - "No Date" (ord: 12)
+#   - "After 1999" (ord: 11)
+#   - The three new terms will be deleted.
+
 class AddThreeOrderedTerms < ActiveRecord::Migration[7.0]
   def up
     facet = Facet.find_by!(name: "Decade")
-
-    # Add and remove terms from facet "Decade", and reorder them.
-    # The term "After 1999" is no longer needed and will be removed 
-    # when all items_terms have been updated
     term  = Term.find_by!(facet: facet, value: "After 1999")
+    # NOTE: Ensure all related items_terms records are updated before removing "After 1999" to prevent orphaned references.
     term.update!(ord: 15)
     term  = Term.find_by!(facet: facet, value: "No Date")
     term.update!(ord: 14)