# Contributing to unraid-podman

Thanks for your interest in contributing. This project is in an early,
architecture-first stage — please read [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
before proposing structural changes, so new work stays consistent with the agreed
design (RAM-root persistence model, no systemd, Docker coexistence, etc.).

## Ground rules

- Discuss non-trivial changes in an issue before opening a PR — this repo makes
  deliberate, sometimes non-obvious trade-offs (see the "Offene Fragen / Risiken"
  section of the architecture doc) and we'd rather align early than rework a PR.
- Keep persistence discipline: anything written under `/etc`, `/usr`, `/var` on a
  running Unraid system is lost on reboot. Any new config or state must be mirrored
  to `/boot/config/plugins/podman/` or an array/cache path — see
  [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#7-persistenz-strategie-zusammenfassung-der-prinzipien).
- No systemd. Init/process management goes through `plugin/rc.d/rc.podman` in the
  classic BSD `start|stop|restart|status` style.
- Don't introduce changes that could destabilize a coexisting Docker installation
  (shared storage paths, shared bridge/network names, shared iptables chains).

## Repository layout

See the "Repository structure" section in [README.md](README.md). In short:

| Directory | What goes here |
|---|---|
| `packages/` | One subdirectory per Slackware `.txz` package (podman, conmon, crun, netavark, aardvark-dns, containers-common, fuse-overlayfs, passt) |
| `plugin/` | The `.plg` manifest, `rc.d/rc.podman`, `sbin/` helper scripts, and default files staged for `/boot/config/plugins/podman/` |
| `webui/` | Dynamix-style GUI pages under `plugins/podman/` (later phase) |
| `config/` | Default `containers.conf` / `storage.conf` / `registries.conf` / `policy.json` templates |
| `scripts/` | Build and release tooling, not shipped to end users |
| `docs/` | Architecture, install guide, FAQ, troubleshooting, roadmap |

## Development setup

Podman package builds must target Slackware compatibility with Unraid's current
base — this generally means building inside a Slackware-compatible container
rather than on your own distro. Run `scripts/build-packages.sh` (optionally
`scripts/build-packages.sh <name>` for a single package) inside such a
container; `scripts/ci/setup-slackware-buildenv.sh` bootstraps the toolchain
and C library dependencies the build needs. `.github/workflows/build-packages.yml`
runs the same scripts in CI and is the reference for the exact container image
and setup sequence.

For anything touching `plugin/rc.d/rc.podman`, `plugin/sbin/*.sh`, or `podman.plg`,
test on a real or virtualized Unraid instance — behavior around RAM-root, `/boot`
persistence, and array/cache availability at boot cannot be fully validated on a
generic Linux box.

## Coding conventions

- **Shell scripts** (`rc.podman`, `sbin/*.sh`, `scripts/*.sh`): POSIX-compatible
  where practical, `set -eu` at minimum, and must pass
  [ShellCheck](https://www.shellcheck.net/) (see `.github/workflows/lint.yml`).
- **Slackware package recipes** (`packages/*`): follow standard `SlackBuild`
  conventions (`slack-desc` limited to 70 columns / 11 lines, `doinst.sh` for
  post-install steps).
- **PHP/JS in `webui/`**: follow the conventions of Unraid's existing Dynamix
  plugins for consistency with the rest of the GUI.
- Commit messages: [Conventional Commits](https://www.conventionalcommits.org/)
  (`feat:`, `fix:`, `docs:`, `build:`, `ci:`, ...) so changelog generation and
  history stay readable.

## Pull requests

1. Fork, branch off `main`, keep PRs focused on a single concern.
2. Update `CHANGELOG.md` under `[Unreleased]` for any user-facing change.
3. Update relevant docs under `docs/` if behavior or structure changes.
4. Make sure CI (lint / package build checks) passes.
5. Describe how you tested the change, especially for anything touching boot
   behavior, persistence, or Docker coexistence.

## Reporting bugs / requesting features

Use the issue templates under `.github/ISSUE_TEMPLATE/`. For security-relevant
reports (rootful socket exposure, privilege escalation, etc.), follow
[SECURITY.md](.github/SECURITY.md) instead of a public issue.

## Code of Conduct

This project follows the [Code of Conduct](.github/CODE_OF_CONDUCT.md). By
participating, you agree to uphold it.