Skip to main content
Thank you for showing interest in the development of osu!. We aim to provide a good collaborating environment for everyone involved, and as such have decided to list some of the most important things to keep in mind in the process.

​
Issue or Discussion?

Understanding when to use issues versus discussions is important for effective collaboration.
When in doubt, start with a discussion first. We will escalate to issues as needed. Feedback in a slightly wrong place is better than no feedback at all.

​
Use GitHub Issues for:

A bug is a situation in which there is something clearly and objectively wrong with the game. Examples of bug reports:
  • The game crashes to desktop when I start a beatmap
  • Friends appear twice in the friend listing
  • The game slows down a lot when I play this specific map
  • A piece of text is overlapping another piece of text on the screen

​
Use GitHub Discussions for:

Use discussions when you want to:
  • Provide subjective feedback on the game (UI appearance, default skin, game mechanics, PP and scoring systems, etc.)
  • Suggest a new feature to be added to the game
  • Report a non-specific problem that may be connected to your hardware or operating system
If we cannot reproduce an issue, it is deemed low priority, or it is deemed to be specific to your setup, the issue may be downgraded to a discussion by a maintainer.

​
Reporting Bugs

When opening an issue for a bug report, please follow these steps:
1

Search for existing issues

Before opening the issue, search for any similar existing issues using the text search bar and issue labels. This includes both open and closed issues (we may have already fixed something, but the fix hasn’t yet been released).
2

Fill out the issue template

When opening the issue, please fill out as much of the issue template as you can. In particular, please make sure to include:
  • Logs - Instructions on how to find log files are included in the issue template
  • Screenshots - Visual evidence helps us understand the problem
3

Provide follow-up information

We may ask you for follow-up information to reproduce or debug the problem. Please look out for this and provide follow-up info if we request it.

​
Providing General Feedback

When opening a discussion, please keep in mind the following:
1

Search existing discussions

Use the search function to see if your idea has been proposed before, or if there is already a thread about a particular issue you wish to raise.
2

Provide details

  • If proposing a feature, explain it in as much detail as possible
  • If reporting a non-specific problem, provide applicable logs, screenshots, or video that illustrate the issue
If a discussion gathers enough traction, it may be converted into an issue by a maintainer.

​
Submitting Pull Requests

​
Before You Start

Due to significant community interest and limited review throughput, the core team’s primary focus is on the issues currently on the roadmap. Reviewing PRs outside the roadmap scope is done on a best-effort basis, so please be aware that it may take a while before a core maintainer reviews your change.
For simple issues: A direct PR is okay. For non-trivial issues: Please ask us first before starting work. This way we can:
  • Estimate if it is a good fit for you
  • Provide the correct direction on how to address it
  • Avoid wasted effort
For roadmapped issues: While we do not rule out external contributors from working on roadmapped issues, we will generally prefer to handle them ourselves unless they’re not very time sensitive. For visual changes or bigger tasks: If there is no corresponding issue or discussion thread yet, please open a discussion or issue first to avoid wasted effort. This applies especially if you want to work on designs from the osu! Figma master library.

​
Pre-submission Checklist

Before opening your PR, ensure you:
1

Master the fundamentals

  • Are comfortable with object-oriented programming principles
  • Understand C# syntax
  • Know your development environment
  • Are familiar with git and the pull request workflow
2

Add tests

We expect most new features and bugfixes to have test coverage, unless the effort of adding them is prohibitive. See the testing documentation for more details on our visual testing methodology.
3

Run code analysis

Run tests and code style analysis before opening the PR:
./InspectCode.sh  # Linux/macOS
# or
.\InspectCode.ps1  # Windows
This is particularly important if you’re a first-time contributor, as CI will not run for your PR until we allow it to do so.
4

Test in debug configuration

Do not run the game in release configuration during testing (except for benchmarks). Using release is unnecessary and harmful, and can even lead to losing your local realm database if you start making changes to the schema.
The debug configuration has a completely separated full-stack environment, including a development website instance at https://dev.ppy.sh/. You can register an account on that development instance for testing purposes without worry about multi-accounting infractions.
Please do not make code changes via the GitHub web interface.

​
Opening the Pull Request

When you’re ready to open your PR, please follow these guidelines:
1

Use a topic branch

Submit the pull request from a topic branch (not master), and keep the Allow edits from maintainers checkbox selected, so that we can push fixes to your PR if necessary.
2

Choose the correct target branch

Pick the following target branch for your pull request:
  • pp-dev - if the change impacts star rating or performance points calculations for any of the rulesets
  • master - otherwise
3

Follow git best practices

  • Please avoid pushing untested or incomplete code
  • Please do not force-push or rebase unless we ask you to
  • Please do not merge master continually if there are no conflicts to resolve. We will do this for you when the change is ready for merge

​
Code Review Process

We are highly committed to quality when it comes to the osu! project. This means that contributions from less experienced community members can take multiple rounds of review to get to a mergeable state. We try our utmost best to never conflate a person with the code they authored, and to keep the discussion focused on the code at all times. Please consider our comments and requests a learning experience.

​
Getting Help

If you’re uncertain about some part of the codebase or some inner workings of the game and framework, please reach out by: We will try to help you as much as we can.

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us