Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
Quickemu is a community-driven project that automates the creation and execution of optimized virtual machines for Linux, macOS, and Windows. These guidelines outline the technical standards, social expectations, and procedural workflows required to maintain the project's integrity and foster a welcoming environment for all contributors.
The project relies on a Bash-based architecture, utilizing quickget for OS acquisition and quickemu for VM management. Contributions range from documentation improvements and bug reports to the implementation of support for new operating systems and features.
Sources: README.md:10-15, CONTRIBUTING.md:3-9, AGENTS.md:3-6
Community Standards and Conduct
Participation in the Quickemu community is governed by a Code of Conduct designed to ensure a harassment-free experience for everyone. This applies to all community spaces, including GitHub discussions, issues, pull requests, and the official Discord channel.
Behavior Expectations
Contributors are expected to demonstrate empathy, use welcoming language, and accept constructive feedback gracefully. Unacceptable behaviors include trolling, personal attacks, public or private harassment, and the publishing of private information without permission.
Sources: CODE_OF_CONDUCT.md:12-35
Enforcement Guidelines
Community leaders are responsible for enforcing standards and may take corrective actions based on the severity of the violation:
- Correction: A private written warning for unprofessional behavior.
- Warning: A warning for single or repeated incidents with potential temporary restrictions.
- Temporary Ban: A time-limited prohibition from community interaction.
- Permanent Ban: A permanent removal from the community for patterns of violation or serious harassment.
Sources: CODE_OF_CONDUCT.md:65-103
Development Environment and Tools
Quickemu provides a structured environment for development and testing, primarily leveraging Nix for dependency management.
Project Structure
| File/Component | Description |
|---|---|
quickemu | Main VM launcher script (Bash) |
quickget | OS downloader and configuration generator (Bash) |
quickreport | System diagnostics utility |
chunkcheck | Download verification utility |
flake.nix | Nix flake for packaging and development |
| Sources: AGENTS.md:8-16 |
Setting Up the Environment
The project uses nix to provide a consistent development shell with all necessary dependencies.
nix develop # Enter devshell with all dependencies
direnv reload # Update local environment for testing
The development shell patches the quickemu script to use Nix store paths for specific dependencies like OVMF and Samba.
Sources: AGENTS.md:18-24
Technical Standards and Code Style
All scripts within the Quickemu project must adhere to specific formatting and technical requirements to ensure compatibility and maintainability.
Bash Requirements and Linting
- Version: All scripts must be compatible with Bash 4.0+.
- Linting: Scripts must be ShellCheck compliant. Before submission, contributors should run:
shellcheck quickemu quickget quickreport chunkcheck. - Style:
- Files must use UTF-8 encoding, LF line endings, and end with a final newline.
- Functions must use the
function name() {syntax. quickgetuses 4-space indentation;quickemuuses 2-space indentation.
Sources: AGENTS.md:38-51
Architectural Logic in quickget
In quickget, many functions are invoked via dynamic dispatch. Consequently, the ShellCheck rule SC2317 (detecting unreachable code) is globally disabled for this file.
Sources: AGENTS.md:52-53
The diagram shows the logic flow for quickget when interacting with OS definitions.
Sources: AGENTS.md:27-35, AGENTS.md:55-62
Contribution Workflow
The contribution process involves standard GitHub workflows, with specific requirements for commit messages and pull requests.
Pull Requests (PRs)
- Format: PR titles must follow the Conventional Commits specification.
- Scope: For single-commit PRs, the commit message must match the PR title.
- Validation: PRs trigger CI workflows including
lint-shellcheck,test-quickget, andtest-build-quickemu.
Sources: AGENTS.md:65-74, AGENTS.md:78-86
Commit Message Prefixes
| Prefix | Usage |
|---|---|
fix(quickget): | Fixing distro downloads or updating releases |
fix(quickemu): | Fixing VM configuration or runtime issues |
feat(quickget): | Adding support for a new operating system |
feat(quickemu): | Adding new VM features |
docs: | Documentation updates |
| Sources: AGENTS.md:67-73 |
Adding a New OS
To add support for a new operating system to quickget, contributors must implement several specific functions:
- Add an entry to the
os_info()case statement. - Define
releases_<os>()to return available versions. - Define
editions_<os>()if multiple flavors exist. - Define
arch_<os>()if ARM64 is supported (default is amd64).
Sources: AGENTS.md:55-62
Security and Issue Reporting
Quickemu treats security and bug reporting as critical community inputs, though it is managed on a "best-efforts" basis.
Reporting Vulnerabilities
Vulnerabilities should be reported by filing a GitHub issue and selecting the "Report a vulnerability" option. Supported versions currently include the 4.9.x branch; versions below 4.8 are no longer supported.
Sources: SECURITY.md:3-16
The sequence diagram illustrates the reporting flow for vulnerabilities and bugs.
Sources: SECURITY.md:12-19, CONTRIBUTING.md:7
Summary
Contributing to Quickemu requires a balance of adherence to Bash 4.0 technical standards, conventional commit practices, and the community Code of Conduct. By utilizing the provided Nix development environment and following the automated CI testing workflows, contributors ensure that Quickemu remains a robust tool for automated VM management across diverse operating systems.