This document mostly contains guidelines as to how your contributions should be made, as well as information on best practices.
If you're looking for more specific coding conventions or style guidelines, see the Coding Guidelines.
As a new potential contributor, you will need to fork our repository and make commits to your own "branch". Then you can send us a pull request.
Our master branch is the main development branch containing the
latest, bleeding-edge code.
Our other branches contain groundbreaking research, radical ideas and other
work-in-progress changes that are meant to be merged into master at
a later point in time.
If you're a collaborator, it's your choice whether to push branches to this repository or to your own fork.
Branches are "topical" and should not be "personal" to each user. This means that a branch should be created for a new feature, not for a user specific playground.
Generally, please try submit pull requests that resolve existing issues.
If you're looking for something to work on, take a look at the "good first issue" label, or our milestones.
Of course, if you're interested in something else, feel free to experiment and submit it. But discussing the feature beforehand, in an issue, will make your pull request more likely to be merged in a timely fashion.
Make sure your code contributions follow the Coding Guidelines.
Commits should be tested when added to master. Commits that 'need to be fixed later' which directly affect the state of the mod will be reverted other than in exceptional circumstances.
Commit messages should
- be consistent
- always give a clear indication of what has been changed without having to look at the code
- include issue numbers, using GitHub keywords where necessary
- follow the seven rules identified here
The most important of the seven rules has been copied below, but please read the article:
- Separate subject from body with a blank line
- Limit the subject line to around 60-80 characters (the [seven rules] say 50, but we think ~70 is okay)
- Use the imperative mood in the subject line
- Use the body to explain what and why vs. how
Follow up (addendum) commits should refer to the previous commit. Do this by including the previous commit-identifier SHA and, if there's space, a summarised commit message in the new commit message. Doing this will help identify related commits if they are viewed at a later date.
Try to keep pull requests small — they should be about one thing. When you do multiple things in one pull request, it's hard to review. If you're fixing stuff as you go, you might want to make atomic commits and then cherry-pick those commits into separate branches, leaving the pull request clean.
Read the Code Review guide for more guidelines about the code review process.
Examples. Here are some examples of commit messages with a short and descriptive title in the imperative mood.
-
Here we also have a description that explains the content of the commit.
Fix vehicle model memory leaks in engineReplaceModel Fixed 3 memory leaks: - clump model leak - vehicle visual data (dummies) leak - engineReplaceModel added extra references to TXD, and this was not getting unloaded at times -
Here we have a longer description that explains how to use the feature. The body is wrapped at 72 characters.
Add "beta" CVAR "_beta_qc_rightclick_command" This variable lets you execute a command of your choice when you right click the "quick connect" button. By default this CVAR is set to "reconnect", but you can set it to anything - "connect orange.mtasa.com" or "nick timw0w". In the console, type "_beta_qc_rightclick_command" and press enter. This will tell you the current value of the CVAR. You can do "_beta_qc_rightclick_command=nick timw0w" to change the value of the CVAR. -
Here we say
Fix #1115so that GitHub automatically closes issue #1115. There's no description.Fix #1115: add async encode/decodeString -
There was no specific issue being fixed here, but GitHub's squash-merge feature automatically appended
(#1177), telling us which pull request created this commit. There's no description.Add "remember this option" checkbox to NVidia Optimus dialog (#1177) -
Here we refer to a previous commit.
Addendum to a80f8d6: fix Windows build error
Contributors should try to review other contributor's commits and provide feedback as much as possible.
Please read our Code Review document for information on how to review code effectively.
Merge rights allow you to merge your own approved pull requests and review other people's pull requests.
We grant merge rights after you have proven yourself to be competent, which is generally after 3-5 pull requests. This is not fixed and depends on the extent of your contributions, community status and other factors.
The subject matter of your pull requests do not matter — we are more interested in, once granted merge rights, whether you are capable of maintaining a high standard of code and remaining cohesive with other project collaborators.
After gaining merge rights, if your contributions are of a consistently low standard, or you fail to stick to the rules, your permissions will be revoked.
Before merging, enforced by GitHub's branch protection, pull requests require:
- Linux and Windows status checks to pass
- 1 pull request review
If the pull request is large, try and only merge if there at least 2 pull request reviews. This isn't enforced via branch protection, but please try and stick to this convention (... unless nobody else is reviewing your PR).
Branch protection is not enforced for repository administrators, and those people are therefore not required to send pull requests. Individual repository admins may, for the greater good, pledge to submit pull requests despite this lack of enforcement.
For informational purposes, the current repository administrators are those marked as The MTA Team on this list.
Merge button
Generally use the "Squash and merge" button. If multiple commits are needed because you think having the separate commits are useful, use "Rebase and merge".