Contributing

🎉 First off, thanks for taking the time to contribute! 🎉

Recommendations

Before starting to work on a pull request, make sure a related issue exists or create one to discuss with the maintainers about the feature(s) you want for the project.
We use conventionalcommits.org's rules for creating explicit and meaningful commit messages.
If it's your first time contributing to a project then you should look to the popular first-contributions repository on GitHub. This will give you hands-on experience with the features of GitHub required to make a contribution. As always, feel free to join our Discord to ask any questions and clarify your understanding, we are more than happy to help!

Development

Directory Structure

The repository is structured so different components live as independently as possible.

Folder	Description
`assets`	Auto-generated previews.
`icons`	Icon SVG files for each flavour.
`scripts`	Scripts for optimizing icons, generating flavoured icons, building previews and building the extension.
`src/defaults`	Default file/folder icon associations.
`src/hooks`	Extension runtime code (commands).

Setup

We use a set of tools to build the extension and assets:

nodejs@latest as runtime.
pnpm as dependency manager.
catwalk as in-house preview generator (optional).

Scripts

We provide a set of npm scripts to make development and contribution easier:

Script	Description
`build`	Builds the extension and themes to `dist`.
`catwalk`	Generates the main preview (requires `catwalk`).
`icons:generate`	Generates missing flavoured icon SVGs in their respective flavour folder.
`icons:optimize`	Runs all SVGs through `@iconify/tools/cleanupSVG` and `svgo`.
`icons:preview`	Generates complete flavour previews from existing icons.
`pack`	Generates VSIX extension file.

Notes

The extension is written in TypeScript using ESM syntax, it is later compiled and polyfilled to CJS by tsup.
Try using the vscode API as much as possible in hooks and commands at runtime to avoid relying on native node APIs.

Design guidelines

The following guidelines are what make the icons and the theme consistent. They are the core of this repo and should be respected:

Canvas should be 16x16.
Use 1px strokes and no fill.
Use round stroke-linecap and stroke-linejoin.
Anchor points should be on entire or half values as much as possible.
Only use catppuccin colors.

Note

The design guidelines are still a work in progress. Keep in mind the decision to add an icon is ultimately that of the catppuccin maintainers and team.

Workflow examples

Make sure to run pnpm install to ensure dependencies are installed and up to date before callign any other script.

Creating new icons

Create an icon SVG for a given flavour using your favourite editor (Inkscape is perfect for this!). You can use the given templates (especially for folder icons) or existing icons as base. Make sure to repect the design guidelines.
Put the icon in its corresponding folder as icons/<flavour>/<icon-name>.svg, with naming convention as follows:
- <icon-name>.svg in kebab-case for a file icon.
- folder_<folder-name>.svg and folder_<folder-name>_open.svg for a folder icon (don't forget the open version).
Declare its default associations in the corresponding file with the <icon-name> as key of the exported object:
- src/defaults/fileIcons.ts for files.
- src/defaults/folderIcons.ts for folders.
Run pnpm icons:optimize and pnpm icons:generate and other flavours will be automatically created in their respective folders!
You can run pnpm icons:preview to regenerate flavour previews and ensure everything is looking fine.

Running the extension locally

Build the extension using pnpm build.
Run the extension host by pressing F5 or using the Extension config from the Run and debug VSCode tab.

Note

Hot reload is not supported at the moment. Extension should be rebuilt and extension host process restarted to apply changes.

🎉 Happy contributing! 🎉

4.5 KiB Raw Blame History