Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
199 lines (140 loc) · 5.12 KB

CONTRIBUTING.md

File metadata and controls

199 lines (140 loc) · 5.12 KB

Contributing

Thank you for your contribution! Here you will find some tips, guidelines and other resources for contributing to project.nvim.

Note For Co-Maintainers

First of all thank you for being passionate about this plugin as I am. It means the world to me.

Please follow the instructions stated below. These are not set in stone. For transparency's sake if yow have any suggestions, even regarding this very document, you may open a blank issue.

Table of Contents

Guidelines

What I Will Not Accept

  • BAD COMMIT MESSAGES. Read this guide to get familiarized
  • UNCREDITED CODE. If pulling from somewhere else, paste the reference URL in a comment
  • AI-GENERATED CODE. The code here must be up to date and made with effort
  • MISSING LUA ANNOTATIONS. See Code Annotations
  • MERGE COMMITS. Favour git rebase instead
  • UNSIGNED COMMITS. Read this guide to sign your commits.
  • UNTESTED CHANGES (if warranted). Make sure to test your changes before making a Pull Request
  • UNFORMATTED CODE. See the StyLua section
  • NON-UNIX LINE ENDINGS. Make sure to set your config in your CLI:
# If you want to enforce this only in this repository
git config --local core.autocrlf false
git config --local core.eol lf

# If you want to enforce this in your global settings
git config --global core.autocrlf false
git config --global core.eol lf

And set this in your Neovim config (recommended):

-- init.lua
vim.opt.fileformat = 'unix' -- WRONG
vim.o.fileformat = 'unix' -- CORRECT

Recommendations

StyLua

This will format any Lua file that needs it. I WILL NOT ACCEPT ANY CHANGES TO .stylua.toml, create an issue instead.

You can install StyLua through your package manager or by following these instructions.

To run it, you must be in the root of the repository. Simply run the following command:

stylua .

pre-commit

Make sure to be in the root of the repository.

I encourage you to use pre-commit to run the hooks contained in .pre-commit-config.yaml.

To install it, follow these instructions in the pre-commit website. After that, run the following command in your terminal:

pre-commit install

Now every time you run git commit the hooks contained in .pre-commit-config.yaml will run.

It is recommended for you to update the hooks if required to:

pre-commit autoupdate

You must then commit the changes to .pre-commit-config.yaml.

selene

selene is used for linting Lua code.

The configuration is already set in vim.yml and selene.toml. You only need to install it through cargo:

cargo install selene

or your package manager of preference.

To use it, just run it from the root of the repository:

selene lua/

Code Annotations

Warning

Undocumented code will be either asked for corrections or, if not willing to document, rejected.

Please refer to LuaLS' code annotations to understand the syntax.

Let's say you create a new submodule lua/project/foo.lua. If said module returns a table with fields, the optimal way to document is to do it in the same file, and following this format:

---A table that contains `foo`.
---@class Project.Foo
local Foo = {}

return Foo

If any fields are defined, preferably define them as below:

---A table that contains `foo` and more.
--- ---
---@class Project.Foo
---An **OPTIONAL** data field containing things.
--- ---
---@field things? table
local Foo = {}

---A data field containing stuff.
--- ---
Foo.stuff = 1.0 -- Or whatever data should go here

---A function that does `Foo`.
---@param x any Data containing whatever
---@param y_optional? table OPTIONAL table containing riches
function Foo.do_foo(x, y_optional)
  -- Blah blah blah
  Foo.things = true
end

---A function that does `Bar`.
--- ---
---@param verbose? boolean OPTIONAL flag that enables verbose behaviour
function Foo.do_bar(verbose)
  -- Blah blah blah
  Foo.things = false
end

-- Blah blah blah

return Foo

Bear in mind that any field that's not explicitly defined should go under the** ---@class annotation, e.g. Foo.things from above.

Any instance of wrapping already existing data types will be rejected.

---NOT ALLOWED
---@alias StringType string
---@alias Int integer

---ALLOWED
---@alias StringDict table<string, any>
---@alias IntList integer[]