Muse is a platform for running code analysis tooling during pull requests, adding a notion of assurance to your repository’s continuous integration system. This quick start is intentionally brief, consider also reading the live documentation at https://docs.muse.dev.
Bug Bash Projects
A project or set of projects will be preselected for the beginning of a bug bash. Check the rules of your specific bash to see if you are allowed to fix bugs in other projects as well. The bug bash homepage (https://bugbash.muse.dev) includes the rules, a list of projects, and a leaderboard of the current point standings of participants. Each project has a link to the repository on GitHub as well as a list of Muse analysis results collected before the bash began. Feel free to use Muse to analyze the project for yourself as well. This will ensure you don’t try to fix bugs which have already been addressed. If you want to analyze a new project for yourself, see the below section, “Supporting a new repository”.
Finding a Bug
Once analysis completes you can see a list of results in https://console.muse.dev. For example, one result reads:
Here we see the bug title, message body, line, column, and tool that produced the result. The bug report is also a link to the line and file hosted on GitHub. Each tool provides a detailed description of the bug type, its meaning, and often a remedy.
The full list of findings can be daunting to behold. Never fear, you just need one bug! Industrial projects are large - don’t hesitate to jump past bugs that are confusing and find code you can grasp quickly. Finding a code and issue that is clear to you is key to making good use of your time.
Finally, the console provides full text search of the bug results. If you’re looking for a particular file, function, or tool result then try the search first. Sometimes bug of certain types are of more interest to some people, if so just hunt those and happy fixing!
So how do you fix it? Well the coding is up to you - pull on the social network if you need to. Join the project’s channels in our discord and strike up conversation.
Once you have the code right then check out a branch, commit the code, and push it up:
git checkout -b fix/something-was-fixed git commit . -p git push
Finally, open a pull request with the upstream repository - the one you originally - so everyone can benefit from your work. You’ll also get valuable internet points on our leaderboard.
Using Muse - Supporting a new repository
Ok, so you’re a trailblazer and want to forge your own path. That’s cool. The brief, brief, brief version:
- Go to https://console.muse.dev. Log in. Follow the flow to install the Muse GitHub app.
- Optional: For any repository you own go to https://console.muse.dev and click “analyze” to get findings.
- For any activated repository Muse will analyze pull requests and post results.
The first step is to log in and install the GitHub app on your account. Once installed, github will notify Muse of any newly opened or updated pull request. Muse will then work to detect the build system and run a cadre of analysis tools. Any detected bugs that were introduced by the pull request will be surfaced via a comment to the pull request thread on GitHub. For example, see this mock Apache Shiro PR.
Working Without Pull Requests
Pull requests are not the only method to cause work. Browse to
https://console.muse.dev/<GitHub Owner>/<Repository Name> and click on the “Analyze” button to start an analysis and get findings
for the repository in its current state.
Fixing Build Issues
The automatic build system detection might not suffice. In these cases it will be necessary to write a configuration file. We’ll touch on common Java and C issue. Full help and an FAQ are available online.
For Java or C/++ projects first ensure your project can be built in a x86-64 Ubuntu 20 environment
using Java8, 11, or clang. Consider using the musedev/build-test docker image via
docker run --rm -it musedev/build-test bash.
With both Java and C/++ projects you can be explicit about the build system (instead of depending on
auto-detection). For this you commit a
.muse/config.toml file containing
build = "make <target>" where
make <target> could instead be
maven compile, or even
prefixed with environmental variables such as
CC=gcc make all.
The most common Java issue is JDK version. You can commit a
.muse/config.toml file to the
jdk11 = true to change from the default jdk8 to jdk11.
The most common C/++ issue is libraries. You can commit a
.muse/config.toml file with
setup = ".muse/setup.sh" and a
.muse/setup.sh file with
apt update && apt install -y <ubuntu dependencies>.
Some projects, Java and C alike,need submodules. You can use the
setup field desribed above to
git submodules update --init --recursive or any other command to acquire code. As always,
reach out to our discord or support via the console if there are any issues.