diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e4a86ef..b47abbc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,33 +7,36 @@ *I know that it can be annoying to adopt standard from every project but if there weren't any the project would be soon unreadable and unmaintainable.* -To have your PR merged in this repository you'll need to keep the following things in mind: +To have your PR merged more quickly you'll need to keep the following things in mind: - StyLua - While I understand that everybody is used to their code formatting I'll have to enforce StyLua. There were contributions that reformatted the whole codebase while modifying 2 lines of code. - It takes a lot of time to go through such contributions and figure out what was really changed. - - So please use StyLua (for Lua 5.1) to format your code. + It takes a lot of time to go through such contributions and figure out what was really changed + and what was their formatting tool. + - So please use StyLua (`v0.20.0`) to format your code. - LuaCheck - - LuaCheck is here to catch errors that I could overlook since I'm not that great with Lua. - Some warnings/issues may feel like small things that don't impact anything but once there's enough - issues it becomes hard to find the *real* ones in the large number of issues that *don't matter*. + - LuaCheck is here to catch errors that anyone could overlook. + Some warnings/issues may feel like small things when they basically don't impact anything + (eg. unused argument) but once there's enough issues it becomes hard to find the *real* ones + in the large number of issues that *don't matter*. - So please use LuaCheck and fix any issues/warnings you can. - Conventional commits - Everybody is used to writing commits their own way. But everybody communicates differently and - people like to commit things like: `test`, `test2`, `small changes`, ... It's then hard to figure - out what commit changed what and what parts of the codebase it affects. + people like to commit things like: `test`, `test2`, `small changes`, etc. It's then hard to figure + out what that commit actually means, what changes were made and what parts of the codebase + are affected. - Your PRs will most likely be squashed and merged so you can keep doing commit messages as you're used to. But please use Conventional commits for the PR title (and description if aplicable) for - better readability and better commit message when squashed and merged. + better readability and better commit message when the PR is squashed and merged. ### Easily use StyLua and LuaCheck If you don't want to mess around with StyLua and LuaCheck you can use [`act`](). -It's a runner for Github Actions that allows you to run the actions locally. +It's a runner for Github workflows that allows you to run them locally. -Using `act` you can run the same StyLua and LuaCheck actions that will be run on your PR before -you create it. +Using `act` you can run the same StyLua and LuaCheck workflows that will run on your PR before +it's merged. If you use `nix` and `direnv` I've setup `default.nix` and `.envrc` files in the project's root for easy environment setup. @@ -48,9 +51,9 @@ for easy environment setup. 3. Run `act` 4. Select the `Medium` image size 5. Let it run - - First time run takes longer because it needs to pull the Docker images and install the necessary - packages. My workflows utilize cache so any subsequent runs will take considerably less time unless - there's a package update. + - The initial run takes longer because it requires pulling the Docker images and installing + the necessary packages within the container. My workflows utilize cache so any subsequent runs + will take considerably less time unless there's a package update. ##### Using `act` @@ -69,6 +72,8 @@ and [Luacheck/Luacheck ] 🏁 Job succeeded ``` +if there were no issues found. + If there were issues you'll see something like this at the end of `act` output: ``` @@ -82,7 +87,7 @@ Error: Job 'Luacheck' failed ``` If both workflows fail it will show `Error: Job 'xy' failed` -only for the fist one that failed at the end. +only for the fist one that failed. ###### LuaCheck Issues @@ -97,7 +102,7 @@ If there are issues the output will have something like this: [Luacheck/Luacheck ] 🏁 Job failed ``` -To know what exactly what's wrong look a bit above in the logs and see somethings like: +To know what exactly what's wrong look a bit above in the output and see somethings like: ``` [Luacheck/Luacheck ] 🐳 docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/3] user= workdir= @@ -128,6 +133,7 @@ If there are issues the output will have something like this: ``` StyLua creates a `diff` between the expected formatting and the formatting that is used. +Look a bit above in the output to see it: ``` [StyLua/StyLua] 🐳 docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/4] user= workdir= @@ -155,5 +161,5 @@ StyLua creates a `diff` between the expected formatting and the formatting that | 12851285 | return Presence ``` -To fix these issues you can either manually modify the file using the diff or run `stylua .` and it -will apply the formatting automatically. +To fix these issues you can either manually modify the file using the diff +or you can run `stylua .` and it will apply the formatting automatically.