From 9873d2bc98242dea07912cb92dfb3de87c0a1d6d Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Sun, 1 Oct 2023 16:09:41 +0300 Subject: [PATCH] docs/contributing: move guidelines to docs webpage --- .github/CONTRIBUTING.md | 222 ++-------------------------------------- 1 file changed, 6 insertions(+), 216 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 10371c9..436a68e 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -8,7 +8,7 @@ ## Welcome -I'm glad you are thinking about contributing to neovim-flake! If you're unsure about anything, just ask -- or submit the issue or pull request anyway. The worst that can happen is you'll be politely asked to change something. Friendly contributions are always welcome. +I'm glad you are thinking about contributing to neovim-flake! If you're unsure about anything, just ask - or submit the issue or pull request anyway. The worst that can happen is you'll be politely asked to change something. Friendly contributions are always welcome. Before you contribute, I encourage you to read this project's CONTRIBUTING policy (you are here), its [LICENSE](LICENSE.md), and its [README](README.md). @@ -18,223 +18,13 @@ If you have any questions regarding those files, feel free to open an issue or [ The contribution process is mostly documented in the [pull request template](.github/pull_request_template.md). You will find a checklist of items to complete before submitting a pull request. Please make sure you complete it before submitting a pull request. If you are unsure about any of the items, please ask. -### Code of Conduct - -This project does not quite have a code of conduct yet. And to be honest, I'm not sure if I want one. I'm not expecting this project to be a hotbed of activity, but I do want to make sure that everyone who does contribute feels welcome and safe. As such, I will do my best to make sure that those who distrupt the project are dealt with swiftly and appropriately. - -If you feel that you are not being treated with respect, please contact me directly. - ### Guidelines -Here are the overall boundaries I would like you to follow while contributing to neovim-flake. +We provide instructions on a healthy contribution to neovim-flake - including styling, commit formats, how-to guides for adding new modules and options. +You are very well recommended to read the contributing guideliner over at [the documentation](https://notashelf.github.io/neovim-flake#hacking) -#### Documentation +### Code of Conduct -If you are making a pull request to add a +This project does not quite have a code of conduct yet. And to be honest, I'm not sure if I want one or if it will ever have one. I'm not expecting this project to be a hotbed of activity, but I do want to make sure that everyone who does contribute feels welcome and safe. As such, I will do my best to make sure that those who distrupt the project are dealt with swiftly and appropriately. -#### Style - -**Nix** -We use Alejandra for formatting nix code, which can be invoked directly by running `nix fmt` in the repository. - -While Alejandra is mostly opinionated on how code looks after formatting, certain formattings are done at the user's discretion. - -Please use one line code for attribute sets that contain only one subset. -For example: - -```nix -# parent modules should always be unfolded -module = { - value = mkEnableOption "some description" // { default = true; }; - # same as parent modules, unfold submodules - subModule = { - # this is an option that contains more than one nested value - someOtherValue = mkOption { - type = lib.types.bool; - description = "Some other description" - default = true; - }; - }; -} -``` - -If you move a line down after the merge operator, Alejandra will automatically unfold the whole merged attrset for you, which we do not want. - -```nix -module = { - key = mkEnableOption "some description" // { - default = true; # we want this to be inline - }; - # ... -} -``` - -For lists, it's up mostly to your discretion but please try to avoid unfolded lists if there is only one item in the list. - -```nix - -# ok -acceptableList = [ - item1 - item2 - item3 - item4 -]; - -# not ok -listToBeAvoided = [item1 item2 item3 item4]; -``` - -_This will be moved elsewhere, disregard unless you are adding a new plugin with keybinds_ - -#### Keybinds - -##### Custom key mappings support for a plugin - -To add custom keymappings to a plugin, a couple of helper functions are available in the project. - -To set a mapping, you should define it on `vim.maps.`. -The available modes are: - -- normal -- insert -- select -- visual -- terminal -- normalVisualOp -- visualOnly -- operator -- insertCommand -- lang -- command - -An example, simple keybinding, can look like this: - -```nix - -{ - vim.maps.normal = { - "wq" = { - action = ":wq"; - silent = true; - desc = "Save file and quit"; - }; - }; -} -``` - -There are many settings available in the options. Please refer to [the documentation](https://notashelf.github.io/neovim-flake/options.html#opt-vim.maps.command._name_.action) to see a list of them. - -neovim-flake provides a list of helper commands, so that you don't have to write the mapping attribute sets every time: - -`mkBinding = key: action: desc:` - makes a basic binding, with `silent` set to true. -`mkExprBinding = key: action: desc:` - makes an expression binding, with `lua`, `silent`, and `expr` set to true. -`mkLuaBinding = key: action: desc:` - makes an expression binding, with `lua`, and `silent` set to true. -Note - the lua in these bindings is _actual_ lua, not pasted into a `:lua`. -Therefore, you either pass in a function like `require('someplugin').some_function`, without actually calling it, -or you define your own function, like `function() require('someplugin').some_function() end`. - -Additionally, to not have to repeat the descriptions, there's another utility function with its own set of functions: - -```nix -# Utility function that takes two attrsets: -# { someKey = "some_value" } and -# { someKey = { description = "Some Description"; }; } -# and merges them into -# { someKey = { value = "some_value"; description = "Some Description"; }; } - -addDescriptionsToMappings = actualMappings: mappingDefinitions: -``` - -This function can be used in combination with the same mkBinding functions as above, except they only take two arguments - `binding` and `action`, and have different names. -`mkSetBinding = binding: action:` - makes a basic binding, with `silent` set to true. -`mkSetExprBinding = binding: action:` - makes an expression binding, with `lua`, `silent`, and `expr` set to true. -`mkSetLuaBinding = binding: action:` - makes an expression binding, with `lua`, and `silent` set to true. - -You can read the source code of some modules to see them in action, but their usage should look something like this: - -```nix -# plugindefinition.nix -{lib, ...}: -with lib; { - options.vim.plugin = { - enable = mkEnableOption "Enable plugin"; - - # Mappings should always be inside an attrset called mappings - mappings = { - # mkMappingOption is a helper function from lib, - # that takes a description (which will also appear in which-key), - # and a default mapping (which can be null) - toggleCurrentLine = mkMappingOption "Toggle current line comment" "gcc"; - toggleCurrentBlock = mkMappingOption "Toggle current block comment" "gbc"; - - toggleOpLeaderLine = mkMappingOption "Toggle line comment" "gc"; - toggleOpLeaderBlock = mkMappingOption "Toggle block comment" "gb"; - - toggleSelectedLine = mkMappingOption "Toggle selected comment" "gc"; - toggleSelectedBlock = mkMappingOption "Toggle selected block" "gb"; - }; - }; -} -``` - -```nix -# config.nix -{ - pkgs, - config, - lib, - ... -}: -with lib; -with builtins; let - cfg = config.vim.plugin; - self = import ./plugindefinition.nix {inherit lib;}; - mappingDefinitions = self.options.vim.plugin; - - # addDescriptionsToMappings is a helper function from lib, - # that merges mapping values and their descriptions - # into one nice attribute set - mappings = addDescriptionsToMappings cfg.mappings mappingDefinitions; -in { - config = mkIf (cfg.enable) { - # ... - - vim.maps.normal = mkMerge [ - # mkSetBinding is another helper function from lib, - # that actually adds the mapping with a description. - (mkSetBinding mappings.findFiles " Telescope find_files") - (mkSetBinding mappings.liveGrep " Telescope live_grep") - (mkSetBinding mappings.buffers " Telescope buffers") - (mkSetBinding mappings.helpTags " Telescope help_tags") - (mkSetBinding mappings.open " Telescope") - - (mkSetBinding mappings.gitCommits " Telescope git_commits") - (mkSetBinding mappings.gitBufferCommits " Telescope git_bcommits") - (mkSetBinding mappings.gitBranches " Telescope git_branches") - (mkSetBinding mappings.gitStatus " Telescope git_status") - (mkSetBinding mappings.gitStash " Telescope git_stash") - - (mkIf config.vim.lsp.enable (mkMerge [ - (mkSetBinding mappings.lspDocumentSymbols " Telescope lsp_document_symbols") - (mkSetBinding mappings.lspWorkspaceSymbols " Telescope lsp_workspace_symbols") - - (mkSetBinding mappings.lspReferences " Telescope lsp_references") - (mkSetBinding mappings.lspImplementations " Telescope lsp_implementations") - (mkSetBinding mappings.lspDefinitions " Telescope lsp_definitions") - (mkSetBinding mappings.lspTypeDefinitions " Telescope lsp_type_definitions") - (mkSetBinding mappings.diagnostics " Telescope diagnostics") - ])) - - ( - mkIf config.vim.treesitter.enable - (mkSetBinding mappings.treesitter " Telescope treesitter") - ) - ]; - - # ... - }; -} -``` - -If you have come across a plugin that has an API that doesn't seem to easily allow custom keybindings, don't be scared to implement a draft PR. We'll help you get it done. +If you feel that you are not being treated with respect, please contact me directly.