This page covers some of the tasks that you may face while contributing. The approaches mentioned here are designed to make the process easier and may be applied to other projects hosted on GitHub or similar platforms.
For more information on Git and GitHub, see GitHub Documentation
Git is a version control system which helps manage changes to files. The osu! wiki's data and history of changes are stored in a Git repository. GitHub is a platform for development that provides a web interface for Git repositories and offers a set of tools for project management.
In order to make changes to a repository located on GitHub, a potential contributor needs to obtain a controlled copy of it called a fork. When you create your fork of the osu-wiki
repo, you take a snapshot of its contents at this very moment. To make a meaningful contribution, always sync your fork before making a set of changes — this can be done directly from GitHub:
Go to your fork of the osu-wiki
repo.
Select the master
branch from the dropdown.
Click Fetch upstream
, and select Fetch and merge
.
Updating the outdated branch
Now your branch is up-to-date with the original repository.
This solution works fine in most cases, although the feature itself has limited capabilities. For example, it doesn't allow you to overwrite any unwanted changes on the branch, as it only merges the upstream master
branch.
If you encountered any problems while using the GitHub tool or you want to overwrite your branch's contents, you can use the workflow written by the osu! wiki contributors.
Open your fork and go to the Actions
tab.
On the left sidebar, look for Sync with ppy:master
.
Click Run workflow
and fill in the options:
GitHub Actions workflow dispatch menu
master
.{branch name}-backup
on your fork before attempting to update it.ppy:master
, discarding all of its differing commits. By default, ppy:master
will be merged into the target branch.Click the Run workflow
button and wait for the workflow to complete. If you're curious about how the tool works, click on the Sync with ppy:master
workflow task.
See also: Forking Workflow | Atlassian Git Tutorial
Within your fork of the osu! wiki, you are free to make any changes and save them. Commits are individual "save points" of the repository. Branches are workspaces, which let you switch between multiple versions of the repository. To make your workflow easier and keep the history of the wiki clean and free from noise, follow these guidelines:
master
, and only keep your changes in there. Give it a meaningful name, such as update-staff-log
.Rewrite the section about jump patterns
says a lot more than Update en.md
.A pull request shows other people how your edits will affect the files. Add some information to your pull request to explain your intentions:
Title
: a very short descriptive title for your changes in English, together with the article's name. In case of a translation, start with the two-letter language name of your translations in brackets. Examples:
[FR] Add `BBCode`
Update `Beatmapping` and `Beatmap/Difficulty`
Description
: anything you want to signal to the maintainers and other potential reviewers. Examples:
Allow edits from maintainers
checkbox, as it will allow the wiki maintainers to help you improve the pull request when necessaryReviews are best applied directly through the GitHub web interface. Use the Add suggestion to batch
button when in the Files changed
tab to apply multiple reviews simultaneously.
You may also use the Commit suggestion
button to apply a single suggestion individually, provided that you make commits sparingly and with informative messages.
Using this system will automatically mark suggestions as resolved. When applying reviews manually (e.g. when the reviewer didn't add a direct suggestion), mark them as resolved after committing the change to prevent forgetting any. Letting GitHub apply reviews automatically is preferred, as it ensures that suggestions are applied correctly and prevents any manual copy errors.
There are two reasons for why a conflict could have happened:
Depending on the severity of the conflicts, you have two options on how to fix this:
Resolve conflicts
button, click on that. This will open a slightly different version of the web editor.
<<<<<<<
to the =======
is your changes, whereas everything from =======
to >>>>>>> master
is what's in the ppy/master
branch.<<<<<<<
, =======
, and >>>>>>> master
markings.Mark as resolved
(this is only available when all conflicting parts of the file are resolved).Resolve conflicts
button is blocked due to the conflicts being too complicated for GitHub, you are out of luck and will need to update your branch and make your changes again.