Contributing¶

Contributions to the installer are welcome. The project is intentionally a thin wrapper — please keep that scope in mind when proposing changes.

Dev environment setup¶

The installer is pure Bash. You need:

macOS with Apple Silicon (to run and test the install flow end-to-end)
shellcheck — static analysis for shell scripts
shfmt — shell script formatter
mkdocs-material — for docs contributions

# Install lint/format tools
brew install shellcheck shfmt

# Install docs dependencies
pip install -r requirements-docs.txt

Working on the docs¶

The documentation site uses MkDocs Material. To preview locally:

pip install -r requirements-docs.txt
mkdocs serve

Then open http://127.0.0.1:8000 in your browser. Changes to any docs/*.md file reload automatically.

To build a static site for inspection:

mkdocs build --strict

The --strict flag treats warnings as errors — the same mode used in CI.

Lint and format¶

# Check for issues
shellcheck install.sh bin/mlx-training-studio lib/*.sh

# Check formatting (does not modify files)
shfmt --diff install.sh bin/mlx-training-studio lib/*.sh

# Apply formatting
shfmt -w install.sh bin/mlx-training-studio lib/*.sh

Both shellcheck and shfmt run automatically on every push and pull request via the CI workflow.

Testing changes¶

Run preflight checks (no side effects)¶

bash bin/mlx-training-studio doctor

Test a full install in an isolated location¶

MLX_TS_NONINTERACTIVE=1 MLX_TS_INSTALL_DIR="${HOME}/Applications" MLX_TS_SOURCE_DIR="/tmp/mlx-ts-test-source"   bash bin/mlx-training-studio install

Clean up after a test run¶

rm -rf /tmp/mlx-ts-test-source
rm -rf "${HOME}/Applications/MLX GUI.app"
rm -f "${HOME}/Library/Application Support/MLX Training Studio/manifest.json"

Commit message style¶

This project uses Conventional Commits:

<type>(<scope>): <short summary in imperative mood>

[optional body — explain why, not what]

Types:

Type	Use for
`feat`	New feature or capability
`fix`	Bug fix
`docs`	Documentation changes only
`refactor`	Code change that neither fixes a bug nor adds a feature
`test`	Adding or improving tests
`ci`	Changes to CI workflows
`chore`	Dependency bumps, config tweaks, etc.

Examples:

feat(checks): add disk space warning threshold option
fix(build): quote xcodeproj path to handle space in project name
docs(troubleshooting): add Gatekeeper quarantine fix
ci: switch to actions/deploy-pages for MkDocs deploy

Pull request guidelines¶

Fork the repository and create a branch named <type>/<short-description>, e.g., fix/gatekeeper-quarantine-flag.
Make sure shellcheck passes with no new warnings.
Make sure shfmt --diff reports no formatting differences.
Test locally with MLX_TS_NONINTERACTIVE=1 before opening a PR.
Write a clear PR description explaining what changed and why. Reference any related issues.
Keep PRs focused — one logical change per PR.

Scope¶

This repo is intentionally a thin installer wrapper. Please do not add:

Auto-update daemons or background services
Analytics or telemetry of any kind
Features that belong in the upstream application itself

For upstream app improvements (new training modes, UI changes, etc.), open an issue or PR at stevenatkin/mlx-lm-gui.

Code of conduct¶

This project follows the spirit of the Contributor Covenant. Be respectful, constructive, and assume good faith. Issues and PRs that are abusive, off-topic, or spam will be closed without discussion.