jiriks74/presence.nvim
1
0
Fork 0
mirror of https://github.com/jiriks74/presence.nvim synced 2024-12-28 11:02:34 +01:00
Code Issues Releases Activity Actions

feat(docs): Add contributin guidelines (#51)
Some checks failed
Luacheck / Luacheck (push) Successful in 12s
Details
StyLua / StyLua (push) Failing after 12s
Details

Browse source 
* feat(docs): Add basic CONTIBUTING.md

* fix(docs): Use better wording

* feat(docs): Add Issue guidelines and ToC

* fix(ci/cd): Rename StyLuacheck to be in line with CONTRIBUTING.md

* fix(docs): Luacheck was LuaCheck

* fix(docs): Streamline the documents

* fix(docs): Formatting issues

* fix(docs): Formating issues, duplicate header

* fix(docs): Formating
This commit is contained in:
Jiří Štefka 2024-04-18 18:52:51 +02:00 committed by GitHub
parent f989f7ed50
commit 97985a95e4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 254 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/workflows/stylua.yml vendored
View file

@ -1,7 +1,7 @@
name: StyLua name: StyLua
on: [push, pull_request] on: [push, pull_request]
jobs: jobs:
StyLuacheck: StyLua:
runs-on: ubuntu-latest runs-on: ubuntu-latest
steps: steps:
- name: Update repositories - name: Update repositories

245
CONTRIBUTING.md Normal file
View file

@ -0,0 +1,245 @@
# Contributing
## Table of Contents
- [Issues](#issues)
- [Bugs/Issues](#bugsissues)
- [Feature Requests](#feature-requests)
- [Pull Requests](#pull-requests)
- [Make sure code is up to standards](#make-sure-code-is-up-to-standards)
- [Using StyLua and Luacheck directly](#using-stylua-and-luacheck-directly)
- [Using `act`](#using-act)
- [First time setup](#first-time-setup)
- [Running `act`](#running-act)
- [Luacheck Issues](#luacheck-issues)
- [StyLua Issues](#stylua-issues)
- [Assets](#assets)
## Issues
My repository uses Github's forms so it's easier to create a new issue or
feature request with all the necessary information.
When reporting a new issue or creating a feature request:
1. Check that it doesn't exist already
- Even if an issue is closed add a command and/or reopen it.
It's easier to track one issue in one
issue report than in 3.
2. Use the appropriate form
- When clicking the `New Issue` button you can either select `Issue Report`
or `Feature Request`
3. Fill out all the information
- Eg. if the form asks for logs provide them.
If you cannot provide some information say so and why.
4. Wait for feedback
- I'm a college student doing this for free.
I'll try to respond ASAP but finding time for maintaining something like
this is hard so please keep that in mind.
### Bugs/Issues
To create a new bug report just use the
[Issue Form](https://github.com/jiriks74/presence.nvim/issues/new?assignees=jiriks74&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D%3A+)
from the selection after clicking the `New Issue` button.
The form will guide you through the process.
### Feature Requests
To create a feature request just use the
[Feature Request Form](https://github.com/jiriks74/presence.nvim/issues/new?assignees=jiriks74&labels=enhancement&projects=&template=feature_request.yml&title=%5BFEAT%5D%3A+)
from the selection after clicking the `New Issue` button. The form will guide you through the process.
## Pull Requests
*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 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 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 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`, 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 the PR is squashed and merged.
### Make sure code is up to standards
#### Using StyLua and Luacheck directly
To run Luacheck use the following command in the repository's root directory:
```bash
luacheck --config .luacheckrc .
```
To format using StyLua first make sure that you're using StyLua `0.20.0`
(`stylua --version`) to prevent any formatting changes between the versions.
Then you can run the following command to format the code:
```bash
stylua .
```
#### Using `act`
If you don't want to mess around with StyLua and Luacheck you can use [`act`](https://github.com/nektos/act).
It's a runner for Github workflows that allows you to run them locally.
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.
##### First time setup
1. Install prerequisites
- `docker`
2. [Install `act`](https://nektosact.com/installation/index.html)
3. Run `act`
4. Select the `Medium` image size
5. Let it run
- 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.
##### Running `act`
Just run `act` without any arguments and it will run all the workflows in the `.github/workflows`
directory.
You should see something like:
```bash
[StyLua/StyLua] 🏁 Job succeeded
```
and
```bash
[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:
```bash
Error: Job 'StyLua' failed
```
or
```bash
Error: Job 'Luacheck' failed
```
If both workflows fail it will show `Error: Job 'xy' failed`
only for the fist one that failed.
###### Luacheck Issues
If there are issues the output will have something like this:
```bash
[Luacheck/Luacheck ] ❌ Failure - Main Luacheck linter
[Luacheck/Luacheck ] exitcode '2': failure
[Luacheck/Luacheck ] ⭐ Run Post Install Luacheck
[Luacheck/Luacheck ] 🐳 docker cp src=<dir-xy> dst=<dir-ab>
[Luacheck/Luacheck ] ✅ Success - Post Install Luacheck
[Luacheck/Luacheck ] 🏁 Job failed
```
To know what exactly what's wrong look a bit above in the output and see
somethings like:
```bash
[Luacheck/Luacheck ] 🐳 docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/3] user= workdir=
| Checking lua/lib/log.lua OK
| Checking lua/presence/discord.lua OK
| Checking lua/presence/file_assets.lua OK
| Checking lua/presence/file_explorers.lua OK
| Checking lua/presence/init.lua 1 error
|
| lua/presence/init.lua:1268:1: expected <eof> near 'end'
|
| Checking lua/presence/plugin_managers.lua OK
|
| Total: 0 warnings / 1 error in 6 files
```
###### StyLua Issues
If there are issues the output will have something like this:
```bash
[StyLua/StyLua] ❌ Failure - Main Check code formatting
[StyLua/StyLua] exitcode '1': failure
[StyLua/StyLua] ⭐ Run Post Install cargo
[StyLua/StyLua] 🐳 docker cp src=/home/jirka/.cache/act/awalsh128-cache-apt-pkgs-action@latest/ dst=/var/run/act/actions/awalsh128-cache-apt-pkgs-action@latest/
[StyLua/StyLua] ✅ Success - Post Install cargo
[StyLua/StyLua] 🏁 Job failed
```
StyLua creates a `diff` between the expected formatting
and the formatting that is used.
Look a bit above in the output to see it:
```bash
[StyLua/StyLua] 🐳 docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/4] user= workdir=
| Diff in ./lua/presence/init.lua:
| 12721272 | function Presence:handle_buf_add()
| 12731273 | self.log:debug("Handling BufAdd event...")
| 12741274 |
| 1275 |-vim.schedule(function()
| 1276 |- if vim.bo.filetype == "qf" then
| 1277 |- self.log:debug("Skipping presence update for quickfix window...")
| 1278 |- return
| 1279 |- end
| 1275 |+ vim.schedule(function()
| 1276 |+ if vim.bo.filetype == "qf" then
| 1277 |+ self.log:debug("Skipping presence update for quickfix window...")
| 1278 |+ return
| 1279 |+ end
| 12801280 |
| 1281 |- self:update()
| 1282 |-end)
| 1281 |+ self:update()
| 1282 |+ end)
| 12831283 | end
| 12841284 |
| 12851285 | return Presence
```
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.
## Assets
All the assets are in the [`file_assets.lua`](lua/presence/file_assets.lua).
If you'd like to add/modify any assets create a PR to the mentioned
[`file_assets.lua`](lua/presence/file_assets.lua).

23
README.md
View file

@ -137,26 +137,19 @@ OS may not yet be supported
## Development ## Development
- Clone the repo: `git clone https://github.com/jiriks74/presence.nvim.git` - Clone the repo: `git clone https://github.com/jiriks74/presence.nvim.git`
- Enable [logging](#configuration) and ensure that `presence.nvim` is **_not_** - Enable [logging](#configuration) and ensure that `presence.nvim` is **not**
in the list of vim plugins in your config in the list of vim plugins in your config
- Run `nvim` with your local changes: `nvim --cmd - Run `nvim` with your local changes: `nvim --cmd
'set rtp+=path/to/your/local/presence.nvim' file.txt` 'set rtp+=path/to/your/local/presence.nvim' file.txt`
- Ensure that there are no [luacheck](https://github.com/mpeterv/luacheck/) - Make sure that your contribution follows
errors: `luacheck lua` [CONTRIBUTING.md](https://github.com/jiriks74/presence.nvim/blob/main/CONTRIBUTING.md)
guidelines before creating a PR.
## Contributing ## Contributing
**Please use [Conventional Commits](https://www.conventionalcommits.org/) **Please read [CONTRIBUTING.md](https://github.com/jiriks74/presence.nvim/blob/main/CONTRIBUTING.md)
if you want to contribute. before creating a PR or an issue.**
It makes everyones jobs easier.**
**This project uses [StyLua](https://github.com/JohnnyMorganz/StyLua).
Please format your code using StyLua for better readability**
Pull requests are very welcome, feel free to open an issue to work on Pull requests are very welcome, feel free to open an issue to work on
or message [me (@jiriks74)](https://discordapp.com/users/517810049360461837) on my or [message me directly (@jiriks74)](https://discordapp.com/users/517810049360461837)
[Discord server](https://discord.gg/cCq3qcB4jB)! on my [Discord server](https://discord.gg/cCq3qcB4jB)!
Asset additions and changes are also welcome! Supported file types can be found in
[`file_assets.lua`](lua/presence/file_assets.lua) and their referenced asset files
can be found in [the `icon-assets` branch](https://github.com/jiriks74/presence.nvim/tree/icon-assets).