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
- 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