Skip to content

Latest commit

 

History

History
192 lines (133 loc) · 7.97 KB

CONTRIBUTING.md

File metadata and controls

192 lines (133 loc) · 7.97 KB
Raw

Contributors Guide

So you've decided to become a contributor to our project. Excellent!

We are always looking for new developers, so if you're new, please check out our Getting Started guide.

But before we can start accepting your code, there are a couple of things you should know about how we work.

This document mostly contains guidelines and rules as to how your code should be structured and how it can be committed without upsetting any fellow contributors.

Where to code

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.

What to code

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.

Committing code

Make sure your code contributions follow the Style Guide.

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

The most important of the seven rules has been copied below, but please read the article:

  1. Separate subject from body with a blank line
  2. Limit the subject line to around 60-80 characters (the [seven rules] say 50, but we think ~70 is okay)
  3. Use the imperative mood in the subject line
  4. 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.

  1. 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

  2. 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.

  3. Here we say Fix #1115 so that GitHub automatically closes issue #1115. There's no description.

    Fix #1115: add async encode/decodeString

  4. 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)

  5. Here we refer to a previous commit.

    Addendum to a80f8d6: fix Windows build error

Reviewing code

Contributors should try to review other contributor's commits and provide feedback as much as possible.

Please read our "Code Review" article for information on how to review code effectively.

Gaining and losing merge rights

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.

Merging pull requests

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".