|
1 | | -# Contributors Guide |
2 | | - |
3 | | -So you've decided to become a contributor to our project. Excellent! |
4 | | - |
5 | | -We are always looking for new developers, so if you're new, |
6 | | -please check out our [Getting Started guide](https://wiki.multitheftauto.com/wiki/Coding_info). |
7 | | - |
8 | | -But before we can start accepting your code, there are a couple of |
9 | | -things you should know about how we work. |
10 | | - |
11 | | -This document mostly contains guidelines and rules as to how your |
12 | | -code should be structured and how it can be committed without |
13 | | -upsetting any fellow contributors. |
14 | | - |
15 | | -## Where to code |
16 | | - |
17 | | -As a new potential contributor, you will need to fork our repository and make |
18 | | -commits to your own "branch". Then you can send us a pull request. |
19 | | - |
20 | | -Our _`master`_ branch is the main development branch containing the |
21 | | -latest, bleeding-edge code. |
22 | | - |
23 | | -Our _other_ branches contain groundbreaking research, radical ideas and other |
24 | | -work-in-progress changes that are meant to be merged into `master` at |
25 | | -a later point in time. |
26 | | - |
27 | | -If you're a collaborator, it's your choice whether to push branches to this |
28 | | -repository or to your own fork. |
29 | | - |
30 | | -**Branches are "topical" and should not be "personal" to each |
31 | | -user.** This means that a branch should be created for a new feature, |
32 | | -not for a user specific playground. |
33 | | - |
34 | | -## What to code |
35 | | - |
36 | | -Generally, please try submit pull requests that resolve existing |
37 | | -[issues](https://github.com/multitheftauto/mtasa-blue/issues). |
38 | | - |
39 | | -If you're looking for something to work on, take a look at the ["good first issue"] |
40 | | -label, or our [milestones]. |
41 | | - |
42 | | -["good first issue"]: https://github.com/multitheftauto/mtasa-blue/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22 |
43 | | -[milestones]: https://github.com/multitheftauto/mtasa-blue/milestones?direction=asc&sort=due_date |
44 | | - |
45 | | -Of course, if you're interested in something else, feel free to experiment |
46 | | -and submit it. But discussing the feature beforehand, in an issue, will |
47 | | -make your pull request more likely to be merged in a timely fashion. |
48 | | - |
49 | | -## Committing code |
50 | | - |
51 | | -**Make sure your code contributions follow the [Style Guide]**. |
52 | | - |
53 | | -[Style Guide]: https://github.com/multitheftauto/mtasa-blue/wiki/Style-Guide |
54 | | - |
55 | | -**Commits should be tested when added to master.** Commits |
56 | | -that 'need to be fixed later' which directly affect the state of |
57 | | -the mod will be reverted other than in exceptional circumstances. |
58 | | - |
59 | | -**Commit messages should** |
60 | | - |
61 | | -- be consistent |
62 | | -- always give a clear indication of what has been changed without having to look at the code |
63 | | -- include issue numbers, using [GitHub keywords](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) where necessary |
64 | | -- [follow the seven rules identified here](http://chris.beams.io/posts/git-commit/) |
65 | | - |
66 | | -The most important of the [seven rules](http://chris.beams.io/posts/git-commit/) has been copied below, but please read the article: |
67 | | - |
68 | | -1. Separate subject from body with a blank line |
69 | | -2. Limit the subject line to around 60-80 characters (the [seven rules] say 50, but we think ~70 is okay) |
70 | | -3. Use the imperative mood in the subject line |
71 | | -4. Use the body to explain what and why vs. how |
72 | | - |
73 | | -**Follow up (addendum) commits should refer to the previous commit.** Do this by |
74 | | -including the previous commit-identifier SHA and, if there's space, a summarised commit message in |
75 | | -the new commit message. Doing this will help identify related commits |
76 | | -if they are viewed at a later date. |
77 | | - |
78 | | -**Try to keep pull requests small — they should be about one thing.** When you do multiple things |
79 | | -in one pull request, it's hard to review. If you're fixing stuff as you go, you might want |
80 | | -to make atomic commits and then cherry-pick those commits into separate branches, |
81 | | -leaving the pull request clean. |
82 | | - |
83 | | -**Read the ["Code Review"] guide** for more guidelines about the code review process. |
84 | | - |
85 | | -**Examples**. Here are some examples of commit messages with a short and descriptive title in the imperative mood. |
86 | | - |
87 | | -1. Here we also have a description that explains the content of the commit. |
88 | | - ``` |
89 | | - Fix vehicle model memory leaks in engineReplaceModel |
90 | | - |
91 | | - Fixed 3 memory leaks: |
92 | | - - clump model leak |
93 | | - - vehicle visual data (dummies) leak |
94 | | - - engineReplaceModel added extra references to TXD, and this was not getting unloaded at times |
95 | | - ``` |
96 | | -
|
97 | | -2. Here we have a longer description that explains how to use the feature. The body is wrapped at 72 characters. |
98 | | - ``` |
99 | | - Add "beta" CVAR "_beta_qc_rightclick_command" |
100 | | - |
101 | | - This variable lets you execute a command of your choice when you right |
102 | | - click the "quick connect" button. |
103 | | - |
104 | | - By default this CVAR is set to "reconnect", but you can set it to |
105 | | - anything - "connect orange.mtasa.com" or "nick timw0w". |
106 | | - |
107 | | - In the console, type "_beta_qc_rightclick_command" and press enter. This |
108 | | - will tell you the current value of the CVAR. |
109 | | - |
110 | | - You can do "_beta_qc_rightclick_command=nick timw0w" to change the |
111 | | - value of the CVAR. |
112 | | - ``` |
113 | | -
|
114 | | -3. Here we say `Fix #1115` so that GitHub automatically closes issue #1115. There's no description. |
115 | | - ``` |
116 | | - Fix #1115: add async encode/decodeString |
117 | | - ``` |
118 | | -
|
119 | | -4. There was no specific issue being fixed here, but GitHub's squash-merge feature automatically appended `(#1177)`, |
120 | | - telling us which pull request created this commit. There's no description. |
121 | | - ``` |
122 | | - Add "remember this option" checkbox to NVidia Optimus dialog (#1177) |
123 | | - ``` |
124 | | -
|
125 | | -5. Here we refer to a previous commit. |
126 | | - ``` |
127 | | - Addendum to a80f8d6: fix Windows build error |
128 | | - ``` |
129 | | -
|
130 | | -## Reviewing code |
131 | | -
|
132 | | -Contributors should try to review other contributor's commits and provide |
133 | | -feedback as much as possible. |
134 | | -
|
135 | | -Please read our ["Code Review"] article for information on how to review code effectively. |
136 | | -
|
137 | | -["Code Review"]: https://github.com/multitheftauto/mtasa-blue/wiki/Code-Review |
138 | | -
|
139 | | -<!-- |
140 | | -
|
141 | | -TODO(qaisjp): the below content should be part of a code of conduct instead |
142 | | -
|
143 | | -Ratings and comments are open for the public to review code and provide |
144 | | -feedback. Please be mature and civilised when posting comments. |
145 | | -
|
146 | | -Make sure you make appropriate use of the GitHub Reactions feature to |
147 | | -rate commits or express agreement/disagreement to a comment. This avoids |
148 | | -spammy comments such as "+1", "-1", "Nice one!", etc. |
149 | | -
|
150 | | -Since you can only react to comments, not commits, feel free to create |
151 | | -the initial "+1" comment in response to a commit. However, future |
152 | | -similar reactions to a commit should be to the first response comment. |
153 | | -
|
154 | | ---> |
155 | | -
|
156 | | -## Gaining and losing merge rights |
157 | | -
|
158 | | -Merge rights allow you to merge your own approved pull requests and |
159 | | -review other people's pull requests. |
160 | | -
|
161 | | -We grant merge rights after you have proven yourself to be competent, |
162 | | -which is generally after 3-5 pull requests. This is not fixed and depends |
163 | | -on the extent of your contributions, community status and other factors. |
164 | | -
|
165 | | -The subject matter of your pull requests do not matter — we are more interested in, |
166 | | -once granted merge rights, whether you are capable of maintaining |
167 | | -a high standard of code and remaining cohesive with other project collaborators. |
168 | | -
|
169 | | -After gaining merge rights, if your contributions are of a consistently low standard, |
170 | | -or you fail to stick to the rules, your permissions will be revoked. |
171 | | -
|
172 | | -## Merging pull requests |
173 | | -
|
174 | | -Before merging, enforced by GitHub's branch protection, pull requests **require**: |
175 | | -- Linux and Windows status checks to pass |
176 | | -- 1 pull request review |
177 | | -
|
178 | | -If the pull request is large, try and only merge if there at least 2 pull request reviews. |
179 | | -This isn't enforced via branch protection, but please try and stick to this convention |
180 | | -(... unless nobody else is reviewing your PR). |
181 | | -
|
182 | | -Branch protection is **not enforced** for repository administrators, |
183 | | -and those people are therefore not required to send pull requests. Individual repository admins may, |
184 | | -for the greater good, pledge to submit pull requests despite this lack of enforcement. |
185 | | -
|
186 | | -For informational purposes, the current repository administrators are those marked as _The MTA Team_ on |
187 | | -[this list](https://forum.mtasa.com/staff/). |
188 | | -
|
189 | | -**Merge button** |
190 | | -
|
191 | | -Generally use the "Squash and merge" button. If multiple commits are needed because you think |
192 | | -having the separate commits are useful, use "Rebase and merge". |
| 1 | +This information is now available at [mtasa-docs (mtasa-blue CONTRIBUTING.md)](https://github.com/multitheftauto/mtasa-docs/blob/main/mtasa-blue/CONTRIBUTING.md). |
0 commit comments