Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
198 lines (133 loc) · 5.41 KB

CONTRIBUTING.md

File metadata and controls

198 lines (133 loc) · 5.41 KB

Contributing to nvim-web-devicons

Thank you for your contribution!

Prerequisites

Code is formatted using stylua and linted using luacheck.

stylua

Install via your OS package manager e.g. Arch Linux:

pacman -S stylua

or using cargo:

cargo install stylua

luacheck

Install using luarocks (preferred):

luarocks install --local luacheck

or via your OS package manager e.g. Arch Linux:

pacman -S luacheck

If you experience luarocks dependency issues installing luacheck, you may need to set an older lua version e.g.

luarocks config --local lua_version 5.1

Adding Or Updating Icons

Add or update icons in lua/nvim-web-devicons/default/ directory. Build after making your changes.

Icons must be added to /default/ files only. The /light/ files are automatically generated and should not be modified.

  1. icons_by_filename.lua
  2. icons_by_file_extension.lua
  3. icons_by_operating_system.lua
  4. icons_by_desktop_environment.lua
  5. icons_by_window_manager.lua

Add the icon to table in file 1. if the icon is for a file that is always named that way, for example .gitconfig. Add the icon to table in file 2. if the icon is for all files with an extension, for example vim. Add the icon to table in files 3., 4. and 5. if the icon is from an OS, DE or WM.

Each icon must have the following structure (this is an example):

[".gitconfig"] = { icon = "", color = "#41535b", cterm_color = "0", name = "GitConfig" },

Important

Make sure each icon association occupies exactly one line.

All of the following keys are required:

  • icon glyph
  • color must contain a color in the html notation
    • it is desirable to use the "official" icon color: look at the website for a style guide or pick the colour from a logo
  • cterm_color must contain a placeholder (any number)
    • the value for cterm_color will be generated by the script in next step
  • name must only contain alphanumeric characters (don't use /, -, _)

Building

Note: Ensure your current working directory is the repo root.

Generate

Following your changes, please run:

make

This will:

  1. Install required plugins: vim-colortemplate and mini.align if necessary
  2. Generate cterm colors
  3. Generate light color variants
  4. Check style
  5. Lint
  6. Find missing filetypes

You can automatically fix any style issues via:

make style-fix

Please commit all files from lua/nvim-web-devicons/default/, lua/nvim-web-devicons/light/ and lua/nvim-web-devicons/filetypes.lua

Validate

After committing, please run:

make colors-check

This is run in CI and ensures that generation was correct by re-running it and validating that no changes were made.

Test

Run :NvimWebDeviconsHiTest to view the icons and their highlighting.

Start Neovim with TERM=xterm-256color nvim ... to test cterm.

Check with &background dark and light

Documentation

When modifying or adding API, please update Usage

Pull Request

Please reference any issues in the description e.g. "resolves #1234", which will be closed upon merge.

Please check "allow edits by maintainers" to allow nvim-web-devicons maintainers to make small changes such as documentation tweaks.

Subject

The merge commit message will be the subject of the PR.

A Conventional Commits subject will be validated by the Semantic Pull Request Subject CI job. Reference the issue to be used in the release notes e.g.

feat: add gradle icons
fix: update rust icon
feat(#192): :NvimWebDeviconsHiTest

Available types:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests or correcting existing tests
  • build: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
  • ci: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
  • chore: Other changes that don't modify src or test files
  • revert: Reverts a previous commit

If in doubt, look at previous commits.

See also The Conventional Commits ultimate cheatsheet

Browser Font

It is useful to see the actual glyphs in the pull request. That can be done by setting the browser font to your nerd font.

Using firefox:

  • Settings -> General
  • Fonts -> Advanced
  • Change Monospace to "Hack Nerd Font Mono" or similar
  • Uncheck "Allow pages to choose their own fonts, instead of your selections above"