Code Style & Script Conventions
Relevant source files
The following files were used as context for generating this wiki page:
Quickemu is a collection of Bash scripts designed to automate the management of QEMU virtual machines. To maintain consistency across the project's various utilities—including quickemu, quickget, quickreport, and chunkcheck—the project enforces strict coding standards, linting requirements, and contribution workflows. These conventions ensure that the codebase remains portable across Linux and macOS hosts while supporting a vast array of guest operating systems.
The core philosophy of the project is to provide an "optimized by default" experience, reducing the need for exhaustive manual configuration. This is achieved through a structured modular approach in Bash, where functional logic is separated from OS-specific definitions.
Sources: AGENTS.md:3-8, README.md:16-20
Scripting Standards
All scripts within the Quickemu project must adhere to Bash 4.0+ syntax. This version requirement is explicitly checked at runtime to ensure compatibility with advanced Bash features used throughout the project.
Formatting and Linting
The project maintains specific formatting rules to ensure readability and consistency.
| Rule | Requirement |
|---|---|
| Encoding | UTF-8 |
| Line Endings | LF (Unix) with a final newline |
| Whitespace | Trim trailing whitespace (except in Markdown files) |
| ShellCheck | Must be compliant; specific warnings (like SC2317) may be disabled globally where dynamic dispatch is used |
Sources: AGENTS.md:28-36, AGENTS.md:73-73
Indentation and Syntax
Indentation levels vary by script within the project to match established patterns:
- quickemu: Uses 2-space indentation.
- quickget: Uses 4-space indentation.
- Function Definition: Functions must use the
function name() {syntax.
Sources: AGENTS.md:28-34
Development Workflow and Tools
Quickemu utilizes Nix for environment reproducibility and ShellCheck for static analysis. This ensures that every developer works within a consistent environment with all necessary dependencies.
The diagram above illustrates the standard local development cycle for contributing to the project.
Sources: AGENTS.md:14-25, AGENTS.md:65-65
Testing Procedures
Before submitting changes, developers are expected to validate their scripts using the following commands:
- Linting:
shellcheck quickemu quickget quickreport chunkcheck - Validation: Use
./quickget --check <os>to verify download logic and URL construction. - Architecture Testing: Use
--arch arm64or--check-all-archto ensure cross-platform compatibility.
Sources: AGENTS.md:21-26
Contribution Conventions
Quickemu follows a strict set of rules for contributions to maintain a clean and searchable project history.
Conventional Commits
All commit messages and Pull Request titles must follow the Conventional Commits specification. This is enforced via CI workflows.
| Prefix | Use Case |
|---|---|
fix(quickget): | Fixing distro downloads or updating editions/releases |
fix(quickemu): | Fixing VM configuration or runtime issues |
feat(quickget): | Adding support for a new operating system |
feat(quickemu): | Adding new VM features |
ci: | Changes to CI/CD workflows |
docs: | Updates to documentation or the wiki |
Sources: AGENTS.md:47-60, CONTRIBUTING.md:11-11
Pull Request Guidelines
- PR Titles: Must match Conventional Commits format.
- Atomicity: For single-commit PRs, the commit message must match the PR title.
- Verification: PRs trigger automated workflows including
lint-shellcheck,lint-pr,test-quickget, andtest-build-quickemu.
Sources: AGENTS.md:62-71
Project Structure & Module Roles
The project is divided into specialized scripts, each with a defined role in the VM lifecycle.
This graph represents the data flow between the primary scripts and their respective outputs.
Sources: AGENTS.md:1-12, README.md:52-60
Security and Community Standards
The project maintains a professional environment and a clear policy for handling vulnerabilities.
- Code of Conduct: Participants are expected to follow the Contributor Covenant, prioritizing empathy, kindness, and constructive feedback. Community leaders enforce these standards through warnings or bans if necessary.
- Security Reporting: Vulnerabilities are reported by filing an issue and selecting "Report a vulnerability." Security updates are currently prioritized for the latest stable versions (e.g., 4.9.x).
Sources: CODE_OF_CONDUCT.md:5-20, SECURITY.md:5-15
Conclusion
The Code Style and Script Conventions of Quickemu are designed to manage the complexity of supporting nearly 1000 operating system editions within a Bash-based framework. By enforcing ShellCheck compliance, mandatory Nix development environments, and Conventional Commits, the project ensures that its automated VM management remains robust and maintainable for both Linux and macOS users.