|
@@ -1,106 +1,66 @@
|
|
|
1
1
|
# osu! wiki contribution guide
|
|
2
2
|
|
|
3
|
-
Thanks for your interest in making the osu! wiki better! This
|
|
3
|
+
Thanks for your interest in making the osu! wiki better! This article covers the contribution process step by step. In case you are familiar with GitHub, feel free to follow the common feature-branch workflow for proposing changes and skip to the [self-check](#self-check) section.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
New contributors are not expected to be familiar with GitHub or [git](https://git-scm.com/), because they're tools mainly tailored towards developers. Don't worry if you don't get something right the first time — a [wiki maintainer](/wiki/People/osu!_wiki_maintainers) will either point you in the right direction or fix it for you.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
In case you need tips or advice during any stage, don't hesitate to ask in the `#osu-wiki` channel of the [osu! Discord server](/wiki/Community/osu!_Discord_server).
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
## Areas of interest
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
2. [Sign in](https://github.com/login).
|
|
13
|
-
3. Continue to [Forking](#forking).
|
|
11
|
+
If you want to help, but don't know where to start, see [osu! wiki maintenance § Routines](/wiki/osu!_wiki/Maintenance#routines) for a list of tasks which need to be performed regularly, and for ways to help other wiki editors. To familiarise yourself with the formatting language used on the wiki, check Adam Pritchard's [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+
## Editing the wiki
|
|
16
14
|
|
|
17
|
-
|
|
15
|
+
*For a generalised contribution process, see [GitHub flow - GitHub Docs](https://docs.github.com/en/get-started/quickstart/github-flow)*
|
|
18
16
|
|
|
19
|
-
|
|
17
|
+
The osu! wiki articles are stored on [GitHub][osu_wiki]. To contribute, do the following:
|
|
20
18
|
|
|
21
|
-
|
|
19
|
+
0. [Create](https://github.com/signup) a GitHub account.
|
|
20
|
+
1. Open the [`ppy/osu-wiki`][osu_wiki] repository and click `Fork` in the top-right corner to make a controlled copy of the wiki. To return to your fork, go to [`ppy/osu-wiki`][osu_wiki] and press `Fork` again.
|
|
22
21
|
|
|
23
|
-
|
|
22
|
+
- If you've made a fork some time ago, sync it according to [Best practices § Syncing the fork](/wiki/osu!_wiki/Contribution_guide/Best_practices#syncing-the-fork).
|
|
24
23
|
|
|
25
|
-
|
|
24
|
+
2. Read [Best practices § Making changes](/wiki/osu!_wiki/Contribution_guide/Best_practices#making-edits) and perform necessary edits. While you are free to use any application of your choice, the osu! wiki has detailed instructions on two workflows:
|
|
26
25
|
|
|
27
|
-
|
|
26
|
+
- [GitHub web-based editor](/wiki/osu!_wiki/Contribution_guide/GitHub_web-based_editor) (online, no installation required).
|
|
27
|
+
- [GitHub Desktop](/wiki/osu!_wiki/Contribution_guide/GitHub_Desktop) (offline, offers more control).
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
## Self-check
|
|
30
30
|
|
|
31
|
-
|
|
31
|
+
When you are done editing, take some time to proofread your work. Go through the following quick checklist:
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
- **Tone of delivery**: the osu! wiki articles, with rare exceptions, must be written using a neutral register.
|
|
34
|
+
- **Style and grammar**: the articles should be clear, understandable, and require no significant mental effort from the reader. Be consistent and avoid overcomplicated or abrupt sentences. Use editors with built-in spell checkers, such as [Google Docs](https://docs.google.com), to expose typos and grammatical or syntax errors.
|
|
35
|
+
- **[Content parity](/wiki/Article_styling_criteria/Writing#content-parity)**: translations must contain the same information as the original articles (differences in punctuation, wording, or formatting are obviously expected). Instead of changing the contents of the translation, [open an issue](https://github.com/ppy/osu-wiki/issues/new) or an extra pull request for the original if you feel it is incomplete, inaccurate, or outdated.
|
|
36
|
+
- **Structure and formatting**: preview your article with a tool such as [jbt's Markdown Editor](https://jbt.github.io/markdown-editor/) to make sure it looks exactly how you wanted it to be.<!-- TODO(TicClick): we really need an article on markup features specific to the osu! wiki-->
|
|
37
|
+
- **All images and other non-text files** must be [under 1 megabyte](/wiki/Article_styling_criteria/Formatting#file-size). **Screenshots** need to use the default osu! skin and [specific settings](/wiki/Article_styling_criteria/Formatting#screenshots-of-gameplay), including the maximum dimensions of 1280×720.
|
|
34
38
|
|
|
35
|
-
|
|
39
|
+
For more specific writing and formatting standards, refer to the [article styling criteria](/wiki/Article_styling_criteria). It's not recommended to read it all at once — a reviewer will likely point out if something needs to be corrected either way.
|
|
36
40
|
|
|
37
|
-
|
|
41
|
+
## Pull request
|
|
38
42
|
|
|
39
|
-
|
|
43
|
+
After the changes are double-checked, committed, and pushed to your fork, you need to propose them to the wiki maintainers by opening a pull request:
|
|
40
44
|
|
|
41
|
-
|
|
45
|
+
1. In **your fork** of the osu! wiki, find the dropdown which says `master↓`, and select the branch with your changes.
|
|
46
|
+
2. Click the `Contribute↓` button and select `Open pull request`.
|
|
47
|
+
3. Fill in the details according to [Best practices § Opening a pull request](/wiki/osu!_wiki/Contribution_guide/Best_practices#opening-a-pull-request) and click `Create pull request`.
|
|
42
48
|
|
|
43
|
-
|
|
49
|
+
## Review
|
|
44
50
|
|
|
45
|
-
|
|
51
|
+
All changes to the osu! wiki are moderated. During that stage, other collaborators point out possible mistakes and ways to fix them, either in free form, or by suggesting direct edits to the pull request. Just like with any other peer review, you need to address the comments by [applying the suggestions](/wiki/osu!_wiki/Contribution_guide/Best_practices#applying-reviews), or by explaining why you'd rather keep things your way.
|
|
46
52
|
|
|
47
|
-
|
|
53
|
+
If no one has checked in after a couple of days, try the following:
|
|
48
54
|
|
|
49
|
-
|
|
55
|
+
- Make sure you have resolved all suggestions — people may be waiting on your responses.
|
|
56
|
+
- Ask other osu! wiki editors in the [osu! Discord server](/wiki/Community/osu!_Discord_server) (`#osu-wiki` channel) or in the GitHub comments.
|
|
57
|
+
- To get help with the translation, check a couple of merged pull requests for your language and get in touch with their reviewers and/or authors ([example GitHub query](https://github.com/ppy/osu-wiki/pulls?q=is:pr+is:merged+[ID])).
|
|
58
|
+
- Ask your friends for a quick look!
|
|
50
59
|
|
|
51
|
-
|
|
60
|
+
In addition to a manual review process, the osu! wiki repository has [a set of automated checks](/wiki/osu!_wiki/Maintenance#ci-checks), which ensure that your changes follow the common style of the wiki and are free from formatting errors. To see their status, open the `Actions` tab of your pull request and follow the diagnostic messages under the errors, if there are any.
|
|
52
61
|
|
|
53
|
-
|
|
62
|
+
## Merge
|
|
54
63
|
|
|
55
|
-
- [
|
|
56
|
-
- [GitHub Desktop](/wiki/osu!_wiki/Contribution_guide/GitHub_Desktop) - edit locally; this is best for single and/or multi article edits (this includes uploading, deleting, and moving images or other files).
|
|
64
|
+
Your changes will eventually be checked by one of the [wiki maintainers](/wiki/People/osu!_wiki_maintainers), usually after reviews by other collaborators. If nothing happens after a reasonable amount of time, ask in the comments of the pull request, or in the `#osu-wiki` channel of the [osu! Discord server](/wiki/Community/osu!_Discord_server). Your changes will appear on the osu! wiki shortly after the merge (in rare cases, this may take up to five hours).
|
|
57
65
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
**When you complete either *GitHub Web Interface* or *GitHub Desktop* article, you can continue to the next section.**
|
|
61
|
-
|
|
62
|
-
## Finishing
|
|
63
|
-
|
|
64
|
-
### Opening a pull request
|
|
65
|
-
|
|
66
|
-
1. Go to the [`ppy/osu-wiki` repo](https://github.com/ppy/osu-wiki).
|
|
67
|
-
|
|
68
|
-
2. If you were quick enough, you may see this yellow banner.
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
3. If you see it, click on the `Compare & pull request` button (skip to step 8). If not, click the `New pull request` button (continue to step 4).
|
|
73
|
-
|
|
74
|
-
4. On the next page, if you see these two buttons as pictured below, click the `compare across forks`.
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
5. Click on the `head fork` dropdown and select the one with your username (it should be the second one).
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
6. Click on the `compare` dropdown and select the one with the branch you had created (these are listed alphabetically).
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
7. Click `Create pull request`.
|
|
87
|
-
|
|
88
|
-
8. Enter the title in English. This should be a very brief explanation of what you changed.
|
|
89
|
-
|
|
90
|
-
For article translations, include the two-letter language name of your translations in brackets before the title. Your title can just be the name of the article(s) that you are translating. For example, `[FR] BBCode` would indicate that you are updating the French translation of the [BBCode article](/wiki/BBCode).
|
|
91
|
-
|
|
92
|
-
9. Fill in the description box with a summary of your changes. You should mention any information relevant to your pull request, such as its completion status and anything you want reviewers to know. You can also make your pull request automatically close issues upon merge by writing "resolves #1" or "closes #1", etc. in the description (see [Closing issues using keywords](https://help.github.com/articles/closing-issues-using-keywords/) on GitHub Help).
|
|
93
|
-
|
|
94
|
-
10. Once you are ready, click `Create pull request`.
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
11. See [Reviews](#reviews) and [Merging](#merging) below.
|
|
99
|
-
|
|
100
|
-
### Reviews
|
|
101
|
-
|
|
102
|
-
Once you have created your pull request, other osu! wiki editors may review your changes to help catch some mistakes you may have missed. **You will need to keep up with these reviews,** otherwise your pull request may be marked for closure! If you want someone to review your pull request, you can ask other osu! wiki editors in the [osu!dev Discord](https://discord.gg/ppy) (`#osu-wiki` channel) or in the GitHub comments.
|
|
103
|
-
|
|
104
|
-
### Merging
|
|
105
|
-
|
|
106
|
-
For your changes to become appear live on the osu! wiki, your pull request has to be merged. Once your pull request has been reviewed and approved, you can either use the commenting section in GitHub to ask someone to merge it, or do the same in the [osu!dev Discord](https://discord.gg/ppy) (`#osu-wiki` channel). Once it is merged, your changes will take up to five hours to appear live on the osu! wiki.
|
|
66
|
+
[osu_wiki]: https://github.com/ppy/osu-wiki
|