From 25b9a235d0bfa0764c7a5502416ab08d260e60ae Mon Sep 17 00:00:00 2001 From: Stanislav Zhuk Date: Wed, 19 Nov 2025 15:48:47 +0200 Subject: [PATCH 1/3] Update DDEV Add-on Maintenance Guide blog --- .../blog/ddev-add-on-maintenance-guide.md | 36 +++++++++++++++++-- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/src/content/blog/ddev-add-on-maintenance-guide.md b/src/content/blog/ddev-add-on-maintenance-guide.md index 2cc5e226..4cd4212b 100644 --- a/src/content/blog/ddev-add-on-maintenance-guide.md +++ b/src/content/blog/ddev-add-on-maintenance-guide.md @@ -1,8 +1,8 @@ --- title: "DDEV Add-on Maintenance Guide" pubDate: 2025-05-01 -modifiedDate: 2025-07-22 -modifiedComment: Added update checker script. +modifiedDate: 2025-11-19 +modifiedComment: Added new features from DDEV v1.24.10 summary: Maintaining an add-on involves regularly updating it to stay compatible with new features in both the upstream ddev-addon-template and DDEV itself. author: Stas Zhuk featureImage: @@ -72,11 +72,41 @@ These improve the quality of contributions and bug reports. Your add-on should encourage users to keep DDEV updated. The current recommendation is to add this stanza to `install.yaml`: ```yaml -ddev_version_constraint: ">= v1.24.3" +ddev_version_constraint: '>= v1.24.10' ``` This ensures compatibility and resolves known issues, such as those related to the [Mutagen Problem Report](open-source-for-the-win.md#mutagen-problemreport). +### Customizing `ddev describe` Output + +With DDEV v1.24.10, add-ons can now customize the output of the `ddev describe` with `x-ddev.describe-*` extension. + +[This feature](https://docs.ddev.com/en/stable/users/extend/custom-docker-services/#customizing-ddev-describe-output) is useful for showing credentials, URLs, or usage notes for custom services. + +Example: + +- https://github.com/ddev/ddev-redis/blob/main/docker-compose.redis.yaml + +### Changing `ddev ssh` Shell + +DDEV v1.24.10 also introduced the ability for add-ons to specify a custom shell for the `ddev ssh -s service` command using the [`x-ddev.ssh-shell`](https://docs.ddev.com/en/stable/users/extend/in-container-configuration/#changing-ddev-ssh-shell) extension. + +Example: + +- https://github.com/ddev/ddev-varnish/blob/main/docker-compose.varnish.yaml + +It's also useful to check if shell is available in the `tests/test.bats` file (where `service` is the name of the service container you want to test): + +```bash +health_checks() { + # Check that bash is available in the "service" container + run ddev exec -s service command -v bash + assert_success + assert_output --partial "bash" + # ... other health checks ... +} +``` + ### Add-on Badges The old `maintained` badge required yearly updates, which became a maintenance burden, especially for contributors with many add-ons. It's now replaced by a `last commit` badge. From bed232c9ffe0ec4f5ec7c7d2a8ab7ac9b760ee52 Mon Sep 17 00:00:00 2001 From: Stanislav Zhuk Date: Wed, 19 Nov 2025 15:52:03 +0200 Subject: [PATCH 2/3] prettier --- src/content/blog/ddev-add-on-maintenance-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/blog/ddev-add-on-maintenance-guide.md b/src/content/blog/ddev-add-on-maintenance-guide.md index 4cd4212b..efb9b92b 100644 --- a/src/content/blog/ddev-add-on-maintenance-guide.md +++ b/src/content/blog/ddev-add-on-maintenance-guide.md @@ -72,7 +72,7 @@ These improve the quality of contributions and bug reports. Your add-on should encourage users to keep DDEV updated. The current recommendation is to add this stanza to `install.yaml`: ```yaml -ddev_version_constraint: '>= v1.24.10' +ddev_version_constraint: ">= v1.24.10" ``` This ensures compatibility and resolves known issues, such as those related to the [Mutagen Problem Report](open-source-for-the-win.md#mutagen-problemreport). From 5a7e165ed10ddc33da7e93768a160b2ee25e3dbd Mon Sep 17 00:00:00 2001 From: Stanislav Zhuk Date: Wed, 19 Nov 2025 15:55:39 +0200 Subject: [PATCH 3/3] Move newer features to top --- .../blog/ddev-add-on-maintenance-guide.md | 88 +++++++++---------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/src/content/blog/ddev-add-on-maintenance-guide.md b/src/content/blog/ddev-add-on-maintenance-guide.md index efb9b92b..994cc3c8 100644 --- a/src/content/blog/ddev-add-on-maintenance-guide.md +++ b/src/content/blog/ddev-add-on-maintenance-guide.md @@ -42,31 +42,6 @@ Here are some high-level practices to follow: DDEV development is moving fast, and new features are introduced regularly. Here are some recent updates you should be aware of: -### `ddev get` Deprecation - -The classic `ddev get` command is deprecated in DDEV v1.23.5 and replaced by `ddev add-on get`. - -Huge thanks to [@GuySartorelli](https://github.com/GuySartorelli) for implementing this feature, and also for proactively updating many add-on `README.md` files. You've likely already seen a pull request for your add-on! - -### Better Testing with Bats Libraries - -While all add-ons use the [Bats](https://bats-core.readthedocs.io/en/stable/) framework for testing, many are still missing Bats libraries that simplify assertions and test writing. - -Consider adopting these libraries to enhance test clarity and maintainability. - -Example: - -- https://github.com/ddev/ddev-addon-template/blob/main/tests/test.bats - -### Issue and PR Templates - -Make sure your add-on includes: - -- [Issue templates](https://github.com/ddev/ddev-addon-template/tree/main/.github/ISSUE_TEMPLATE) -- [Pull request template](https://github.com/ddev/ddev-addon-template/blob/main/.github/PULL_REQUEST_TEMPLATE.md) - -These improve the quality of contributions and bug reports. - ### Recommending DDEV Version Constraints Your add-on should encourage users to keep DDEV updated. The current recommendation is to add this stanza to `install.yaml`: @@ -107,6 +82,50 @@ health_checks() { } ``` +### MutagenSync Annotation for Commands + +With DDEV v1.24.4, custom commands can now use the [`MutagenSync`](https://docs.ddev.com/en/stable/users/extend/custom-commands/#mutagensync-annotation) annotation. + +You should use this annotation if your `host` or `web` commands modify, add, or remove files in the project directory. It ensures that file sync is handled correctly when Mutagen is enabled, preventing unexpected behavior or sync delays. (It does no harm and causes no performance issues if Mutagen is not in use.) + +Example: + +- https://github.com/backdrop-ops/ddev-backdrop-bee/blob/main/commands/web/bee + +### Support for Optional Compose Profiles + +The same DDEV v1.24.4 release introduced support for [optional docker-compose profiles](https://docs.ddev.com/en/stable/users/extend/custom-compose-files/#optional-services), which can be used by add-ons to offer more flexible configuration. + +Example: + +- https://github.com/ddev/ddev-mongo/blob/main/docker-compose.mongo.yaml +- https://github.com/ddev/ddev-mongo/blob/main/commands/host/mongo-express + +### `ddev get` Deprecation + +The classic `ddev get` command is deprecated in DDEV v1.23.5 and replaced by `ddev add-on get`. + +Huge thanks to [@GuySartorelli](https://github.com/GuySartorelli) for implementing this feature, and also for proactively updating many add-on `README.md` files. You've likely already seen a pull request for your add-on! + +### Better Testing with Bats Libraries + +While all add-ons use the [Bats](https://bats-core.readthedocs.io/en/stable/) framework for testing, many are still missing Bats libraries that simplify assertions and test writing. + +Consider adopting these libraries to enhance test clarity and maintainability. + +Example: + +- https://github.com/ddev/ddev-addon-template/blob/main/tests/test.bats + +### Issue and PR Templates + +Make sure your add-on includes: + +- [Issue templates](https://github.com/ddev/ddev-addon-template/tree/main/.github/ISSUE_TEMPLATE) +- [Pull request template](https://github.com/ddev/ddev-addon-template/blob/main/.github/PULL_REQUEST_TEMPLATE.md) + +These improve the quality of contributions and bug reports. + ### Add-on Badges The old `maintained` badge required yearly updates, which became a maintenance burden, especially for contributors with many add-ons. It's now replaced by a `last commit` badge. @@ -139,25 +158,6 @@ Examples: - https://github.com/ddev/ddev-solr/blob/main/docker-compose.solr.yaml - https://github.com/ddev/ddev-opensearch/blob/main/docker-compose.opensearch.yaml -### MutagenSync Annotation for Commands - -With DDEV v1.24.4, custom commands can now use the [`MutagenSync`](https://docs.ddev.com/en/stable/users/extend/custom-commands/#mutagensync-annotation) annotation. - -You should use this annotation if your `host` or `web` commands modify, add, or remove files in the project directory. It ensures that file sync is handled correctly when Mutagen is enabled, preventing unexpected behavior or sync delays. (It does no harm and causes no performance issues if Mutagen is not in use.) - -Example: - -- https://github.com/backdrop-ops/ddev-backdrop-bee/blob/main/commands/web/bee - -### Support for Optional Compose Profiles - -The same DDEV v1.24.4 release introduced support for [optional docker-compose profiles](https://docs.ddev.com/en/stable/users/extend/custom-compose-files/#optional-services), which can be used by add-ons to offer more flexible configuration. - -Example: - -- https://github.com/ddev/ddev-mongo/blob/main/docker-compose.mongo.yaml -- https://github.com/ddev/ddev-mongo/blob/main/commands/host/mongo-express - ## Repository Configuration Best Practices To keep your add-on repository tidy, safe, and aligned with community standards, consider adjusting the following GitHub settings: