Thank you for your interest in contributing to B.A.L.L.E.R. (Binary Allocation & Library Launch Environment in Rust), a cross-platform package manager for Linux and Windows.
This guide covers everything you need to submit a contribution: environment setup, branch and commit conventions, testing expectations, and the review process.
Quick links
| Resource | Location |
|---|---|
| Technical setup reference | docs/contributing.md |
| Architecture overview | docs/architecture.md |
| Command reference | docs/commands.md |
| Pull request template | .github/pull_request_template.md |
| License | LICENSE |
| Security contact | Discord: HMythical |
- Getting Started
- Branch Strategy
- Filing Issues: Bug Reports & Feature Requests
- Code Contributions
- Commit Style
- Documentation
- Security Issues
- Pull Request Process
- Code of Conduct
- License
- Getting Help
| Requirement | Notes |
|---|---|
| Rust (stable toolchain) | 2021 edition, installed via rustup |
| Git | Any recent version |
| Linux tooling | A C toolchain and pkg-config for bundled dependencies |
| Windows tooling | PowerShell 5.1 or later and the MSVC build tools |
Verify your toolchain before starting:
rustc --version
cargo --version-
Fork
HMythical/ballerunder your own GitHub account. -
Clone your fork locally:
git clone https://github.com/<your-username>/baller.git cd baller
-
Add the upstream remote so you can stay in sync:
git remote add upstream https://github.com/HMythical/baller.git git fetch upstream
-
Confirm your commit identity is set correctly so your work is attributed to you:
git config user.name "Your Name" git config user.email "you@example.com"
-
Create a branch off
rootdevfor your work (see Branch Strategy).
Linux
./build/linux/build.sh dev # Debug build
./build/linux/build.sh release # Release build (stripped)
./build/linux/build.sh test # Tests + clippy + fmt check
./build/linux/build.sh clean # Clean artifacts
./build/linux/build.sh install # Install to /usr/local/bin and ~/.local/binWindows (PowerShell)
.\build\winbuild\build.ps1 -Command dev # Debug build
.\build\winbuild\build.ps1 -Command release # Release build
.\build\winbuild\build.ps1 -Command test # Run tests
.\build\winbuild\build.ps1 -Command clean # Clean artifacts
.\build\winbuild\build.ps1 -Command install # Install per-machine and per-userWhere install puts the binary. Both platforms install to a per-machine
directory and a per-user one — /usr/local/bin and ~/.local/bin on Linux,
%ProgramFiles%\baller\bin and %LOCALAPPDATA%\baller\bin on Windows. Only the
per-machine directory needs elevation, so a plain ./build.sh install writes the
per-user copy, reports which directory it could not write, and still leaves a
working baller on PATH; re-run under sudo (or from an elevated PowerShell)
to get both. If neither can be written the command fails rather than claiming
success. BALLER_INSTALL_DIR overrides the pair and installs to that one
location instead; BALLER_SYSTEM_INSTALL_DIR and BALLER_USER_INSTALL_DIR
override one side each. uninstall removes from every directory it would have
installed to.
Where the scripts run cargo. Both scripts run every cargo command from the
repository root, so they behave the same whatever directory you call them from,
and stop with a non-zero exit as soon as cargo fails. On Linux, clean checks
target/ first: a build run as root (sudo, or a container with the repo
mounted) leaves directories you cannot delete, and rather than failing halfway
with Permission denied (os error 13), clean deletes nothing and prints the
sudo chown that gives them back.
You can also use cargo directly. See docs/contributing.md for the full project layout, configuration file format, and dependency list.
Branch names use a type prefix followed by a short, hyphenated description.
| Prefix | Use for | Example |
|---|---|---|
feature/ |
New functionality | feature/parallel-downloads |
fix/ |
Bug fixes | fix/manifest-path-resolution |
docs/ |
Documentation changes | docs/registry-configuration |
refactor/ |
Restructuring without behaviour change | refactor/dep-solver-traits |
test/ |
Test additions or changes | test/downloader-edge-cases |
chore/ |
Build, CI, and maintenance work | chore/bump-clap-version |
Note: Keep descriptions lowercase and hyphen-separated. Avoid branch names that only reference an issue number.
| Branch | Purpose |
|---|---|
rootdev |
Main development branch. All contributions target this branch. |
deploy |
Release branch. Maintained by the project maintainer. |
The flow is:
your-fork/feature/<description> -> HMythical/baller:rootdev -> deploy (releases)
Contributors open pull requests against rootdev. Only the maintainer promotes rootdev to deploy for a release.
Keep your branch current before opening a pull request:
git fetch upstream
git rebase upstream/rootdev- CI must pass on both Linux and Windows.
- The description must explain what changed and why.
- New functionality must include test coverage.
- Changes should stay within a single platform where practical (see Platform-Specific Rules).
Baller ships two checked-in issue templates, written in the high-detail style of issue #89. Pick the template that matches what you are reporting, invoke it with the GitHub CLI, and follow the grounding rules below.
| You want to… | Template | CLI invocation |
|---|---|---|
| Report a bug (crash, wrong exit code, corrupted DB, bad install) | .github/ISSUE_TEMPLATE/bug.md |
gh issue create --template bug |
| Request a feature (new source, command, or enhancement) | .github/ISSUE_TEMPLATE/baller-feature.md |
gh issue create --template baller-feature |
From the web, use the "New issue" chooser and select the matching template. Both templates use the same seven-section anchor format as issue #89: Summary / Justification (for features) or Why this happens (for bugs) / Reproduction / Expected behavior / Suggested direction / Additional context / Environment.
- Search open issues first; duplicates are closed. Reference a related issue by number in your body (e.g. "related to #89").
- Use the template that matches what you are filing — do not put a feature request in the bug template or vice versa.
- Report security vulnerabilities privately rather than as a public issue — see Security Issues.
- Verified references only. Every
src/path:linemust be checked against the current working tree before filing. Read the file, correct stale or off-by-N line numbers, and never copy a reference from memory, an older issue, or a closed PR. - No fabricated output. Never invent terminal output, exit codes, error
strings, or timestamps in a Reproduction section. Prefer naming an existing
unit test (
filename.rs:line) or a precise, verifiable static walkthrough; otherwise state clearly what a would-be test would assert. - Sandboxed reproductions. Keep reproductions offline and local
(
HOME=$(mktemp -d)-style). Avoid live downloads,sudo, or installing packages into the system. If a reproduction genuinely requires network or elevated access, say so explicitly and provide the offline or static alternative. - One issue per report. A single issue should track a single bug or a single feature request so it can be labelled, triaged, and closed independently.
| Language | Scope |
|---|---|
| Rust | Primary implementation language for all application code |
| PowerShell | Windows build, install, and packaging scripts |
| Bash | Linux build, install, and packaging scripts |
| Python | CI helper and validation scripts under scripts/ |
New languages and runtimes are not accepted without prior discussion in a GitHub issue. Every dependency added to the project increases the surface area a package manager must be trusted with, so additions need justification.
Formatting is enforced by rustfmt and linting by clippy. Run both before committing:
cargo fmt
cargo clippy -- -D warningsNaming and structural conventions:
- Non-OS structs use PascalCase with context included:
BallerConfig, notConfig. - Variables use snake_case with explicit types where inference is not obvious.
- OS-specific structs are prefixed with the OS:
LinuxPackageInfo,WindowsPackageInfo. - OS-specific variables are prefixed with
os_. - Configuration structs are suffixed with
Config; builders withBuilder; data transfer objects withDTO. - Booleans are prefixed with
is_,has_,can_, orshould_. - Collections and tuples use plural names.
- Errors are propagated with the
?operator up tomain(). Avoidunwrap()andexpect()outside tests. - Names must be unambiguous and must not collide with names from external crates.
The full convention list, including the project structure and config file format, is in docs/contributing.md.
Every behavioural change needs a test that would fail without it.
cargo test # Run all tests
cargo test -- --nocapture # Run with output
cargo test test_name # Run a specific test- Cover the normal path and the edge cases, including malformed input and failure modes.
- Tests must not depend on network access, a specific machine, or a pre-existing package database.
- Record what you tested, what you expected, and what you observed in the pull request description.
Warning: B.A.L.L.E.R. installs and removes software on a user's machine. Code paths that write to the filesystem, elevate privileges, execute hooks, or verify checksums receive additional scrutiny. Do not submit changes to these paths without tests.
- All OS-specific code lives behind
#[cfg(target_os = "...")]guards, with implementations undersrc/platform/. - Shared behaviour is defined by the
PlatformManagertrait insrc/platform/common.rs. Add to the trait rather than branching on the OS at call sites. - Prefer keeping a single pull request to a single platform. A change that touches both Linux and Windows is harder to review and harder to test, and may be sent back to be split.
- Cross-platform changes to shared modules (OS detection, dependency resolution, the CLI layer) are expected to touch both and are exempt from the rule above.
(<type>) <description>
<body>
<footer>
| Type | Use for |
|---|---|
feat |
New feature |
fix |
Bug fix |
docs |
Documentation only |
style |
Formatting, no behaviour change |
refactor |
Restructuring without behaviour change |
test |
Tests |
chore |
Build, CI, and maintenance |
- Use the imperative mood: "Add resolver", not "Added resolver".
- Keep the subject line under 72 characters.
- Leave a blank line between the subject, body, and footer.
- Explain what changed and why in the body. The diff already shows how.
- Reference related issues in the footer with
Closes #<n>orRefs #<n>. - Note test coverage and any limitations or trade-offs.
A feature commit:
(feat) Add topological dependency resolver
Replace the naive recursive walk in dep_solver.rs with a topological
sort that detects cycles before installation begins. The previous
implementation could recurse indefinitely on a circular dependency
graph and left the package database in a partially written state.
Tested with a three-package cycle, a diamond dependency, and a
1,000-node synthetic graph. Cycle detection reports the full path
rather than only the repeated node.
Closes #42
A fix commit:
(fix) Reject archive entries that escape the extraction root
Archive extraction did not validate entry paths, so an archive
containing "../" components could write outside the cache directory.
Entries are now canonicalised and rejected if they resolve outside
the target root.
Refs #58
| Avoid | Use instead |
|---|---|
fixed stuff |
(fix) Correct cache path on Windows |
(feat): Add resolver |
(feat) Add resolver |
Update main.rs |
A subject describing the behaviour that changed |
| A subject line with no body | A body explaining the motivation and testing |
| Bundling unrelated changes | One logical change per commit |
- Document every public item with
///doc comments, including what it returns and the conditions under which it errors. - Use module-level
//!comments to explain a module's responsibility. - Add inline comments only where the reasoning is not obvious from the code. Explain why, not what.
- Update existing comments when you change the behaviour they describe. A stale comment is worse than none.
- Add a doc example for public APIs where a caller would benefit from seeing usage.
- User-facing changes require an update to the relevant file under
docs/. - New commands or flags require an update to
docs/commands.md. - Changes to the manifest, registry, or hook systems require updates to their respective documents in
docs/. - Update
README.mdonly when installation or build instructions change.
Your pull request should stand on its own for a reviewer who has not seen the code before:
- A clear description of the change and the problem it solves.
- Test results, including what you ran and on which platform.
- Terminal output, screenshots, or a recording for changes to user-visible behaviour.
- Any breaking changes, called out explicitly.
- Known limitations or follow-up work.
Warning: Do not open a public GitHub issue for a security vulnerability. Public disclosure before a fix is available puts users at risk.
Report vulnerabilities privately via Discord to HMythical.
Include the following in your report:
| Field | Description |
|---|---|
| Description | What the vulnerability is and which component is affected |
| Steps to reproduce | A minimal, reliable reproduction |
| Impact | What an attacker could achieve, and under what preconditions |
| Affected versions | Commit, tag, or release where you observed the issue |
| Suggested fix | Optional, but appreciated |
Please give the maintainer a reasonable opportunity to release a fix before disclosing the issue publicly.
| Type | Where it belongs |
|---|---|
| General bugs and crashes | GitHub Issues |
| Feature requests | GitHub Issues |
| Usage questions | GitHub Discussions |
| Build or setup problems | GitHub Discussions |
| Stage | Target |
|---|---|
| Initial acknowledgment | Within 48 hours |
| Assessment and severity triage | Within 1 week |
| Fix and release | Depends on severity and complexity |
Run the full local check suite and confirm every item passes:
cargo fmt --check
cargo clippy -- -D warnings
cargo testThen confirm the following:
- Your branch is rebased on the latest
upstream/rootdev. - New functionality has tests, and all tests pass.
- Documentation is updated for any public API or user-facing change.
- Commit messages follow the format in Commit Style.
- The change contains no unrelated edits, commented-out code, or debug output.
- No secrets, credentials, or absolute local paths are committed.
Open the pull request against rootdev. The pull request template is applied automatically. Fill in every section, including:
- Description
- Type of change
- Platform tested
- Testing performed
- Checklist
- Related issues
- Screenshots or recordings, where applicable
Mark the pull request as a draft if you want early feedback on work that is not finished.
| Stage | Detail |
|---|---|
| CI | Linux and Windows workflows must pass before review begins |
| Approval | At least one maintainer approval is required to merge |
| Changes requested | Push additional commits to the same branch; do not force-push mid-review unless asked |
| Merge | Squash and merge, so rootdev keeps a linear history |
If a pull request or commit message is unclear, the maintainer will ask you to explain the change rather than guess at it. The goal is that the next contributor can read the history and understand why the code is the way it is.
Do not copy code from other projects into this repository, including from Chocolatey or any other package manager. Contribute code you wrote or that you have an unambiguous right to relicense under Apache 2.0. If a change is derived from another project, say so explicitly in the pull request so the license can be reviewed.
This project adopts the Contributor Covenant Code of Conduct, version 2.1.
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
Examples of behavior that contributes to a positive environment:
- Demonstrating empathy and kindness toward other people
- Being respectful of differing opinions, viewpoints, and experiences
- Giving and gracefully accepting constructive feedback
- Accepting responsibility, apologizing to those affected by our mistakes, and learning from the experience
- Focusing on what is best for the overall community, not just for us as individuals
Examples of unacceptable behavior:
- The use of sexualized language or imagery, and sexual attention or advances of any kind
- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others' private information, such as a physical or email address, without their explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting
Project maintainers are responsible for clarifying and enforcing these standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior they deem inappropriate, threatening, offensive, or harmful.
Maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, issues, and other contributions that are not aligned with this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
This Code of Conduct applies within all community spaces, including the GitHub repository, issues, discussions, pull requests, and the project Discord. It also applies when an individual is officially representing the project in public spaces.
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainer via Discord to HMythical. All complaints will be reviewed and investigated promptly and fairly.
Maintainers are obligated to respect the privacy and security of the reporter of any incident. Consequences for violations follow the enforcement guidelines described in the Contributor Covenant v2.1, ranging from a private warning to a permanent ban from the community.
This Code of Conduct is adapted from the Contributor Covenant, version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
All contributions to B.A.L.L.E.R. are licensed under the Apache License 2.0.
By submitting a pull request, you agree that your contributions will be licensed under the same terms as the project, and you confirm that you have the right to license them that way.
Note: No Contributor License Agreement is required. The CLA that previously applied to this project has been removed. Contributing requires nothing beyond opening a pull request.
For the full terms, see the LICENSE file.
| Need | Where to go |
|---|---|
| Report a bug | Open the bug template — see Filing Issues |
| Request a feature | Open the feature template — see Filing Issues |
| Ask a usage or design question | GitHub Discussions |
| Report a security vulnerability | Discord: HMythical |
| Report a Code of Conduct violation | Discord: HMythical |
| Read technical documentation | The docs/ directory |
Before opening an issue, search existing issues to see whether it has already been reported.
B.A.L.L.E.R. is early in its life and there is a great deal still to build. Thank you for taking the time to contribute.