Skip to content

Contributing

Contributions to HaLOS are welcome. Each component repository accepts pull requests independently.

Getting Started

  1. Set up the development workspace -- this also sets up the AI-assisted workflow
  2. Read the development workflow
  3. Find an issue to work on in the relevant repository

If you're using Claude Code or a similar AI assistant, you can ask it to survey open issues across repositories and suggest what to work on next.

Reporting Issues

Report bugs and feature requests on the appropriate GitHub repository:

When reporting a bug, include:

  • HaLOS image variant and version
  • Steps to reproduce
  • Expected vs actual behavior
  • Relevant logs (from Cockpit Logs or journalctl)

Submitting Changes

  1. Fork the repository
  2. Create a feature branch (feat/description, fix/description)
  3. Make your changes following the coding standards below
  4. Run tests and linting locally
  5. Submit a pull request with a clear description

See Development Workflow for the full process.

Coding Standards

General

  • Write self-documenting code; comments explain "why", not "what"
  • Keep functions small and focused
  • No magic numbers -- use named constants
  • Validate inputs at system boundaries

Language-Specific

Language Linter Formatter Type Checker
Python ruff ruff pyright or ty
TypeScript ESLint Prettier tsc (strict mode)
Rust clippy rustfmt (built-in)
Shell shellcheck -- --

Testing

  • All new code should have tests
  • Test behavior, not implementation details
  • Run tests locally before pushing: ./run test

Debian Packaging

  • Never edit debian/changelog directly -- use ./run bumpversion
  • Include a version bump for package-affecting changes
  • Test package installation and removal on a test device

Communication

  • Discussions: GitHub Discussions for questions, ideas, and general conversation
  • Issues: For specific bugs and feature requests
  • Pull Requests: For code contributions