How to make property/enum names consistent without breaking everything?

Contributing to Blender
1

I noticed that the naming and descriptions of settings in text objects differs from the same names in the equivalent geometry node. For example, the setting called “Text Vertical Align” in text objects is called “Align Y” in the geometry node. What can/should I touch in the code so that I don’t break things?

I’m assuming from reading some of the code and documentation that the following is true:

  static const EnumPropertyItem rna_node_geometry_string_to_curves_align_x_items[] = {
// I know I can change the identifier, but should I?
      {GEO_NODE_STRING_TO_CURVES_ALIGN_X_LEFT,
// Changing this string would break everything?
       "LEFT",
       ICON_ALIGN_LEFT,
// This looks like what I can change, I should reuse the exact text used by the other property to ensure it is localized correctly?
       "Left",
// This looks like what I can change, I should reuse the exact text used by the other property to ensure it is localized correctly?
       "Align text to the left"},

// Changing this string would break everything?
  prop = RNA_def_property(srna, "align_x", PROP_ENUM, PROP_NONE);
// Changing this string would break everything?
  RNA_def_property_enum_sdna(prop, NULL, "align_x");
// I know I can change the identifier, but should I?
  RNA_def_property_enum_items(prop, rna_node_geometry_string_to_curves_align_x_items);
// I know I can change the identifier, but should I?
  RNA_def_property_enum_default(prop, GEO_NODE_STRING_TO_CURVES_ALIGN_X_LEFT);
// This looks like what I can change, I should reuse the exact text used by the other property to ensure it is localized correctly?
  RNA_def_property_ui_text(prop, "Align X", "");
2

GEO_NODE_STRING_TO_CURVES_ALIGN_X_LEFT is just defined index for preprocessing. It shouldn’t changed.

3

Changing this enum value identifier is fine, the underlying value (0 here) must not change though since it’s written to .blend files, so changing it breaks compatibility.

This string will be used as identifier for this enum value in the Python API. So changing it will break all scripts using it, internal C/C++ code should not be affected.

These are used for the UI, the former will be the default label the latter the tooltip description. It’s also the Python API description. Changing it is fine.
A good description for me is more important than having the translation right away. Plenty of translators will update the translation for their language before the release.

This string will be used as name for the enum property in the Python API (i.e. something.align_x). So changing it will break all scripts using it, similar to the enum value identifier above.

This string must match the property’s counterpart in the DNA struct, otherwise you get a compilation error. Changing the name in the DNA struct too needs special care, since it’s written to .blend files.

This is just the internal variable name, it’s fine to change. I’d keep it consistent with the RNA property name.

See enum value above.

Same as above, UI default label and tooltip description. Fine to change.

I suggest checking with the geometry nodes team to make sure a change like this would be accepted. The geometry nodes code is much newer than the text code in question. Nowadays naming is done more carefully, they may have further reasoning.

2 Likes