diff --git a/src/content/blog/ddev-add-on-maintenance-guide.md b/src/content/blog/ddev-add-on-maintenance-guide.md index 2cc5e226..994cc3c8 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: @@ -42,6 +42,65 @@ 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: +### 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`: + +```yaml +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 ... +} +``` + +### 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`. @@ -67,16 +126,6 @@ Make sure your add-on includes: 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`: - -```yaml -ddev_version_constraint: ">= v1.24.3" -``` - -This ensures compatibility and resolves known issues, such as those related to the [Mutagen Problem Report](open-source-for-the-win.md#mutagen-problemreport). - ### 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. @@ -109,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: