beyondcode / beyondcode/herd-community

herd.yml: Windows service catalogue is a subset of macOS (no Typesense), so a shared manifest cannot be applied by herd init on Windows

Open
#1,746 0 comments 0 reactions 0 assignees View on GitHub
fixed-in-next-release macOS windows
Dominant language
No language data
Stars
122
Forks
1
PR merge metrics
No merged PRs in 30d

Description

## Summary

`herd.yml` is documented as a manifest a team commits so every machine gets the same PHP version and Herd Pro services via `herd init`. In a mixed macOS / Windows team this breaks silently at the documentation level and loudly at `herd init` time, because the two platforms do not offer the same services or versions:

- The macOS service-versions page lists Typesense (0.26 / 29.x / 30.x), Valkey and Redis 7.0.x / 7.4.x.
- The Windows service-versions page lists no Typesense and no Valkey, and Redis 7.0.0 only. `/docs/windows/herd-pro-services/typesense` returns 404.
- The herd-yaml docs page (both macOS and Windows variants) mentions no platform caveat, no way to mark a service optional or per-platform, and no wildcard versions.

A manifest like this therefore works on macOS and fails `herd init` on Windows:

```yaml
name: myapp
php: '8.5'
secured: true
services:
mysql:
version: 8.4.2
port: '${DB_PORT}'
typesense:
version: 29.0
port: '${TYPESENSE_PORT}'
```

The same failure mode already hits single-platform teams when an exact patch version drops out of a newer Herd build's catalogue (#1595, discussion #1735), so the underlying problem is that `herd init` treats every `services` entry as a hard requirement with an exact version.

## Requests

1. Document the platform differences on the herd-yaml page (or link the two service-versions pages from it) so teams know a committed manifest is not portable as-is.
2. Let `herd init` warn and skip a service that is unavailable on the current platform or Herd build instead of aborting, or add an explicit `optional: true` / `platforms: [macos]` key per service.
3. Accept wildcard versions (`8.4.x`, `29.x`) so a manifest survives catalogue updates (this is the ask in #1595 / #1735 too).

## Environment

- Herd for macOS and Herd for Windows, both current at time of writing, Herd Pro.
- Reproduced by committing the manifest above in a Laravel project and running `herd init` on each platform.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the herd-yaml documentation pages for macOS and Windows and compare the linked service-versions pages, then reproduce the example manifest with herd init on both platforms. Done should make platform and catalogue differences explicit and establish a supported way for manifests to handle unavailable services and version changes.

Written by the indexing model from the issue text.

Assessment

Tech stack
laravel, mysql, php, redis
Domain
cli, devops, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.