Frozen Buckets; or, Why Won't My Bucketed Item Move?

Recently I was helping a coworker fix a bug related to the item paths within a bucket. Specifically, we were trying to dynamically change the path based on a field on the item (to make sure the date-based path matched the publish-date field set by the author) using the steps outlined by John West at this blog post. No matter what we did, the item refused to move! We googled, we asked around, we double and tripled checked the code, but nothing seemed to work.

Finally (perhaps belatedly), we started decompiling the Sitecore bucketing code responsible for the actual moving of the item. Lo and behold, we found this method in Sitecore.Buckets.dll:

internal static bool IsLockedChildRelationship(this Item item)
  if (item != null && item.Fields[Sitecore.Buckets.Util.Constants.ShouldNotOrganizeInBucket] != null)
    return item.Fields[Sitecore.Buckets.Util.Constants.ShouldNotOrganizeInBucket].Value == "1";
  return true;

That Sitecore.Buckets.Util.Constants.ShouldNotOrganizeInBucket property is an ID that refers to the field of the same name:

Lock child relationship - Maintains the hierarchical relationship between this item and its children when this item is stored in an item bucket

It's nice when help text appears in the right place; now, only if it was more clear.

Once we unchecked that box, our code properly moved items to new paths inside the bucket! We spent an embarrassingly long time troubleshooting before finding this field; don't make the same mistake we did!