# Contributing to veilor-os

## Getting set up

```bash
git clone https://github.com/veilor-org/veilor-os.git
cd veilor-os
sudo dnf install lorax livecd-tools pykickstart anaconda-tui squashfs-tools xorriso qemu-kvm edk2-ovmf
```

## Build locally

```bash
./build/build-iso.sh    # output: build/out/veilor-os-43-YYYYMMDD-HHMMSS.iso
```

Requires sudo (loop devices + chroot mounts). On hosts with a recent
pcre2 / libselinux skew, the build will fail at `selinux-policy %triggerin`;
CI handles this automatically (matched libs in fresh container).

## Build via CI

Push to `main` triggers `.github/workflows/build-iso.yml`. Output is
attached as a workflow artifact for 14 days.

```bash
git push origin main
gh run watch
gh run download --name veilor-os-iso
```

## Test the ISO

```bash
./test/run-vm.sh                           # boots latest ISO in KVM
SECBOOT=1 ./test/run-vm.sh                 # boots in OVMF Secure Boot mode
FRESH=1 ./test/run-vm.sh                   # wipe disk + nvram, fresh install
./test/run-vm.sh build/out/veilor-os-XX.iso  # specific ISO
```

Walk through `test/boot-checklist.md` before approving a PR.

## House rules

1. **No personal data in commits.** No IPs, hostnames, emails, GitHub handles
   inside shipped artifacts. CI grep gate enforces.
2. **Hardening parity.** Any change must keep the audit risk score
   (`security/audit-template.md`) at or below current baseline.
3. **One feature per PR.** Easier to review, easier to revert.
4. **Follow upstream.** When Fedora changes a package layout, prefer adapting
   over forking. We layer veilor on Fedora — we don't fight it.
5. **Caveman mode for commits.** Conventional Commits, ≤50 char subject,
   body only when "why" isn't obvious.

## Branch model

- `main` — always green CI. Tagged for releases.
- `feat/*`, `fix/*`, `chore/*` — branched off main, PR'd back.
- Direct push to main blocked.

## Release flow

```bash
git tag -a v0.2.0 -m "first green ISO"
git push origin v0.2.0
gh release create v0.2.0 --generate-notes
# CI attaches the built ISO + sha256 to the release automatically
```

## Code of conduct

Be technical, be direct, no drama. Disagree with the design, not the person.
If a contribution introduces a security regression, the PR is closed without
discussion.