Creating shared fields has two major parts. First the field's configuration is created, and then it's added to the cgov_core installation profile in order to make it available when the CancerGov Drupal instance is set up.

Creating the field configuration

1. Export a baseline config
   • From inside the web container, run the command:

     drupal config:export --directory="../files-private/baseline-config" --remove-uuid --remove-config-hash
     

2. Launch the Drupal UI
3. In the Drupal UI, create a throwaway type.
   1. Structure > Content types > Add content type
   2. Enter a name (e.g. "Junk Type")
   3. Click "Save and manage fields."
4. Delete the automatically created body field.
   1. Choose "Delete" from the dropdown button in the "Operations" column.
   2. Confirm the deletion.
5. Click the "Add field" button.
6. Choose a type for the new field.
7. Enter the label (e.g. "My Text Field").
   • Note: The label becomes the default "Machine name", you can edit this as needed. If the label was "My Text Field" then the field's machine name would be my_text_field. You'll need this below.
8. Click the "Save and continue" button.
9. Set other field settings as needed.
10. Click the "Save field settings" button.
    • NOTE: There's no need to set the "Help text" at this point. Help text is actually defined when the field is attached to a node type.
11. Click the "Save settings" button.
    • At this point, you'll be back to the type's list of fields.
12. Export the updated configuration.
    • From inside the web container, run the command:

      drupal config:export --directory="../files-private/feature-config" --remove-uuid --remove-config-hash`
      

    • NOTE: This is almost the same command as before, but the directory argument is changed.

Preserving the field configuration

The configuration export step places a collection of YAML files in $GIT_ROOT/files-private/feature-config. You can compare this with the set in $GIT_ROOT/files-private/baseline-config to see what's changed.

For the example of creating "My Text Field" (see above), the feature-config directory will contain a new file field.storage.node.field_intro_text.yml. This is the field's storage definition. (There will also be some other new and modified files associated with the new "Junk Type" node type as well connecting the node type with the field, but those are a separate discussion.)

1. Copy field.storage.node.field_intro_text.yml to the $GIT_ROOT/docroot/profiles/custom/cgov_site/modules/custom/cgov_core/config/install/ directory.
2. Edit the new file to resemble the structure

    langcode: en
    status: true
    dependencies:
      module:
        - node
        - text
      enforced:
        module:
          - cgov_core
    id: node.field_my_text_field
    field_name: field_my_text_field
    entity_type: node
    type: text_long
    settings: {  }
    module: text
    locked: false
    cardinality: 1
    translatable: true
    indexes: {  }
    persist_with_no_fields: true
    custom_storage: false
   

   • The changes you are making are:
     • Add the enforced: property to note that the field is controlled by cgov_core.
     • Change the persist_with_no_fields value to true so the field won't be immediately deleted because it's not being used by any node types.
3. Add a test for the existence of the field to CGovFieldStorageTest, located in docroot/profiles/custom/cgov_site/modules/custom/cgov_core/tests/src/Kernel/FieldStorage/