wiki/osu!_wiki/Contribution_guide/en.md CHANGED
@@ -1,106 +1,66 @@
1
1
  # osu! wiki contribution guide
2
2
 
3
- Thanks for your interest in making the osu! wiki better! This quick-start guide is intended for newcomers that have never worked with GitHub and the osu! wiki contribution workflow before. If you already have experience using GitHub, feel free to skip this guide and follow the common feature-branch workflow for content updates in this repository.
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
- If, during any part, you are confused and/or need further help, feel free to send a message to the [osu!dev Discord](https://discord.gg/ppy) (`#osu-wiki` channel).
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/osu!_wiki/Maintenance/List_of_maintainers) will either point you in the right direction or fix it for you.
6
6
 
7
- ## Getting started
7
+ In case you need tips or advice during any stage, don't hesitate to ask in the `#osu-wiki` channel of the [osu!dev Discord server](/wiki/Community/osu!dev_Discord_server).
8
8
 
9
- ### Registering
9
+ ## Areas of interest
10
10
 
11
- 1. [Sign up](https://github.com/join) for a GitHub account if you don't have one.
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
- ### Forking
13
+ ## Editing the wiki
16
14
 
17
- 1. Go to the [`osu-wiki` repo](https://github.com/ppy/osu-wiki).
15
+ *For a generalised contribution process, see [GitHub flow - GitHub Docs](https://docs.github.com/en/get-started/quickstart/github-flow)*
18
16
 
19
- 2. Click `Fork`.
17
+ The osu! wiki articles are stored on [GitHub][osu_wiki]. To contribute, do the following:
20
18
 
21
- ![](img/fork.jpg)
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
- 3. Click `Fork` again to go to your fork.
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
- 4. Seeing something similar to the image below means you made a fork of `ppy/osu-wiki` repo and that you are on your fork.
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
- ![](img/forked.jpg)
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
- 5. Continue to [Syncing your fork](#syncing-your-fork).
29
+ ## Self-check
30
30
 
31
- ### Syncing your fork
31
+ When you are done editing, take some time to proofread your work. Go through the following quick checklist:
32
32
 
33
- 1. Go to your fork of the `osu-wiki` repo.
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
- 2. Above the files, there is some text to tell you if your branch is either "behind", "ahead", or "even" with `ppy:master`. If it says that the branch is either "behind" or "ahead and behind" with any amount of behind-commits, your branch is outdated.
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
- ![](img/fork-even.jpg "OK \(no commits and not outdated\)")
41
+ ## Pull request
38
42
 
39
- ![](img/fork-ahead.jpg "OK \(these are your commits\)")
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
- ![](img/fork-behind.jpg "Potentially bad \(your branch is outdated\)")
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
- ![](img/fork-ahead-behind.jpg "Potentially bad \(your branch is outdated with your commits\)")
49
+ ## Review
44
50
 
45
- 3. This isn't much of a problem; that is, if you aren't going to edit a file that was already changed which may be unlikely the more commits you are behind.
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
- 4. To resolve this, see the [My branch is out of date!](/wiki/osu!_wiki/Contribution_guide/Common_Issues#my-branch-is-out-of-date!) section in the Common Issues article.
53
+ If no one has checked in after a couple of days, try the following:
48
54
 
49
- 5. When you complete step 4, continue to [Editing online or locally](#editing-online-or-locally).
55
+ - Make sure you have resolved all suggestions people may be waiting on your responses.
56
+ - Ask other osu! wiki editors in the [osu!dev Discord server](/wiki/Community/osu!dev_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%3Apr+is%3Amerged+%5BID%5D)).
58
+ - Ask your friends for a quick look!
50
59
 
51
- ## Editing online or locally
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
- At this point, you have two choices:
62
+ ## Merge
54
63
 
55
- - [GitHub Web Interface](/wiki/osu!_wiki/Contribution_guide/GitHub_Web_Interface) - edit online; this is best for single article edits.
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/osu!_wiki/Maintenance/List_of_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!dev Discord server](/wiki/Community/osu!dev_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
- *Note: You are not limited to the two choices listed above for editing. To keep this guide short and simple, these articles will not discuss using other tools in-depth or at all. There are other third party applications that can do more or less than what the GitHub Web Interface and GitHub Desktop already do.*
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
- ![](img/github-recent.jpg)
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
- ![](img/compare-across-forks-no.jpg "No good.")
77
-
78
- 5. Click on the `head fork` dropdown and select the one with your username (it should be the second one).
79
-
80
- ![](img/head-fork.jpg)
81
-
82
- 6. Click on the `compare` dropdown and select the one with the branch you had created (these are listed alphabetically).
83
-
84
- ![](img/compare-branch.jpg)
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
- ![](img/new-pull-request.png)
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