uuid:
  - value: 0c899647-4916-4ad6-bde0-5ae1f397cc13
langcode:
  - value: en
type:
  - target_id: daily_email
    target_type: node_type
    target_uuid: 8bde1f2f-eef9-4f2d-ae9c-96921f8193d7
revision_timestamp:
  - value: '2025-05-11T09:00:08+00:00'
revision_uid:
  - target_type: user
    target_uuid: b8966985-d4b2-42a7-a319-2e94ccfbb849
revision_log: {  }
status:
  - value: true
uid:
  - target_type: user
    target_uuid: b8966985-d4b2-42a7-a319-2e94ccfbb849
title:
  - value: 'Maintaining backward compatibility'
created:
  - value: '2024-07-30T00:00:00+00:00'
changed:
  - value: '2025-05-11T09:00:08+00:00'
promote:
  - value: false
sticky:
  - value: false
default_langcode:
  - value: true
revision_translation_affected:
  - value: true
path:
  - alias: /daily/2024/07/30/maintaining-backward-compatibility
    langcode: en
body:
  - value: |
      <p>I've recently decided I'm going to open source <a href="/presentations/building-build-configs">Build Configs tool</a> that I use to generate build configuration files for Drupal, Sculpin and Fractal projects.</p>

      <p>Inspired by <a href="/presentations/working-with-workspace">Workspace</a> and others, and based on previous versions of similar tools - most recently by <a href="https://github.com/ALT-F4-LLC/build-configs">TheAltF4Stream's project with the same name</a> (which is written in Rust and supports different template types) - I've been using this tool to manage configuration files for various personal, client and open-source projects.</p>

      <p>Before I open-source it, there are some changes I'd like to make, such as renaming some template types and updating the format and keys within the configuration file.</p>

      <p>Changes to the configuration file would be a breaking change and, whilst it's only me using it, I want my other projects to keep working and for me to continue supporting the prior versions - at least for now, so I want to make sure any changes are backward compatible.</p>

      <h2 id="how-it-works">How it works</h2>

      <p>There are four steps performed when generating files for a project:</p>

      <ul>
      <li>Create a final configuration object from the project's configuration file as well as any defaults.</li>
      <li>Validate the final configuration.</li>
      <li>Create a list of files to generate.</li>
      <li>Generate the files.</li>
      </ul>

      <p>If I change <code>sculpin</code> to <code>sculpin-site</code> in a configuration file, for example, it will fail the validation step.</p>

      <p>But, I have an opportunity within the first step to perform any normalisation that's needed and to provide a compatibility layer - such as changing <code>sculpin-site</code>, which is an invalid value, to <code>sculpin</code>.</p>

      <p>I also renamed <code>symfony</code> to <code>symfony-cli</code> by performing the same step.</p>

      <p>This means the validation step will receive valid data that it can use and the new changes have been encapsulated within a single step of the process. I haven't needed to change any code elsewhere.</p>

      <p>I can also add deprecation warnings if legacy values are used.</p>

      <h2 id="here%27s-the-thing">Here's the thing</h2>

      <p>Similar to feature flags, this is temporary code that will later be removed when I'm ready to remove the compatibility layer, similar to how <code>drupal_set_message()</code> was deprecated and changed to use the <code>Messenger</code> service before being removed in Drupal 9.</p>

      <p>In the future, I can refactor the internal logic to use a different approach and when I'm ready, eventually remove the compatibility layer and tag a new major version with the breaking changes.</p>

              
    format: full_html
    processed: |
      <p>I've recently decided I'm going to open source <a href="/presentations/building-build-configs">Build Configs tool</a> that I use to generate build configuration files for Drupal, Sculpin and Fractal projects.</p>

      <p>Inspired by <a href="/presentations/working-with-workspace">Workspace</a> and others, and based on previous versions of similar tools - most recently by <a href="https://github.com/ALT-F4-LLC/build-configs">TheAltF4Stream's project with the same name</a> (which is written in Rust and supports different template types) - I've been using this tool to manage configuration files for various personal, client and open-source projects.</p>

      <p>Before I open-source it, there are some changes I'd like to make, such as renaming some template types and updating the format and keys within the configuration file.</p>

      <p>Changes to the configuration file would be a breaking change and, whilst it's only me using it, I want my other projects to keep working and for me to continue supporting the prior versions - at least for now, so I want to make sure any changes are backward compatible.</p>

      <h2 id="how-it-works">How it works</h2>

      <p>There are four steps performed when generating files for a project:</p>

      <ul>
      <li>Create a final configuration object from the project's configuration file as well as any defaults.</li>
      <li>Validate the final configuration.</li>
      <li>Create a list of files to generate.</li>
      <li>Generate the files.</li>
      </ul>

      <p>If I change <code>sculpin</code> to <code>sculpin-site</code> in a configuration file, for example, it will fail the validation step.</p>

      <p>But, I have an opportunity within the first step to perform any normalisation that's needed and to provide a compatibility layer - such as changing <code>sculpin-site</code>, which is an invalid value, to <code>sculpin</code>.</p>

      <p>I also renamed <code>symfony</code> to <code>symfony-cli</code> by performing the same step.</p>

      <p>This means the validation step will receive valid data that it can use and the new changes have been encapsulated within a single step of the process. I haven't needed to change any code elsewhere.</p>

      <p>I can also add deprecation warnings if legacy values are used.</p>

      <h2 id="here%27s-the-thing">Here's the thing</h2>

      <p>Similar to feature flags, this is temporary code that will later be removed when I'm ready to remove the compatibility layer, similar to how <code>drupal_set_message()</code> was deprecated and changed to use the <code>Messenger</code> service before being removed in Drupal 9.</p>

      <p>In the future, I can refactor the internal logic to use a different approach and when I'm ready, eventually remove the compatibility layer and tag a new major version with the breaking changes.</p>

              
    summary: null
field_daily_email_cta: {  }