|
| 1 | +# Contributing guide <!-- omit in toc --> |
| 2 | + |
| 3 | +Thank you for investing your time in contributing to our project! With your contribution you help Garry's Mod Lua developers get accurate and the latest autocomplete suggestions for the GLua API. |
| 4 | + |
| 5 | +In this guide you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR. |
| 6 | + |
| 7 | +## New contributor guide |
| 8 | + |
| 9 | +To get an overview of the project, read the [README](README.md). Here are some general resources to help you get started with open source contributions: |
| 10 | + |
| 11 | +* [Finding ways to contribute to open source on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github) |
| 12 | +* [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git) |
| 13 | +* [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) |
| 14 | +* [Collaborating with pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests) |
| 15 | + |
| 16 | + |
| 17 | +## Getting started |
| 18 | + |
| 19 | +This project automatically builds Garry's Mod Lua API [annotations for use with `LuaLS/lua-language-server`](https://github.com/LuaLS/lua-language-server/wiki/Annotations). It does this by scraping [the Garry's Mod Wiki](https://wiki.facepunch.com/gmod/). |
| 20 | + |
| 21 | +The above means that if you want to improve or correct the definitions, you'll have to either: |
| 22 | + |
| 23 | +* [Contribute to the official Garry's Mod Wiki](https://wiki.facepunch.com/gmod/#contributing) (if it contains an error) and wait until the scraper runs again (at the start of every month). |
| 24 | +* Or, if there's an error in the scraper, you can [contribute to this project](#contributing-to-this-project) and fix it yourself. |
| 25 | + |
| 26 | +The addon for Lua Language Server is seperate from this project. If you want it to be updated, you'll have to [contribute to that project according to these instructions](#updating-the-addon-for-lua-language-server). |
| 27 | + |
| 28 | +## Contributing to this project |
| 29 | + |
| 30 | +### Reporting an issue |
| 31 | + |
| 32 | +If you find an error in the scraper, please [open an issue](https://github.com/luttje/glua-api-snippets/issues/new) and describe the problem. If you can, please include a link to the page on the Garry's Mod Wiki that is incorrectly scraped. |
| 33 | + |
| 34 | +### Creating a pull request |
| 35 | + |
| 36 | +You can help the project even more by fixing the error yourself. To do this, you'll have to [fork this project](https://docs.github.com/en/get-started/quickstart/fork-a-repo), make corrections and [create a pull request](https://github.com/luttje/glua-api-snippets/compare) with your changes. Before you do that, please consider the following: |
| 37 | + |
| 38 | +* Create an issue before you start working on a pull request. This way you can get feedback on your idea before you spend time on it. |
| 39 | +* Make your changes on a seperate branch and name it according to this convention: |
| 40 | + * `bugfix/<short-bug-description>` if you're fixing a bug *(e.g. `bugfix/incorrect-argument-type`)*. |
| 41 | + * `feature/<short-feature-description>` if you're adding a new feature *(e.g. `feature/add-example-links`)*. |
| 42 | + * `docs/<short-docs-description>` if you're updating the documentation *(e.g. `docs/update-contributing-guide`)*. |
| 43 | +* Cluster changes in small commits. *This makes it easier to review your changes.* |
| 44 | +* Do not create a single PR with multiple unrelated changes. Create seperate PRs for each change. *This makes it easier to review your changes.* |
| 45 | +* Make sure your changes are correct and don't break anything. |
| 46 | +* Add tests for your changes if possible. |
| 47 | +* Clearly describe your changes (and why you made them) in the pull request description. |
| 48 | + |
| 49 | +#### Step-by-step guide to contribute to this project |
| 50 | + |
| 51 | +1. [Fork this project](https://github.com/luttje/glua-api-snippets/fork) to your own GitHub account. |
| 52 | + |
| 53 | +2. [Clone the forked project](https://docs.github.com/en/get-started/quickstart/fork-a-repo#cloning-your-forked-repository) to your local machine. |
| 54 | + |
| 55 | +3. Create a new branch for your changes, for example: |
| 56 | + |
| 57 | + ```bash |
| 58 | + git checkout -b bugfix/incorrect-argument-type |
| 59 | + ``` |
| 60 | + |
| 61 | +4. Make your changes and commit them: |
| 62 | + |
| 63 | + ```bash |
| 64 | + git add . |
| 65 | + git commit -m "Fix incorrect argument type" |
| 66 | + ``` |
| 67 | + |
| 68 | +5. Push your changes to your forked project: |
| 69 | + |
| 70 | + ```bash |
| 71 | + git push origin bugfix/incorrect-argument-type |
| 72 | + ``` |
| 73 | + |
| 74 | +6. [Create a pull request](https://github.com/luttje/glua-api-snippets/compare) with your changes. |
| 75 | + |
| 76 | +7. Wait for your pull request to be reviewed and merged. |
| 77 | + |
| 78 | +✨ **Thanks in advance for your contribution!** |
| 79 | + |
| 80 | +## Updating the addon for Lua Language Server |
| 81 | + |
| 82 | +At the first of every month the scraper runs and updates the addon for Lua Language Server to [the `lua-language-server-addon` branch in this repo](https://github.com/luttje/glua-api-snippets/tree/lua-language-server-addon). However this does not automatically update the Lua Language Server Addon, since the branch is only a sub repository in the [LuaLS/LLS-Addons repository](https://github.com/LuaLS/LLS-Addons) |
| 83 | + |
| 84 | +#### Step-by-step guide to update our addon at [`LuaLS/LLS-Addons`](https://github.com/LuaLS/LLS-Addons/) |
| 85 | + |
| 86 | +1. Go to the Lua Language Server Addons repository and take note of [their contribution guidelines](https://github.com/LuaLS/LLS-Addons/blob/main/CONTRIBUTING.md) |
| 87 | + |
| 88 | +2. [Fork the Lua Language Server Addon Repository](https://github.com/LuaLS/LLS-Addons/fork) to your own GitHub account. |
| 89 | + |
| 90 | +3. [Clone the forked project](https://docs.github.com/en/get-started/quickstart/fork-a-repo#cloning-your-forked-repository) to your local machine. |
| 91 | + |
| 92 | +4. Create a new branch for your changes, for example: |
| 93 | + |
| 94 | + ```bash |
| 95 | + git checkout -b update-garrysmod-addon |
| 96 | + ``` |
| 97 | + |
| 98 | +5. Update the `garrysmod` sub repository to the latest commit in the `lua-language-server-addon` branch in this repo: |
| 99 | + |
| 100 | + ```bash |
| 101 | + git submodule update --remote addons/garrysmod/module |
| 102 | + ``` |
| 103 | + |
| 104 | +6. Commit your changes: |
| 105 | + |
| 106 | + ```bash |
| 107 | + git add . |
| 108 | + git commit -m "Updated garrysmod addon" |
| 109 | + ``` |
| 110 | + |
| 111 | +7. Push your changes to your forked project: |
| 112 | + |
| 113 | + ```bash |
| 114 | + git push origin update-garrysmod-addon |
| 115 | + ``` |
| 116 | + |
| 117 | +8. [Create a pull request at the `LuaLS/LLS-Addons` repository](https://github.com/LuaLS/LLS-Addons/compare) with your changes. Make sure to allow edits from maintainers. |
| 118 | + |
| 119 | +9. Wait for your pull request to be reviewed and merged. |
| 120 | + |
| 121 | +✨ **Thanks in advance for your help in keeping our addon up to date!** |
0 commit comments