Contributing
Thank you for your interest in the BuildStream project for XFCE Linux!
Contribute compute — no code needed
Your machine runs one task at a time using your signed-in AI coding CLI. The relay alternates between eligible School (OS) and Reef (apps) hives after each task. If one hive has no work, the other can continue.
The guide covers prerequisites, verified just setup, credentials, provider
costs, and how to stop with Ctrl+C. Your subscription quota or API charges apply.
Never post account credentials or API keys in issues or pull requests.
Getting Started
Prerequisites
- The
justcommand runner. Use a current release. Ubuntu 24.04 has a version that is too old for the grouped recipes. - BuildStream 2.7.0+ or Podman for the repository's
bst2container - Podman
- QEMU + KVM
- 200GB+ free disk space
- Git, Python 3, pytest, and BATS
Setup Development Environment
# Clone repository
git clone https://github.com/tuna-os/xfce-linux.git
cd xfce-linux
# Verify the recipe files parse
just --summary >/dev/null
just --evaluate >/dev/null
# Run the fast local tests
bats tests/bats/*.bats
python3 -m pytest tests/pytest/ -v
# Verify Podman
podman --version
Development Workflow
1. Creating a Feature Branch
git checkout -b feature/your-feature-name
2. Making Changes
Adding XFCE Components
Add the component's BuildStream element under elements/, then reference that
element from the appropriate composition element. Use a checked-in element in
the same directory as the schema example. Component definitions are BuildStream
files, not the name/repo/checkout map that this guide showed before. Local
sources should use release tags from upstream. Document exceptions in
docs/ci-and-iso-pipeline.md.
Modifying Element Definitions
- Edit relevant
.bstfile inelements/ - Validate syntax:
bst show elements/your-element.bst - Test build:
bst build elements/your-element.bst
Adding Patches
- Create patch file in
patches/freedesktop-sdk/orpatches/gnome-build-meta/ - Reference in patch_queue sources
- Test:
just build
3. Testing Changes
# Unit and functional tests (the same commands used by CI)
bats tests/bats/*.bats
python3 -m pytest tests/pytest/ -v
# Verify the justfiles parse
just --summary >/dev/null
just --evaluate >/dev/null
# Validate the complete BuildStream graph
bst --no-interactive show --deps all oci/xfce-linux.bst >/dev/null
# Full rebuild (if major changes)
just build
# Validate the exported image
just lint
Shell, YAML, workflow, and Renovate changes are also checked by ShellCheck,
yamllint, actionlint, and renovate-config-validator in CI. See
docs/ci-and-iso-pipeline.md
for the full pre-merge and post-merge gate sequence.
4. Documentation
Update relevant documentation:
- CI/ISO bugs: docs/ci-and-iso-pipeline.md (add an invariant test too)
- Build process: docs/, AGENTS.md
- Architecture decisions: docs/adr/
5. Commit and Push
git add -A
git commit -s -m "Description of changes
- Detailed list of changes
- Second point
- Third point"
git push origin feature/your-feature-name
Commit Message Guidelines
Use clear, descriptive commit messages:
type(scope): Short description
Detailed explanation of what and why.
- Bullet point 1
- Bullet point 2
- Bullet point 3
Fixes: #issue-number (if applicable)
Commit Types
feat:New featurefix:Bug fixdocs:Documentationrefactor:Code structure changesbuild:Build process changestest:Test changeschore:Maintenance
Build System
Using just Commands
# Show available commands
just --list
# Build phases
just build # Full OCI build
just export # Export to image
just generate-bootable-image # Create bootable disk
just boot-vm # Launch QEMU VM
# Development
just clean # Clean cache
just logs # View logs
just --list # List all available recipes
BuildStream Commands
# Show element details
bst show elements/path/to/element.bst
# Build specific element
bst build elements/path/to/element.bst
# Build with progress
bst build --progress tty elements/path/to/element.bst
# Cache information
bst artifact show <artifact-id>
# View logs
bst log <artifact-id>
Project Structure
xfce-linux/
├── docs/ # Documentation
├── elements/ # BuildStream elements
│ ├── core/ # XFCE core
│ ├── xfce-linux/ # Integration layer
│ └── oci/ # OCI composition
├── patches/ # BuildStream patches
├── files/ # Build-time files
├── scripts/ # Build scripts
├── tools/ # Development tools
└── Justfile # Build automation
Testing
Run the fast test suites before you push:
bats tests/bats/*.bats
python3 -m pytest tests/pytest/ -v
Boot Testing
just boot-vm boots bootable.raw (run just generate-bootable-image first).
It takes one of two paths, which the host selects, and each path has a
different set of endpoints. Read the recipe's output before you connect.
Native QEMU (used when qemu-system-x86_64 is on PATH):
# Start VM (daemonized)
just boot-vm
# Serial console on ttyS0 (in another terminal)
telnet 127.0.0.1 4445
# Serial debug shell on ttyS1
telnet 127.0.0.1 4447
# SSH (after boot)
ssh root@127.0.0.1 -p 2223
# VNC — QEMU display :1, i.e. TCP 5901
vncviewer 127.0.0.1:1
QEMU exposes its monitor as a Unix socket at ./qemu-monitor.sock, not as a
TCP port.
sshd is enabled, but the image ships no authorized keys and keeps OpenSSH's
default PermitRootLogin prohibit-password, so ssh root@ fails with
Permission denied (publickey) until you add your own key. Log in on the serial
console first and append your public key to /root/.ssh/authorized_keys.
Podman fallback (used when qemu-system-x86_64 is missing): the recipe runs
ghcr.io/qemus/qemu:latest instead, and prints a web/VNC URL on the first free
port from 8006 upward. The container forwards SSH on 127.0.0.1:2222, not
2223.
Verify XFCE Installation
The image is built from source by BuildStream on a freedesktop-sdk base
(gnome-build-meta.bst:oci/gnomeos/stack.bst). There is no package manager
and no dpkg database inside the guest. Examine the filesystem and systemd
instead.
# Check XFCE binaries
ls /usr/bin | grep -E 'xfce|xf' | head -20
# Inspect the XFCE library tree (panel plugins live under here)
ls -la /usr/lib/xfce4/
# Check the display manager
systemctl status gdm
# View greeter/session logs — the session is 'xfce-wayland', started by GDM;
# there is no xfce-session unit
journalctl -u gdm -n 50
Known Issues & Solutions
See docs/ci-and-iso-pipeline.md for the
current CI/ISO problem log. docs/technical/SOLUTIONS_AND_ANALYSIS.md is a
dated (2026-05) session report kept for history, not a live issue tracker.
Code Review Process
-
Automated Checks:
- BATS and pytest test suites
- Validation of the full dependency graph in BuildStream
- Justfile syntax checks
- ShellCheck, yamllint, actionlint, and Renovate configuration validation
-
Manual Review:
- Check for completeness
- Verify documentation
- Test build locally
-
Tests:
- Make sure that you pass the fast tests on your machine
- Relevant image, ISO, or install tests pass for the scope of the change
- No regressions
Performance Considerations
- Large builds take time: 88-90 minutes typical
- Cache is essential: 127GB local cache with remotes
- Important network access: The build pulls from remote caches
- Disk space: ~200GB for cache + artifacts
Troubleshooting
Build Fails
# Check logs
bst log <artifact-id>
# View build directory
bst shell elements/path/to/element.bst
# Clean and retry
just clean
just build
Elements Don't Load
# Validate all elements
bst show elements/
# Check specific element
bst show elements/path/to/element.bst
# View dependencies
bst show --deps elements/path/to/element.bst
VM Boot Issues
- Make sure that artifacts from BuildStream exist
- Verify QEMU installation:
qemu-system-x86_64 --version - Check KVM availability:
kvm-okorgrep vmx /proc/cpuinfo
Documentation Standards
- Use Markdown for all documentation
- Include code examples where helpful
- Keep README.md up-to-date
- Clearly document incompatible changes
- Update docs/ci-and-iso-pipeline.md when you fix a CI or ISO bug. Add an invariant test and a row there, per AGENTS.md's CI gate rules.
Questions?
- Check documentation first: See
docs/directory - Review build logs:
~/.cache/buildstream/logs/ - Check git history: Previous commits for context
- See docs/ci-and-iso-pipeline.md: the CI/ISO problem log
License
This project includes open-source components with various licenses (GPL, LGPL, MIT). Make sure that contributions comply with these licenses.
Thank you for your contribution! 🚀
For more information, see:
- docs/README.md — Documentation index
- AGENTS.md — Architecture, commands, and gotchas
- docs/ci-and-iso-pipeline.md — CI, ISO, install-test, and release pipeline