52 lines
2.7 KiB
Markdown
52 lines
2.7 KiB
Markdown
---
|
|
title: Maintaining backward compatibility
|
|
date: 2024-07-30
|
|
permalink: daily/2024/07/30/maintaining-backward-compatibility
|
|
tags:
|
|
- software-development
|
|
- php
|
|
- symfony
|
|
- drupal
|
|
- open-source
|
|
cta: ~
|
|
snippet: |
|
|
How I approach maintaining backward compatibility in projects.
|
|
---
|
|
|
|
I've recently decided I'm going to open source [Build Configs tool][0] that I use to generate build configuration files for Drupal, Sculpin and Fractal projects.
|
|
|
|
Inspired by [Workspace][1] and others, and based on previous versions of similar tools - most recently by [TheAltF4Stream's project with the same name][2] (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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## How it works
|
|
|
|
There are four steps performed when generating files for a project:
|
|
|
|
- Create a final configuration object from the project's configuration file as well as any defaults.
|
|
- Validate the final configuration.
|
|
- Create a list of files to generate.
|
|
- Generate the files.
|
|
|
|
If I change `sculpin` to `sculpin-site` in a configuration file, for example, it will fail the validation step.
|
|
|
|
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 `sculpin-site`, which is an invalid value, to `sculpin`.
|
|
|
|
I also renamed `symfony` to `symfony-cli` by performing the same step.
|
|
|
|
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.
|
|
|
|
I can also add deprecation warnings if legacy values are used.
|
|
|
|
## Here's the thing
|
|
|
|
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 `drupal_set_message()` was deprecated and changed to use the `Messenger` service before being removed in Drupal 9.
|
|
|
|
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.
|
|
|
|
[0]: {{site.url}}/presentations/building-build-configs
|
|
[1]: {{site.url}}/presentations/working-with-workspace
|
|
[2]: https://github.com/ALT-F4-LLC/build-configs
|