Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
130 lines (90 loc) · 4.25 KB

CONTRIBUTING.md

File metadata and controls

130 lines (90 loc) · 4.25 KB
Raw

Found an Issue?

If you have any problems, please search for [a similar issue] first, before creating a new one (don't forget to follow the issue template).

Also, check the list of known issues before doing so.

Don't forget to provide your environment details: just choose A File Icon: Environment in Command Palette and copy them.

Development

Prerequisites

The CairoSVG dependency needs the cairo library being present on the system.

Linux

sudo apt-get install libcairo2 uv

Windows

You can download the latest release of cairo.dll and place it somewhere Python can load it from.

As a last resort, Graphviz includes cairo.dll in its distribution.

Installation

Navigate to A File Icon root directory and call...

uv sync --dev

Building

Navigate to A File Icon root directory, activate python virtual environment and call...

# build everything
uv run build

# build icons only
uv run build --icons

# build icon theme files only
uv run build --theme

Want to add new icons?

If you want to add a new icon, please follow these steps:

  1. Try to find an icon in one of these resources. We always try to be pretty similar to Atom File Icons package. If you are unable to find anything – add your own.
  2. Add an example file that shows this icon to the tests folder.
  3. Provide the icon in SVG format and put it in the icons/svg directory.
  4. Add icon settings to the icons/icons.json file.
  5. Build and check if the icon looks good (Run A File Icon: Revert to a Freshly Installed State after build to apply your icon).
  6. It's recommended to add a link to the package which provides the syntax (see PACKAGES.md)

All that you need to add are the SVG icon, its settings and the example file(s).

All settings should be alphabetically sorted.

Please do not change any other files - specially in icons/colored and icons/mono folders.

Icon

Requirements:

  • The size should be 16x16 (viewBox).
  • The color should be black via fill="#000" attribute.
  • You should build and check if it looks good. If not, make some tweaks to fit the pixel grid.

Example:

ActionScript Icon

<svg xmlns="http://www.w3.org/2000/svg" fill-rule="evenodd" fill="#000" viewBox="0 0 16 16">
  <path d="M11.174,9.341A2.586,2.586,0,1,1,9.345,6.176,2.586,2.586,0,0,1,11.174,9.341Zm1.389-1.713A6.757,6.757,0,0,1,12.6,4.2,2.639,2.639,0,0,0,7.5,2.879,6.749,6.749,0,0,1,5.958,5.7a6.41,6.41,0,0,1-3,1.766,2.641,2.641,0,1,0,1.368,5.1,6.349,6.349,0,0,1,3.309-.016,6.782,6.782,0,0,1,2.985,1.776,2.611,2.611,0,0,0,3.609-.108,2.639,2.639,0,0,0,.09-3.631A6.786,6.786,0,0,1,12.562,7.628Z"/>
</svg>

Settings

Icons are applied in two different ways:

  1. by <Name>.sublime-file-icons files bypassing any syntax definitions.
  2. by scope defined by syntax definitions, if no icon theme is selected or file extension is not specified in active file icon theme.

Icon themes are generated by uv run build --icons, using icons/icons.json metadata.

{
  "file_type_awk": {
    "color": "red",
    "syntaxes": [
      {
        "extensions": [
          "awk"
        ],
        "name": "Plain Text (AWK)",
        "scope": "source.awk"
      }
    ]
  }
}

Note

"name" and scope remain for historic reasons, but they are no longer evaluated.

Generated icon themes contain mappings for all extensions listed in "extensions": [] nodes. The entry above, produces following entries in A File Icon.sublime-file-icons file.

{
  "icons": {
    "AWK": "file_type_awk",
    "awk": "file_type_awk"
  }
}

Note

Extensions are evaluated case-sensitive even on case-insensitive filesystems.