# Contributing

Thanks for your interest in improving this plugin!

**Scope:** the Unraid integration only - zero-downtime updates of containers behind Traefik's Docker provider, driven from Unraid's Docker page. Traefik itself and Unraid's Docker manager are upstream projects; issues about them belong there. Issues about this plugin (Settings page, update flow, rollback, packaging) belong [here](https://github.com/Greite/unraid-traefik-rolling-update/issues).

## Development setup

Requirements: bash, PHP 8+, `xmllint`, tar (GNU or BSD). Works on Linux and macOS. A real Unraid 7.3+ server with Traefik is needed to exercise the update flow itself (see `Makefile`: `make deploy`, `make testbg`, `make measure`; the server name lives in a git-ignored `local.mk`).

```bash
make selftest                    # pure-logic checks (Traefik detection, eligibility, injection, healthcheck command)
bash scripts/test_php_syntax.sh  # php -l on the script, the include and the .page files
xmllint --noout --noent traefik.rolling.update.plg
bash scripts/test_build.sh       # build dist/traefik.rolling.update-0000.00.00.txz + verify contents
```

CI runs the same four commands on every pull request.

## Repo layout

- `traefik.rolling.update.plg` - Unraid plugin manifest. The `version`/`md5` entities are **bumped by CI, never by hand**. The changelog is written by hand under a `###next` heading in `<CHANGES>`; the release workflow dates it.
- `source/traefik.rolling.update/usr/local/emhttp/plugins/traefik.rolling.update/` - what ships: `scripts/rolling_update` (PHP CLI, all side effects), `include/rolling.php` (pure logic + self-test), the Settings page, the Docker page override, the plugin README and icon.
- `docs/superpowers/specs/` - design documents (the authority when code and docs disagree).
- `scripts/` - build and test scripts, icon generator.
- `.github/workflows/` - CI (`ci.yml`) and releases (`release.yml`).

## Pull requests

- Keep changes focused on one thing.
- Changes to `include/rolling.php` come with self-test checks in `rolling_selftest()`.
- Add a line under `###next` in `<CHANGES>` when the change is user-visible.
- Do not bump the `.plg` version or md5 in a PR.
- UI strings, code comments and commit messages in English (conventional commits).

## Releases

Maintainers run the **Release** workflow (Actions → Release → Run workflow). It builds the package, publishes a GitHub Release with the `.txz` and its `.md5`, then commits the `.plg` bump (version, md5, `###next` → `###<version>`) on `main`. Unraid installs read the `.plg` from `main` and download the package from the release.

## License

By contributing you agree that your contributions are licensed under the [GPL-2.0](LICENSE). The five `*_nchan` helpers in `scripts/rolling_update` are verbatim copies from Unraid's `dynamix.docker.manager` (GPL-2.0, Lime Technology / Bergware International) and must stay verbatim.