-
Notifications
You must be signed in to change notification settings - Fork 17
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
chore: update contribution guidelines (#3)
* chore: update contribution guidelines * chore(contributing): improve commit type descriptions * chore(contributing): recommend vscode
- Loading branch information
1 parent
2734df4
commit 4aed531
Showing
2 changed files
with
64 additions
and
166 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,200 +1,99 @@ | ||
| # Contributing to Qbox | ||
|
|
||
| First of all, thank you for taking the time to contribute! | ||
| Thank you for taking the time to contribute! | ||
|
|
||
| These guidelines will help you help us in the best way possible regardless of your skill level. We ask that you try to read everything related to the way you'd like to contribute and try and use your best judgement for anything not covered. | ||
|
|
||
| ### Table of Contents | ||
| Make sure to also read our [Contributor Code of Conduct](./CODE_OF_CONDUCT.md). | ||
|
|
||
| [Code of Conduct](#code-of-conduct) | ||
| If you still have further questions after reading be sure to join the [Qbox Discord server][discord link]. | ||
|
|
||
| [I don't want to read this whole thing, I just have a question!!!](#i-dont-want-to-read-this-whole-thing-i-just-have-a-question) | ||
| ## Issues | ||
|
|
||
| [How Can I Contribute?](#how-can-i-contribute) | ||
| * [Reporting Bugs](#reporting-bugs) | ||
| * [Suggesting Features / Enhancements](#suggesting-features--enhancements) | ||
| * [Your First Code Contribution](#your-first-code-contribution) | ||
| * [Pull Requests](#pull-requests) | ||
| Open a new issue to report a bug or request a new feature or improvement. | ||
|
|
||
| [Styleguides](#styleguides) | ||
| * [Git Commit Messages](#git-commit-messages) | ||
| * [Lua Styleguide](#lua-styleguide) | ||
| * [JavaScript Styleguide](#javascript-styleguide) | ||
| If you want to ask a question, issues are not the place to do so. Please join our [Discord server][discord link] and ask over there instead. | ||
|
|
||
| Before opening a new issue: | ||
|
|
||
| - [Search](https://github.com/issues?q=is%3Aissue+org%3AQbox-Project) for existing issues; maybe someone else already experienced the same problem that you're having! Duplicate issues will be closed. | ||
| - Download the latest release of the resource you are opening the issue for to make sure that it wasn't already fixed. Issues that are already fixed are considered invalid and will be closed. | ||
|
|
||
| ## Code of Conduct | ||
| When opening a new issue, make sure to pick the right type of form and fill it out. The more information you provide, the easier it will be for us to work on your new issue. Issues that are invalid or do not follow the correct form may be ignored or even closed. | ||
|
|
||
| - Refrain from using languages other than English. | ||
| - Refrain from discussing any politically charged or inflammatory topics. | ||
| - Uphold mature conversations and respect each other; excessive profanity, hate speech or any kind of harassment will not be tolerated. | ||
| - No advertising of any kind. | ||
| - Follow these guidelines. | ||
| - Do not mention members of github unless a question is directed at them and can't be answered by anyone else. | ||
| - Do not mention any of the development team for any reason. We will read things as we get to them. | ||
| ## Pull Requests | ||
|
|
||
| ## I don't want to read this whole thing I just have a question!!! | ||
| Open a new pull request to contribute code. | ||
|
|
||
| > **Note:** Please don't file an issue to ask a question. You'll get faster results by using the resources below. | ||
| You can use your own editor of choice, but we recommend using [VSCode](https://code.visualstudio.com/) with these extensions: | ||
|
|
||
| * [Qbox Discord](https://discord.gg/Z6Whda5hHA) | ||
| - [GitLens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens) | ||
| - [Lua Language Server](https://marketplace.visualstudio.com/items?itemName=sumneko.lua) | ||
| - [EditorConfig](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) | ||
| - [CfxLua IntelliSense](https://marketplace.visualstudio.com/items?itemName=overextended.cfxlua-vscode) | ||
|
|
||
| If you are new to contributing code, you can check out and try to fix issues marked with [`good first issue`](https://github.com/issues?q=is%3Aissue+is%3Aopen+org%3AQbox-Project+label%3A%22good+first+issue%22). | ||
|
|
||
| If you want to contribute code but don't know what to do, please check out issues marked with [`help wanted`](https://github.com/issues?q=is%3Aissue+is%3Aopen+org%3AQbox-Project+label%3A%22help+wanted%22) as those are issues that we actually *need* help with. | ||
|
|
||
| If you want to contribute code unrelated to an existing issue, you should open an issue yourself or ask over on the [Discord server][discord link] to discuss it with our team and ask whether your change is wanted, especially if you are planning on adding new features or large designs. | ||
|
|
||
| Before opening a pull request: | ||
|
|
||
| - Make sure that your contribution fits our [code conventions](#code-conventions) described below. After opening a pull request your code will be checked according to them. | ||
| - Make sure that your pull request is small and focused. Break it into multiple smaller pull requests if not (see [Small Pull Request Manifesto](https://github.com/PlaytikaOSS/small-pull-request-manifesto)). | ||
| - It is recommended to test your changes to make sure they work and don't break existing functionality. | ||
|
|
||
| When opening a pull request, make sure to follow the template and explain your changes. If you are trying to contribute something related to a GitHub issue, make sure to mention it as well. | ||
|
|
||
| ## Code Conventions | ||
|
|
||
| Below are conventions that you must follow when contributing code. | ||
|
|
||
| ## How Can I Contribute? | ||
| ### Commit Message Conventions | ||
|
|
||
| ### Reporting Bugs | ||
| - The first line of a commit message must be 72 characters at most. | ||
| - Commit messages and pull request titles must follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). | ||
| - Use `fix:` when patching a bug. | ||
| - Use `feat:` when introducing a new feature. | ||
| - Use `refactor:` when altering code without changing functionality. | ||
| - Use `chore:` when your changes don't alter production code. | ||
| - Append a `!` after the type/scope of the feature when you change code and introduce a breaking API change. Optionally add a footer to the bottom of your commit message separated by 2 newlines, starting with `BREAKING CHANGE:`, and explaining the breaking change. | ||
|
|
||
| The easiest way to contribute for most people is just to report bugs you find cause if nobody reports it there's a chance we'll never know it exists and then we'll never fix it. | ||
| ### Lua Conventions | ||
|
|
||
| Before creating bug reports, please check [this list](#before-submitting-a-bug-report) as you might find out that you don't need to create one. When you are creating a bug report, please [include as many details as possible](#how-do-i-submit-a-good-bug-report). Fill out the bug-report template with the information it asks for helps us resolve issues faster. | ||
| #### General Style | ||
|
|
||
| > **Note:** If you find a **Closed** issue that seems like it is the same thing that you're experiencing, open a new issue and include a link to the original issue in the body of your new one. | ||
| - Use 4 space indentation. | ||
| - Prefer creating local variables over global ones. | ||
| - Don't repeat yourself. If you're using the same operations in multiple different places convert them into a flexible function. | ||
| - Exported functions must be properly annotated (see [LuaLS Annotations](https://luals.github.io/wiki/annotations/)). | ||
| - Utilize [ox_lib](https://overextended.dev/ox_lib) to make your life easier. Prefer lib calls over native ones. | ||
| - Make use of config options where it makes sense to make features optional and/or customizable. Configs should not be modified by other code. | ||
|
|
||
| #### Before Submitting A Bug Report | ||
| #### Optimization & Security | ||
|
|
||
| * **Check the docs** There's a chance what you see as a bug might just work differently than you expect and if you think it could work better consider a feature enhancement report instead. | ||
| * **Search the [discord](https://discord.gg/Z6Whda5hHA)** to see if anyone else has run into the issue and see if it was solved through user error or code changes. (if the code change isn't pending a PR and you know what you're doing consider submitting one following [Pull Requests](#pull-requests) ) | ||
| * **Determine which resource the problem should be reported in**. If the bug is related to the inventory for example report this bug under qb-inventory rather than under qb-core or some other resource. | ||
| * **Perform a [cursory search](https://github.com/search?q=is%3Aissue+user%3Aqbox-project)** to see if the problem has already been reported. If it has **and the issue is still open**, add a comment to the existing issue instead of opening a new one. | ||
| - Consider [this Lua Performance guide](https://springrts.com/wiki/Lua_Performance). | ||
| - Don't create unnecessary threads. Always try to find a better method of triggering events. | ||
| - Set longer `Wait` calls in distance checking loops when the player is out of range. | ||
| - Don't waste cycles; job specific loops should only run for players with that job. | ||
| - When possible don't trust the client, *especially* with transactions. | ||
| - Balance security and optimizations. | ||
| - Use `#(vector3 - vector3)` instead of `GetDistanceBetweenCoords()`. | ||
| - Use `myTable[#myTable + 1] = 'value'` instead of `table.insert(myTable, 'value')`. | ||
| - Use `myTable['key'] = 'value'` instead of `table.insert(myTable, 'key', 'value')`. | ||
|
|
||
| #### How Do I Submit A (Good) Bug Report? | ||
| #### Naming | ||
|
|
||
| Bugs are tracked as [GitHub issues](https://guides.github.com/features/issues/). After you've determined which resource your bug is related to, create an issue on that repository and provide the following information by filling in bug-report template. | ||
| - Use `camelCase` for local variables and functions. | ||
| - Use `PascalCase` for global variables and functions. | ||
| - Avoid acronyms as they can be confusing and context dependant. | ||
| - Be descriptive; make it easy for the reader. | ||
| - Booleans may be prefixed with `is`, `has`, `are`, etc. | ||
| - Arrays should have plural names. | ||
|
|
||
| Explain the problem and include additional details to help maintainers reproduce the problem: | ||
| ### JavaScript/TypeScript Conventions | ||
|
|
||
| * **Use a clear and descriptive title** for the issue to identify the problem. | ||
| * **Describe the exact steps which reproduce the problem** in as many details as possible. | ||
| * **Provide specific examples to demonstrate the steps**. If something happened with only a specific group or single item but not others, specify that. | ||
| * **Describe the behavior you observed after following the steps** and point out what exactly is the problem with that behavior. | ||
| * **Explain which behavior you expected to see instead and why.** | ||
| * **Include screenshots** which show the specific bug in action or before and after. | ||
| * **If the problem wasn't triggered by a specific action**, describe what you were doing before the problem happened and share more information using the guidelines below. | ||
| Consider following the [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) and the [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html). | ||
|
|
||
| Provide more context by answering these questions if possible: | ||
|
|
||
| * **Did the problem start happening recently** (e.g. after updating to a new version of Qbox?) or was this always a problem? | ||
| * If the problem started happening recently, **can you reproduce the problem in an older version of Qbox?** What's the most recent commit in which the problem doesn't happen? | ||
| * **Can you reliably reproduce the issue?** If not, provide details about how often the problem happens and under which conditions it normally happens. | ||
|
|
||
| Include details about your setup: | ||
|
|
||
| * **When was your Qbox last updated?** | ||
| * **What OS is the server running on**? | ||
| * **Which *extra* resources do you have installed?** | ||
|
|
||
|
|
||
| --- | ||
|
|
||
|
|
||
| ### Suggesting Features / Enhancements | ||
|
|
||
| This section guides you through submitting an enhancement suggestion for Qbox, including completely new features and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your suggestion. | ||
|
|
||
| Before creating enhancement suggestions, please check [this list](#before-submitting-an-enhancement-suggestion) as you might find out that you don't need to create one. When you are creating an enhancement suggestion, please [include as many details as possible](#how-do-i-submit-a-good-enhancement-suggestion). Fill in feature request template, including the steps that you imagine you would take if the feature you're requesting existed. | ||
|
|
||
| #### Before Submitting An Enhancement Suggestion | ||
|
|
||
| * **Make sure it doesn't already exist.** Sounds silly, but there's a lot of features built in to Qbox that people don't realize so take a look through the docs and stuff to make sure it's not already there. | ||
| * **Check if there's already PR which provides that enhancement.** | ||
| * **Determine which resource the enhancement should be suggested in.** Whichever resource the suggestion is about, is where it should go. If the suggestion is about Qbox as a whole, make the suggestion in the qbx-core repository. | ||
| * **Perform a [cursory search](https://github.com/search?q=is%3Aissue+user%3Aqbox-project++&type=issues&state=open)** to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one. | ||
|
|
||
| #### How Do I Submit A (Good) Enhancement Suggestion? | ||
|
|
||
| Enhancement suggestions are tracked as [GitHub issues](https://guides.github.com/features/issues/). After you've determined which resource your enhancement suggestion is related to, create an issue on that repository and provide the following information: | ||
|
|
||
| * **Use a clear and descriptive title** for the issue to identify the suggestion. | ||
| * **Provide a step-by-step description of the suggested enhancement** in as many details as possible. | ||
| * **Provide specific examples to demonstrate the steps**. Include copy/pasteable snippets which you use in those examples, as [Markdown code blocks](https://help.github.com/articles/markdown-basics/#multiple-lines). | ||
| * **Describe the current behavior** and **explain which behavior you expected to see instead** and why. | ||
| * **Include screenshots and animated GIFs** which help you demonstrate the steps or point out the part of Qbox which the suggestion is related to. | ||
| * **Explain why this enhancement would be useful.** | ||
| * **Be creative and unique.** Stealing ideas from popular servers 1:1 detail isn't going to get accepted. | ||
|
|
||
|
|
||
| --- | ||
|
|
||
|
|
||
|
|
||
| ### Your First Code Contribution | ||
|
|
||
| Unsure where to begin contributing to Qbox? You can start by looking through these `beginner` and `help-wanted` issues. | ||
|
|
||
|
|
||
|
|
||
| --- | ||
|
|
||
|
|
||
| ### Pull Requests | ||
|
|
||
| The process described here has several goals: | ||
|
|
||
| - Maintain Qbox's quality. | ||
| - Fix problems that are important to users. | ||
| - Engage the community in working toward the best possible Qbox. | ||
| - Enable a sustainable system for Qbox's maintainers to review contributions. | ||
|
|
||
| Please follow these steps to have your contribution considered by the maintainers: | ||
|
|
||
| 1. Follow all instructions in The Pull Request template. | ||
| 2. Follow the [styleguides](#styleguides). | ||
| 3. Await review by the reviewer(s). | ||
|
|
||
| While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted. | ||
|
|
||
|
|
||
| --- | ||
|
|
||
| ## Styleguides | ||
|
|
||
| ### Git Commit Messages | ||
|
|
||
| * Limit the first line to 72 characters or less. | ||
| * Reference issues and pull requests liberally after the first line. | ||
| * Consider starting the commit message with an applicable emoji: | ||
| * :art: `:art:` when improving the format/structure of the code | ||
| * :racehorse: `:racehorse:` when improving performance | ||
| * :memo: `:memo:` when writing docs | ||
| * :bug: `:bug:` when fixing a bug | ||
| * :fire: `:fire:` when removing code or files | ||
| * :white_check_mark: `:white_check_mark:` when adding tests | ||
| * :lock: `:lock:` when dealing with security | ||
| * :arrow_up: `:arrow_up:` when upgrading dependencies | ||
| * :arrow_down: `:arrow_down:` when downgrading dependencies | ||
| * :shirt: `:shirt:` when removing linter warnings | ||
|
|
||
| ### Lua Styleguide | ||
|
|
||
| All lua code should be done using all the best practices of proper lua using the easiest to read yet fastest/most optimized methods of execution. | ||
|
|
||
| - All exported functions MUST include a properly annotated language server header. See https://github.com/sumneko/lua-language-server/wiki/Annotations | ||
| - Use 4 Space indentation | ||
| - Aim for lua 5.4 (include `lua54 'yes'` in the fxmanifest.lua) | ||
| - Use `PlayerPedId()` instead of `GetPlayerPed(-1)` | ||
| - Use `#(vector3 - vector3)` instead of `GetDistanceBetweenCoords()` | ||
| - Don't create unnecessary threads. always try to find a better method of triggering events | ||
| - Don't repeat yourself.. if you're using the same operations in many different places convert them into a function with flexible variables | ||
| - For distance checking loops set longer waits if you're outside of a range | ||
| - Job specific loops should only run for players with that job, don't waste cycles | ||
| - When possible don't trust the client, esspecially with transactions | ||
| - Balance security and optimizations | ||
| - [Consider this Lua Performance guide](https://springrts.com/wiki/Lua_Performance) | ||
| - Use local varriables everywhere possible | ||
| - Make use of config options where it makes sense making features optional or customizable | ||
| - Instead of `table.insert(myTable, "Value")` use `myTable[#myTable + 1] = "Value"` | ||
| - Instead of `table.insert(ages, "bob", 30)` use `ages["bob"] = 30` | ||
|
|
||
|
|
||
| ### JavaScript Styleguide | ||
|
|
||
| - Use 2 Space indentation | ||
| - Don't repeat yourself.. if you're using the same operations in many different places convert them into a function with flexible variables. | ||
| - Consider following the [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) | ||
| [discord link]: https://discord.gg/Z6Whda5hHA |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters