Contributing

MustardOS is open source and built by a small crew with a lot of help from its community. There is room to help whether you write code, translate, make themes, test new releases or simply report what went wrong.

Ways to help

Translate Put MustardOS into your own language through Weblate, right in your browser. How to translate Report a problem A clear report with a diagnostics file is one of the most useful things you can send. How to report Test new releases Artificer and Knight supporters try new features and fixes before each release. Supporting MustardOS Make a theme Design a theme for everyone to download from the theme library. Theme guides Improve this website Fix a mistake or add a missing guide. Every page links to its source on GitHub. Edit the website Work on the code Fix bugs and add features in the frontend, the system scripts or the core builder. Get the code

Translating

All translations are made on Hosted Weblate, and the language files in the device come from there.

Sign inCreate a free Weblate account, or sign in with GitHub.
Pick a languageOpen the MustardOS project and choose your language, or start a new one.
TranslateWork through the untranslated strings. Your changes reach the next release.

Make every change in Weblate. The language repository on GitHub is filled from Weblate, so anything changed there directly is replaced.

Reporting a problem

Bring problems to the Discord server or the forum. A report the crew can act on straight away includes these things.

DeviceThe device and the MustardOS version, both shown in Information on the device.
What happenedWhat you expected, what happened instead, and any message on the screen.
How to repeat itThe steps that cause it, starting from the Main Menu.
DiagnosticsRun System Diagnostics in the Task Toolkit, or the Diagnostics report for the area that is misbehaving, and attach the file it saves to SD1.

Check whether the problem happens on a fresh install before reporting it. Leftover files from older releases or other systems cause a lot of strange behaviour.

Improving this website

This website lives in the mustardos.github.io repository and is built with Jekyll. The Edit this page on GitHub link at the bottom of each page opens its source.

git clone https://github.com/MustardOS/mustardos.github.io
cd mustardos.github.io
bundle install
bundle exec jekyll serve

Open http://localhost:4000 to see your changes as you make them, then send a pull request.

WritingUse Australian English and plain wording. Call the project MustardOS, and the people behind it the "crew".
LayoutCard grids should fill every row, so pick a number of cards that suits the grid.
Generated dataSome data is copied from the other repositories by the scripts in _scripts, such as the task list and the settings profile schema. Change the source and run the script to update the data.

Working on the code

frontendThe menus, Pickles, Wasabi, the Web Dashboard server and the background helpers, written in C. C internalThe system scripts, device settings, Task Toolkit, applications and shared files that make up the rest of MustardOS. Shell extraBuilds and packages the Libretro cores offered for download. Builder themeThe theme library. Themes languageThe translations, filled from Weblate. Weblate mustardos.github.ioThis website. Jekyll

Building the frontend

You need make, ccache and a C compiler, plus curl or wget, perl and tar for the libraries the build fetches itself. Cross builds for devices expect an aarch64 toolchain in ~/x-tools, or wherever XTOOL points.

git clone https://github.com/MustardOS/frontend
cd frontend

# Guided setup that asks for the device, build type and toolchain
./build.sh

# A release build for the usual Cortex-A53 devices
BUILD=release ./build.sh make -j$(nproc)
DEVICEThe target, such as ARM64_A53 for H700 and A133 devices, which is the default.
BUILDrelease for a device image, or test for a development build with test flags.
./build.sh generateRefreshes the generated language template and script hashes without compiling. Keep the internal repository beside frontend so the hashes match your scripts.
./build.sh databaseWrites compile_commands.json for clangd, CLion and similar editors.

The frontend README has the full build options, native builds and the layout of the source tree.

Checks on every pull request

C formattingRun ./build.sh format before committing. It uses a pinned clang-format version, and ./build.sh format --check is what the pull request check runs.
Shell scriptsScripts in internal run under BusyBox, so they must start with #!/bin/sh and avoid bash-only features. The pull request check runs ShellCheck in POSIX mode.
User-facing textAdd new frontend strings in English. They reach Weblate through the generated language template.
ForkFork the repository on GitHub and clone your fork.
BranchMake your change on its own branch, one topic at a time.
TestBuild it and try it on a device, and run the format or shell checks.
Pull requestOpen a pull request that explains what changed and why.

Licences

The frontend, internal scripts, core builder, themes and translations are released under the GNU General Public License version 3. Except where otherwise noted, the content of this website is licensed under CC Attribution-Noncommercial 4.0 International. By contributing, you agree that your work is released under the same licence as the project it goes into.